api

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2024 License: AGPL-3.0 Imports: 41 Imported by: 1

README

API endpoints

Endpoints:

API Info

GET /info

Show information about the API service.

  • 📥 response:
{
    "supportedChains": [
        {
            "chainID": 5,
            "shortName": "gor",
            "name": "Goerli"
        },
        {
            "chainID": 137,
            "shortName": "matic",
            "name": "Polygon Mainnet"
        },
        {
            "chainID": 80001,
            "shortName": "maticmum",
            "name": "Mumbai"
        },
        {
            "chainID": 1,
            "shortName": "eth",
            "name": "Ethereum Mainnet"
        }
    ]
}
  • ⚠️ errors:
HTTP Status Message Internal error
500 error encoding API info 5023

Tokens

GET /tokens

List of already added tokens.

Pagination URL params

URL key Description Example
pageSize (optional) Defines the number of results per page. By default, 100. ?pageSize=2
nextCursor (optional) When is defined, it is used to get the page results, going forward. By default, "". ?nextCursor=0x1234
prevCursor (optional) When is defined, it is used to get the page results, going backwards. By default, "". ?prevCursor=0x1234

The maximus default page size is 10, but if you provide a page size of -1, the endpoint will return all the results, and it does not require to be paginated.

  • 📥 response:
{
    "tokens": [
        {
            "ID": "0x1324",
            "type": "erc20",
            "decimals": 18,
            "startBlock": 123456,
            "symbol": "$",
            "totalSupply": "21323",
            "name": "Amazing token",
            "synced": true|false,
            "defaultStrategy": 1,
            "tags": "testTag1,testTag2",
            "chainID": 1,
            "externalID": "",
            "chainAddress": "eth:0x1234",
            "iconURI": "http://...png"
        }
    ],
    "pagination": {
        "nextCursor": "",
        "prevCursor": "0x1234",
        "pageSize": 10
    }
}

If tags is empty, it will be ommited.

If externalID is empty, it will be ommited.

  • ⚠️ errors:
HTTP Status Message Internal error
204 no tokens found 4007
400 malformed pagination params 4022
500 error getting tokens information 5005
500 error encoding tokens 5011
GET /tokens/types

List the supported token types.

  • 📥 response:
{
    "supportedTypes": [
        "erc20", 
        "erc721", 
        "erc777", 
        "erc1155", 
        "nation3", 
        "wANT", 
        "poap"
    ]
}
  • ⚠️ errors:
HTTP Status Message Internal error
500 error encoding supported tokens types 5012
POST /tokens

Creates a new token in the database to be scanned. It gets the token information from the provider associated to the token type defined. If the creation success the token will be scanned in the next scanner iteration. The scan process status can be checked getting the token information.

Important: When a token is created, the API also creates a simple strategy with just the holders of that token, which is assigned to it as defaultStrategy.

  • 📤 request:
{
    "ID": "0x1234",
    "type": "erc20|erc721|erc777|erc1155|nation3|wANT|poap",
    "tags": "testTag1,testTag2",
    "chainID": 1,
    "externalID": "" // id for external holders providers
}

tags attribute is optional.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

  • ⚠️ errors:
 HTTP Status Message Internal error
400 malformed token information 4000
409 token already created 4009
400 chain ID provided not supported 4013
500 the token cannot be created 5000
500 error getting token information 5004
500 error initialising web3 client 5019
GET /tokens/{tokenID}?chainID={chainID}&externalID={externalID}

Returns the information about the token referenced by the provided ID and chain ID, the external ID is optional.

chainID URL parameter is mandatory.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

  • 📥 response:
{
    "ID": "0x1324",
    "type": "erc20",
    "size": 120,
    "decimals": 18,
    "startBlock": 123456,
    "symbol": "$",
    "totalSupply": "21323",
    "name": "Amazing token",
    "status": {
        "atBlock": 12345,
        "synced": true|false,
        "progress": 87
    },
    "defaultStrategy": 1,
    "tags": "testTag1,testTag2",
    "chainID": 1,
    "externalID": "",
    "chainAddress": "eth:0x1234",
    "iconURI": "http://...png"
}

If tags is empty, it will be ommited.

If externalID is empty, it will be ommited.

  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed token information 4001
400 malformed chain ID 4018
404 no token found 4003
500 error getting token information 5004
500 error encoding token 5010
500 chain ID provided not supported 5013
500 error initialising web3 client 5019
500 error getting number of token holders 5020
500 error getting last block number from web3 endpoint 5021
GET /tokens/{tokenID}/holders/{holderID}?chainID={chainID}&externalID={externalID}

Returns the holder balance if the holder ID is already registered in the database as a holder of the token ID and chain ID provided, the external ID is optional.

chainID URL parameter is mandatory.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

  • 📥 response:
{
    "balance": "1234567890"
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed token information 4001
400 malformed chain ID 4018
404 no token found 4003
404 token holder not found for the token provided 4023
500 error getting token holders 5006

Strategies

GET /strategies

Returns the ID's list of the strategies registered.

Pagination URL params

URL key Description Example
pageSize (optional) Defines the number of results per page. By default, 100. ?pageSize=2
nextCursor (optional) When is defined, it is used to get the page results, going forward. By default, "". ?nextCursor=3
prevCursor (optional) When is defined, it is used to get the page results, going backwards. By default, "". ?prevCursor=1

The maximus default page size is 10, but if you provide a page size of -1, the endpoint will return all the results, and it does not require to be paginated

  • 📥 response:
{
    "strategies": [
        {
            "ID": 1,
            "alias": "default MON strategy",
            "predicate": "MON",
            "uri": "ipfs://...",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                }
            }
        },
        {
            "ID": 2,
            "alias": "default ANT strategy",
            "predicate": "ANT",
            "uri": "ipfs://...",
            "tokens": {
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234" 
                }
            }
        },
        {
            "ID": 3,
            "alias": "default USDC strategy",
            "predicate": "USDC",
            "uri": "ipfs://...",
            "tokens": {
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        },
        {
            "ID": 4,
            "alias": "strategy_alias",
            "predicate": "MON AND (ANT OR USDC)",
            "uri": "ipfs://...",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                },
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234",
                    "minBalance": "1"
                },
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        }
    ],
    "pagination": {
        "nextCursor": "",
        "prevCursor": "1",
        "pageSize": 10
    }
}
  • ⚠️ errors:
HTTP Status Message Internal error
204 - 4008
400 malformed pagination params 4022
500 error getting strategies information 5008
500 error encoding strategies 5016
POST /strategies

Stores a new strategy based on the defined combination of tokens provided, these tokens must be registered previously.

  • 📤 request:
    {
        "alias": "test_strategy",
        "predicate": "(wANT OR ANT) AND USDC",
        "tokens": {
            "wANT": {
                "ID": "0x1324",
                "chainID": 1,
                "minBalance": "10000"
            },
            "ANT": {
                "ID": "0x1324",
                "chainID": 5,
            },
            "USDC": {
                "ID": "0x1324",
                "chainID": 1,
                "minBalance": "50"
            },
        }
    }
  • 📥 response:
{
    "strategyID": 1
}
  • ⚠️ errors:
HTTP Status Message Internal error
404 no token found 4003
400 malformed strategy provided 4014
400 the predicate provided is not valid 4015
400 the predicate includes tokens that are not included in the request 4016
500 error encoding strategy info 5015
500 error creating strategy 5025
POST /strategies/import/{cid}

Imports a strategy from IPFS downloading it with the cid provided in background. The strategy import will fail if the strategy tokens are not previously created in the database.

  • 📥 response:
{
    "queueID": "0123456789abcdef0123456789abcdef01234567"
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed strategy provided 4014
500 error encoding strategy info 5015
GET /strategies/import/queue/{queueID}

Returns the information of the strategy that are in the creation queue.

  • 📥 response:
{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "strategy": { /* <same_get_strategy_response> */ }
}
  • ⚠️ errors:
HTTP Status Message Internal error
404 strategy not found 4006
400 malformed queue ID 4011
500 error getting strategy information 5009
500 error encoding queue item 5022
  • ⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

GET /strategies/{strategyID}

Returns the information of the strategy related to the provided ID.

  • 📥 response:
{
    "ID": 4,
    "alias": "strategy_alias",
    "predicate": "MON AND (ANT OR USDC)",
    "uri": "ipfs://...",
    "tokens": {
        "MON": {
            "ID": "0x1234",
            "chainID": 5,
            "chainAddress": "gor:0x1234",
            "externalID": "mon_id_on_external_holder_provider"
        },
        "ANT": {
            "ID": "0x1234",
            "chainID": 1,
            "chainAddress": "eth:0x1234",
            "minBalance": "1"
        },
        "USDC": {
            "ID": "0x1234",
            "chainID": 1,
            "chainAddress": "eth:0x1234"
        }
    }
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed strategy ID, it must be an integer 4002
404 no strategy found with the ID provided 4005
500 error getting tokens information 5005
500 error getting strategy information 5007
500 error encoding strategy info 5015
GET /strategies/{strategyID}/estimation?anonymous={true|false}

Enqueue the estimation of size and time (in milliseconds) to create the census generated for the provided strategy. It also calculates the accuracy of the resulting census, it could be different to 100% if the census will be anonymous.

  • 📥 response:
{
    "queueID": "0123456789abcdef0123456789abcdef01234567",
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed strategy ID, it must be an integer 4002
500 error encoding strategy info 5015
GET /strategies/{strategyID}/estimation/queue/{queueID}

Returns the estimation of size and time (in milliseconds) to create the census generated for the strategy related to the queue ID.

  • 📥 response:
{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "estimation": {
        "size": 15000,
        "timeToCreateCensus": 10900,
        "accuracy": 100.0,
    }
}
  • ⚠️ errors:
HTTP Status Message Internal error
404 no strategy found with the ID provided 4005
400 malformed queue ID 4020
500 error encoding queue item 5022
  • ⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

HTTP Status Message Internal error
404 no strategy found with the ID provided 4005
400 the predicate provided is not valid 4015
204 strategy has not registered holders 4017
500 error getting strategy information 5007
500 error evaluating strategy predicate 5026
GET /strategies/{strategyID}/holders

Returns the list of holders with their balances for a strategy. This endpoint only works with single token strategies like default ones.

Pagination URL params

URL key Description Example
pageSize (optional) Defines the number of results per page. By default, 1000. ?pageSize=2
nextCursor (optional) When is defined, it is used to get the page results, going forward. By default, "". ?nextCursor=0x1234
prevCursor (optional) When is defined, it is used to get the page results, going backwards. By default, "". ?prevCursor=0x1234
  • 📥 response:
{
    "holders": {
        "0x1": "1",
        "0x2": "2",
        "0x3": "3",
        "0x4": "4",
        "0x...": "1000",
    },
    "pagination": {
        "nextCursor": "0x5",
        "prevCursor": "0x1",
        "pageSize": 5
    }
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed strategy ID, it must be an integer 4002
404 no token holders found 4004
404 no strategy found with the ID provided 4005
400 malformed pagination params 4022
500 error encoding token holders 5013
500 error getting strategy holders 5030
GET /strategies/token/{tokenID}?chainID={chainID}&externalID={externalID}

Returns strategies registered that includes the token provided for the chain also provided, the external token id is an optional parameter.

externalID URL parameter is optional by default, but required for external provided tokens like POAPs.

  • 📥 response:
{
    "strategies": [
        {
            "ID": 1,
            "alias": "default MON strategy",
            "predicate": "MON",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234"
                }
            }
        },
        {
            "ID": 4,
            "alias": "strategy_alias",
            "predicate": "MON AND (ANT OR USDC)",
            "tokens": {
                "MON": {
                    "ID": "0x1234",
                    "chainID": 5,
                    "chainAddress": "gor:0x1234",
                    "externalID": "mon_id_on_external_holder_provider"
                },
                "ANT": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234",
                    "minBalance": "1"
                },
                "USDC": {
                    "ID": "0x1234",
                    "chainID": 1,
                    "chainAddress": "eth:0x1234"
                }
            }
        }
    ]
}
  • ⚠️ errors:
HTTP Status Message Internal error
204 - 4008
500 error getting strategies information 5008
500 error encoding strategies 5016
POST /strategies/predicate/validate

Returns if the provided strategy predicate is valid and well-formatted. If the predicate is valid the handler returns a parsed version of the predicate as a JSON.

  • 📤 request:
{
    "predicate": "DAI AND (ANT OR ETH)"
}
  • 📥 response:
{
    "result": {
        "childs": {
            "operator": "AND",
            "tokens": [
                {
                    "literal": "DAI"
                },
                {
                    "childs": {
                        "operator": "OR",
                        "tokens": [
                            {
                                "literal": "ANT"
                            },
                            {
                                "literal": "ETH"
                            }
                        ]
                    }
                }
            ]
        }
    }
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed strategy provided 4014
400 the predicate provided is not valid 4015
500 error encoding validated strategy predicate 5024
GET /strategies/predicate/operators

Returns the list of supported operators to build strategy predicates.

  • 📥 response:
{
    "operators": [
        {
            "description": "logical operator that returns the common token holders between symbols with fixed balance to 1",
            "tag": "AND"
        },
        {
            "description": "logical operator that returns the token holders of both symbols with fixed balance to 1",
            "tag": "OR"
        }
    ]
}
  • ⚠️ errors:
HTTP Status Message Internal error
500 error encoding supported strategy predicate operators 5027

Censuses

POST /censuses

Request the creation of a new census with the strategy provided and returns the census ID.

  • 📤 request:
{
    "strategyID": 1,
    "anonymous": false
}
  • 📥 response:
{
    "queueID": "0123456789abcdef0123456789abcdef01234567"
}
  • ⚠️ errors :
HTTP Status Message Internal error
400 malformed strategy ID, it must be an integer 4002
500 error encoding census 5017
GET /censuses/{censusID}

Returns the information of the snapshots related to the provided ID.

  • 📥 response:
{ 
    "ID": 2,
    "strategyID": 1,
    "merkleRoot": "e3cb8941e25dcdb36fc21acbe5f6c5a42e0d4f89839ae94952f0ebbd9acd04ac",
    "uri": "ipfs://Qma....",
    "size": 1000,
    "weight": "200000000000000000000",
    "anonymous": true,
    "accuracy": 100.0
}
  • ⚠️ errors:
HTTP Status Message Internal error
400 malformed census ID, it must be a integer 4001
404 census not found 4006
500 error getting census information 5009
500 error encoding census 5017
GET /censuses/queue/{queueID}

Returns the information of the census that are in the creation queue.

  • 📥 response:
{
    "done": true,
    "error": {
        "code": 0,
        "error": "error message or null"
    },
    "census": { /* <same_get_census_response> */ }
}
  • ⚠️ errors:
HTTP Status Message Internal error
404 census not found 4006
400 malformed queue ID 4011
500 error getting census information 5009
500 error encoding queue item 5022
  • ⚠️ possible error values inside the body:

The request could response OK 200 and at the same time includes an error because it is an error of the enqueued process and not of the request processing).

HTTP Status Message Internal error
404 no token holders found 4004
404 no strategy found with the ID provided 4005
400 no tokens found for the strategy provided 4010
409 census already exists 4012
400 the predicate provided is not valid 4015
204 strategy has not registered holders 4017
500 error creating the census tree on the census database 5001
500 error evaluating strategy predicate 5026
GET /censuses/strategy/{strategyID}

Returns a list of censuses previously created for the strategy provided.

  • 📥 response:
{
    "censuses": [ 
        { 
            "ID": 1,
            "strategyID": 1,
            "merkleRoot": "e3cb8941e25dcdb36fc21acbe5f6c5a42e0d4f89839ae94952f0ebbd9acd04ac",
            "uri": "ipfs://Qma....",
            "size": 1000,
            "weight": "200000000000000000000",
            "anonymous": true,
            "accuracy": 100.0
        }
    ]
}
  • ⚠️ errors:
HTTP Status Message Internal error
204 - 4007
400 malformed census ID, it must be a integer 4001
404 census not found 4006
500 error getting census information 5009
500 error encoding censuses 5018

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrMalformedToken = apirest.APIerror{
		Code:       4000,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed token information"),
	}
	ErrMalformedCensusID = apirest.APIerror{
		Code:       4001,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed census ID, it must be a integer"),
	}
	ErrMalformedStrategyID = apirest.APIerror{
		Code:       4002,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed strategy ID, it must be an integer"),
	}
	ErrNotFoundToken = apirest.APIerror{
		Code:       4003,
		HTTPstatus: apirest.HTTPstatusNotFound,
		Err:        fmt.Errorf("no token found"),
	}
	ErrNotFoundTokenHolders = apirest.APIerror{
		Code:       4004,
		HTTPstatus: apirest.HTTPstatusNotFound,
		Err:        fmt.Errorf("no token holders found"),
	}
	ErrNotFoundStrategy = apirest.APIerror{
		Code:       4005,
		HTTPstatus: apirest.HTTPstatusNotFound,
		Err:        fmt.Errorf("no strategy found with the ID provided"),
	}
	ErrNotFoundCensus = apirest.APIerror{
		Code:       4006,
		HTTPstatus: apirest.HTTPstatusNotFound,
		Err:        fmt.Errorf("census not found"),
	}
	ErrNoTokens = apirest.APIerror{
		Code:       4007,
		HTTPstatus: apirest.HTTPstatusNoContent,
		Err:        fmt.Errorf("no tokens found"),
	}
	ErrNoStrategies = apirest.APIerror{
		Code:       4008,
		HTTPstatus: apirest.HTTPstatusNoContent,
		Err:        fmt.Errorf("no strategy found"),
	}
	ErrTokenAlreadyExists = apirest.APIerror{
		Code:       4009,
		HTTPstatus: http.StatusConflict,
		Err:        fmt.Errorf("token already created"),
	}
	ErrNoStrategyTokens = apirest.APIerror{
		Code:       4010,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("no tokens found for the strategy provided"),
	}
	ErrMalformedCensusQueueID = apirest.APIerror{
		Code:       4011,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed queue ID"),
	}
	ErrCensusAlreadyExists = apirest.APIerror{
		Code:       4012,
		HTTPstatus: http.StatusConflict,
		Err:        fmt.Errorf("census already exists"),
	}
	ErrChainIDNotSupported = apirest.APIerror{
		Code:       4013,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("chain ID provided not supported"),
	}
	ErrMalformedStrategy = apirest.APIerror{
		Code:       4014,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed strategy provided"),
	}
	ErrInvalidStrategyPredicate = apirest.APIerror{
		Code:       4015,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("the predicate provided is not valid"),
	}
	ErrNoEnoughtStrategyTokens = apirest.APIerror{
		Code:       4016,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("the predicate includes tokens that are not included in the request"),
	}
	ErrNoStrategyHolders = apirest.APIerror{
		Code:       4017,
		HTTPstatus: apirest.HTTPstatusNoContent,
		Err:        fmt.Errorf("strategy has not registered holders"),
	}
	ErrMalformedChainID = apirest.APIerror{
		Code:       4018,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed chain ID"),
	}
	ErrNoIPFSUri = apirest.APIerror{
		Code:       4019,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("no IPFS uri provided"),
	}
	ErrMalformedStrategyQueueID = apirest.APIerror{
		Code:       4020,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed queue ID"),
	}
	ErrMalformedHolder = apirest.APIerror{
		Code:       4021,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed holder information"),
	}
	ErrMalformedPagination = apirest.APIerror{
		Code:       4022,
		HTTPstatus: apirest.HTTPstatusBadRequest,
		Err:        fmt.Errorf("malformed pagination params"),
	}
	ErrNoTokenHolderFound = apirest.APIerror{
		Code:       4023,
		HTTPstatus: apirest.HTTPstatusNotFound,
		Err:        fmt.Errorf("token holder not found for the token provided"),
	}
	ErrCantCreateToken = apirest.APIerror{
		Code:       5000,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("the token cannot be created"),
	}
	ErrCantCreateCensus = apirest.APIerror{
		Code:       5001,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error creating the census tree on the census database"),
	}
	ErrCantAddHoldersToCensus = apirest.APIerror{
		Code:       5002,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error adding the holders to the created census"),
	}
	ErrPruningCensus = apirest.APIerror{
		Code:       5003,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error pruning the current census tree"),
	}
	ErrCantGetToken = apirest.APIerror{
		Code:       5004,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting token information"),
	}
	ErrCantGetTokens = apirest.APIerror{
		Code:       5005,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting tokens information"),
	}
	ErrCantGetTokenHolders = apirest.APIerror{
		Code:       5006,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting token holders"),
	}
	ErrCantGetStrategy = apirest.APIerror{
		Code:       5007,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting strategy information"),
	}
	ErrCantGetStrategies = apirest.APIerror{
		Code:       5008,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting strategies information"),
	}
	ErrCantGetCensus = apirest.APIerror{
		Code:       5009,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting census information"),
	}
	ErrEncodeToken = apirest.APIerror{
		Code:       5010,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding token"),
	}
	ErrEncodeTokens = apirest.APIerror{
		Code:       5011,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding tokens"),
	}
	ErrEncodeTokenTypes = apirest.APIerror{
		Code:       5012,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding supported tokens types"),
	}
	ErrEncodeTokenHolders = apirest.APIerror{
		Code:       5013,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding token holders"),
	}
	ErrEncodeStrategyHolders = apirest.APIerror{
		Code:       5014,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding strategy holders"),
	}
	ErrEncodeStrategy = apirest.APIerror{
		Code:       5015,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding strategy"),
	}
	ErrEncodeStrategies = apirest.APIerror{
		Code:       5016,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding strategies"),
	}
	ErrEncodeCensus = apirest.APIerror{
		Code:       5017,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding census"),
	}
	ErrEncodeCensuses = apirest.APIerror{
		Code:       5018,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding censuses"),
	}
	ErrInitializingWeb3 = apirest.APIerror{
		Code:       5019,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error initialising web3 client"),
	}
	ErrCantGetTokenCount = apirest.APIerror{
		Code:       5020,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting number of token holders"),
	}
	ErrCantGetLastBlockNumber = apirest.APIerror{
		Code:       5021,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting last block number from web3 endpoint"),
	}
	ErrEncodeQueueItem = apirest.APIerror{
		Code:       5022,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding queue item"),
	}
	ErrEncodeAPIInfo = apirest.APIerror{
		Code:       5023,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding API info"),
	}
	ErrEncodeValidPredicate = apirest.APIerror{
		Code:       5024,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding validated strategy predicate"),
	}
	ErrCantCreateStrategy = apirest.APIerror{
		Code:       5025,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error creating strategy"),
	}
	ErrEvalStrategyPredicate = apirest.APIerror{
		Code:       5026,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error evaluating strategy predicate"),
	}
	ErrEncodeStrategyPredicateOperators = apirest.APIerror{
		Code:       5027,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error encoding supported strategy predicate operators"),
	}
	ErrCantImportStrategy = apirest.APIerror{
		Code:       5028,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error importing strategy"),
	}
	ErrCantDeleteToken = apirest.APIerror{
		Code:       5029,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error deleting token"),
	}
	ErrCantGetStrategyHolders = apirest.APIerror{
		Code:       5030,
		HTTPstatus: apirest.HTTPstatusInternalErr,
		Err:        fmt.Errorf("error getting strategy holders"),
	}
)

Functions

func CalculateStrategyHolders added in v0.1.3 

func CalculateStrategyHolders(ctx context.Context, qdb *queries.Queries,
	providers map[uint64]providers.HolderProvider, id uint64, predicate string,
) (map[common.Address]*big.Int, *big.Int, uint64, error)

CalculateStrategyHolders function returns the holders of a strategy and the total weight of the census. It also returns the total block number of the census, which is the sum of the strategy block number or the last block number of every token chain id. To calculate the census holders, it uses the supplied predicate to filter the token holders using a lexer and evaluator. The evaluator uses the strategy operators to evaluate the predicate which uses the database queries to get the token holders and their balances, and combines them.

func CreateAndPublishCensus added in v0.1.3 

func CreateAndPublishCensus(
	db *censusdb.CensusDB, storage storagelayer.Storage, opts CensusOptions,
) (types.HexBytes, string, []byte, error)

CreateAndPublishCensus function creates a new census tree based on the options provided and publishes it to IPFS. It needs to persist it temporaly into a internal trees database. It returns the root of the tree, the IPFS URI and the tree dump.

func Init 

func Init(db *db.DB, conf Census3APIConf) (*census3API, error)

func InnerCensusID added in v0.1.3 

func InnerCensusID(blockNumber, strategyID uint64, anonymous bool) uint64

InnerCensusID generates a unique identifier by concatenating the BlockNumber, StrategyID, and a numerical representation of the Anonymous flag from a CreateCensusRequest struct. The BlockNumber and StrategyID are concatenated as they are, and the Anonymous flag is represented as 1 for true and 0 for false. This concatenated string is then converted to a uint64 to create a unique identifier.

func TimeToCreateCensus added in v0.1.3 

func TimeToCreateCensus(size uint64) uint64

TimeToCreateCensus function returns the estimated time to create a census based on the number of holders. It uses a linear regression to estimate the time to create a census based on the number of holders. The regression was calculated using the census3 data (11/24/2023).

Types

type APIInfo added in v0.1.3 

type APIInfo struct {
	SupportedChains []SupportedChain `json:"supportedChains"`
}

type CacheKey added in v0.1.3 

type CacheKey [16]byte

func EncCacheKey added in v0.1.3 

func EncCacheKey(key string) CacheKey

EncCacheKey encodes the key to a string to be used as a map key, it uses md5 to ensure the key is always the same length

type Census3APIConf 

type Census3APIConf struct {
	Hostname        string
	Port            int
	DataDir         string
	GroupKey        string
	Web3Providers   web3.NetworkEndpoints
	HolderProviders map[uint64]providers.HolderProvider
	AdminToken      string
}

type CensusOptions added in v0.1.3 

type CensusOptions struct {
	ID      uint64
	Type    models.Census_Type
	Holders map[common.Address]*big.Int
}

CensusOptions envolves the required parameters to create and publish a census merkle tree

type CensusQueueResponse added in v0.1.2 

type CensusQueueResponse struct {
	Done   bool               `json:"done"`
	Error  error              `json:"error"`
	Census *GetCensusResponse `json:"census"`
}

type CreateCensusRequest added in v0.1.2 

type CreateCensusRequest struct {
	StrategyID uint64 `json:"strategyID"`
	Anonymous  bool   `json:"anonymous"`
}

type CreateStrategyRequest added in v0.1.3 

type CreateStrategyRequest struct {
	Alias     string                    `json:"alias"`
	Predicate string                    `json:"predicate"`
	Tokens    map[string]*StrategyToken `json:"tokens"`
}

type CreateTokenRequest 

type CreateTokenRequest struct {
	ID         string `json:"ID"`
	Type       string `json:"type"`
	Tags       string `json:"tags"`
	ChainID    uint64 `json:"chainID"`
	ExternalID string `json:"externalID"`
}

type GetCensusResponse 

type GetCensusResponse struct {
	CensusID   uint64         `json:"ID"`
	StrategyID uint64         `json:"strategyID"`
	MerkleRoot types.HexBytes `json:"merkleRoot"`
	URI        string         `json:"uri"`
	Size       uint64         `json:"size"`
	Weight     string         `json:"weight"`
	Anonymous  bool           `json:"anonymous"`
	Accuracy   float64        `json:"accuracy"`
}

type GetCensusesResponse 

type GetCensusesResponse struct {
	Censuses []*GetCensusResponse `json:"censuses"`
}

type GetHoldersAtLastBlockResponse added in v0.1.3 

type GetHoldersAtLastBlockResponse struct {
	Done           bool                 `json:"done"`
	Error          error                `json:"error"`
	HoldersAtBlock *TokenHoldersAtBlock `json:"holdersAtBlock"`
}

type GetStrategiesResponse 

type GetStrategiesResponse struct {
	Strategies []*GetStrategyResponse `json:"strategies"`
	Pagination *Pagination            `json:"pagination"`
}

type GetStrategyEstimationResponse added in v0.1.3 

type GetStrategyEstimationResponse struct {
	Done       bool                `json:"done"`
	Error      error               `json:"error"`
	Estimation *StrategyEstimation `json:"estimation"`
}

type GetStrategyHoldersResponse added in v0.1.3 

type GetStrategyHoldersResponse struct {
	Holders    map[string]string `json:"holders"`
	Pagination *Pagination       `json:"pagination"`
}

type GetStrategyResponse 

type GetStrategyResponse struct {
	ID        uint64                    `json:"ID"`
	Alias     string                    `json:"alias"`
	Predicate string                    `json:"predicate"`
	URI       string                    `json:"uri,omitempty"`
	Tokens    map[string]*StrategyToken `json:"tokens"`
}

type GetStrategyToken 

type GetStrategyToken struct {
	ID         string `json:"ID"`
	Name       string `json:"name"`
	MinBalance string `json:"minBalance"`
	Method     string `json:"method"`
}

type GetTokenHolderResponse added in v0.1.3 

type GetTokenHolderResponse struct {
	Balance string `json:"balance"`
}

type GetTokenResponse 

type GetTokenResponse struct {
	ID              string                  `json:"ID"`
	Type            string                  `json:"type"`
	Decimals        uint64                  `json:"decimals"`
	StartBlock      uint64                  `json:"startBlock"`
	Symbol          string                  `json:"symbol"`
	TotalSupply     string                  `json:"totalSupply"`
	Name            string                  `json:"name"`
	Status          *GetTokenStatusResponse `json:"status"`
	Size            uint64                  `json:"size"`
	DefaultStrategy uint64                  `json:"defaultStrategy,omitempty"`
	Tags            string                  `json:"tags,omitempty"`
	ChainID         uint64                  `json:"chainID"`
	ChainAddress    string                  `json:"chainAddress"`
	ExternalID      string                  `json:"externalID,omitempty"`
	IconURI         string                  `json:"iconURI,omitempty"`
}

type GetTokenStatusResponse 

type GetTokenStatusResponse struct {
	AtBlock  uint64 `json:"atBlock"`
	Synced   bool   `json:"synced"`
	Progress int    `json:"progress"`
}

type GetTokensItemResponse added in v0.1.3 

type GetTokensItemResponse struct {
	ID              string `json:"ID"`
	Type            string `json:"type"`
	Decimals        uint64 `json:"decimals"`
	StartBlock      uint64 `json:"startBlock"`
	Symbol          string `json:"symbol"`
	TotalSupply     string `json:"totalSupply"`
	Name            string `json:"name"`
	Synced          bool   `json:"synced"`
	DefaultStrategy uint64 `json:"defaultStrategy,omitempty"`
	Tags            string `json:"tags,omitempty"`
	ChainID         uint64 `json:"chainID"`
	ChainAddress    string `json:"chainAddress"`
	ExternalID      string `json:"externalID,omitempty"`
	IconURI         string `json:"iconURI,omitempty"`
}

type GetTokensResponse 

type GetTokensResponse struct {
	Tokens     []GetTokensItemResponse `json:"tokens"`
	Pagination *Pagination             `json:"pagination"`
}

type ImportStrategyQueueResponse added in v0.1.3 

type ImportStrategyQueueResponse struct {
	Done     bool                 `json:"done"`
	Error    error                `json:"error"`
	Strategy *GetStrategyResponse `json:"strategy"`
}

type Pagination added in v0.1.3 

type Pagination struct {
	NextCursor string `json:"nextCursor"`
	PrevCursor string `json:"prevCursor"`
	PageSize   int32  `json:"pageSize"`
}

type QueueResponse added in v0.1.3 

type QueueResponse struct {
	QueueID string `json:"queueID"`
}

type StrategyEstimation added in v0.1.3 

type StrategyEstimation struct {
	Size               uint64  `json:"size"`
	TimeToCreateCensus uint64  `json:"timeToCreateCensus"`
	Accuracy           float64 `json:"accuracy"`
}

type StrategyToken added in v0.1.3 

type StrategyToken struct {
	ID           string `json:"ID"`
	ChainID      uint64 `json:"chainID"`
	MinBalance   string `json:"minBalance"`
	ChainAddress string `json:"chainAddress"`
	ExternalID   string `json:"externalID,omitempty"`
}

type SupportedChain added in v0.1.3 

type SupportedChain struct {
	ChainID   uint64 `json:"chainID"`
	ShortName string `json:"shortName"`
	Name      string `json:"name"`
}

type TokenHoldersAtBlock added in v0.1.3 

type TokenHoldersAtBlock struct {
	BlockNumber uint64            `json:"blockNumber"`
	Size        int               `json:"size"`
	Holders     map[string]string `json:"holders"`
}

type TokenHoldersResponse 

type TokenHoldersResponse struct {
	Holders map[string]string `json:"holders"`
}

type TokenTypesResponse 

type TokenTypesResponse struct {
	SupportedTypes []string `json:"supportedTypes"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.