apiclient

Documentation

Index

• Constants
• Variables
• type Doer
• type HTTPclient
  • func NewHTTPclient(addr *url.URL, bearerToken *uuid.UUID) (*HTTPclient, error)
  • func (c *HTTPclient) AllHoldersByStrategy(strategyID uint64, truncateByDecimals bool) (map[common.Address]*big.Int, error)
  • func (c *HTTPclient) BearerToken() *uuid.UUID
  • func (c *HTTPclient) Census(censusID uint64) (*api.Census, error)
  • func (c *HTTPclient) CensusesByStrategy(strategyID uint64) ([]*api.Census, error)
  • func (c *HTTPclient) CreateCensus(request *api.Census) (string, error)
  • func (c *HTTPclient) CreateCensusQueue(queueID string) (*api.CensusQueue, error)
  • func (c *HTTPclient) CreateStrategy(request *api.Strategy) (uint64, error)
  • func (c *HTTPclient) CreateToken(token *api.Token) error
  • func (c *HTTPclient) DeleteToken(tokenID string, chainID uint64, externalID string) (string, error)
  • func (c *HTTPclient) DeleteTokenQueue(tokenID string, chainID uint64, externalID, queueID string) (*api.DeleteTokenQueueResponse, error)
  • func (c *HTTPclient) HoldersByStrategy(strategyID uint64, truncateByDecimals bool) (string, error)
  • func (c *HTTPclient) HoldersByStrategyQueue(strategyID uint64, queueID string) (map[common.Address]*big.Int, bool, error)
  • func (c *HTTPclient) Info() (*api.APIInfo, error)
  • func (c *HTTPclient) Request(method string, jsonBody any, urlPath ...string) ([]byte, int, error)
  • func (c *HTTPclient) SetAuthToken(token *uuid.UUID)
  • func (c *HTTPclient) SetHostAddr(addr *url.URL) error
  • func (c *HTTPclient) Strategies(pageSize int, nextCursor, prevCursor string) ([]*api.Strategy, error)
  • func (c *HTTPclient) Strategy(strategyID uint64) (*api.Strategy, error)
  • func (c *HTTPclient) Token(tokenID string, chainID uint64, externalID string) (*api.Token, error)
  • func (c *HTTPclient) TokenHolder(tokenID string, chainID uint64, externalID, holderID string) (*big.Int, error)
  • func (c *HTTPclient) TokenTypes() ([]string, error)
  • func (c *HTTPclient) Tokens(pageSize int, nextCursor, prevCursor string) ([]*api.TokenListItem, error)

Constants

const (
	// HTTPGET is the method string used for calling Request()
	HTTPGET = http.MethodGet
	// HTTPPOST is the method string used for calling Request()
	HTTPPOST = http.MethodPost
	// HTTPDELETE is the method string used for calling
	HTTPDELETE = http.MethodDelete
)

const (

	// GetTokensURI is the URI for getting tokens, it accepts a pageSize,
	// nextCursor and prevCursor
	GetTokensURI = "/tokens?pageSize=%d&nextCursor=%s&prevCursor=%s"
	// CreateTokenURI is the URI for creating a token, it not accepts any
	// parameters
	CreateTokensURI = "/tokens"
	// GetAndDeleteTokenURI is the URI for getting and launchin a token
	// deletion, it accepts the tokenID, chainID and externalID
	GetAndDeleteTokenURI = "/tokens/%s?chainID=%d&externalID=%s"
	// DeleteTokenQueueURI is the URI for deleting a token from a queue, it
	// accepts the tokenID, queueID, chainID and externalID
	DeleteTokenQueueURI = "/tokens/%s/queue/%s?chainID=%d&externalID=%s"
	// GetTokenHolderURI is the URI for getting token holders, it accepts
	// the tokenID, holderID, chainID and externalID
	GetTokenHolderURI = "/tokens/%s/holders/%s?chainID=%d&externalID=%s"
	// GetTokenTypes is the URI for getting token types, it accepts no
	// parameters
	GetTokenTypes = "/tokens/types"

	// GetStrategiesURI is the URI for getting strategies, it accepts a pageSize,
	// nextCursor and prevCursor
	GetStrategiesURI = "/strategies?pageSize=%d&nextCursor=%s&prevCursor=%s"
	// GetStrategyURI is the URI for getting a strategy, it accepts the strategyID
	GetStrategyURI = "/strategies/%d"
	// CreateStrategyURI is the URI for creating a strategy, it accepts no
	// parameters
	CreateStrategyURI = "/strategies"
	// GetTokenHoldersByStrategyURI is the URI for getting token holders of a given strategy
	GetTokenHoldersByStrategyURI = "/strategies/%d/holders?truncateByDecimals=%s"
	// GetTokenHoldersByStrategyURI is the URI for getting token holders of a given strategy
	GetTokenHoldersByStrategyQueueURI = "/strategies/%d/holders/queue/%s"

	// GetCensusURI is the URI for getting a census, it accepts the censusID
	GetCensusURI = "/censuses/%d"
	// CreateCensusURI is the URI for creating a census, it accepts no
	// parameters
	CreateCensusURI = "/censuses"
	// CreateCensusQueueURI is the URI for creating a census queue, it
	// accepts the queueID
	CreateCensusQueueURI = "/censuses/queue/%s"
	// GetCensusesByStrategyURI is the URI for getting the censuses of a
	// strategy, it accepts the strategyID
	GetCensusesByStrategyURI = "/censuses/strategy/%d"
)

Variables

var (
	// ErrBadInputs is returned when bad inputs are provided to a method. Each
	// method will specify the inputs it expects and the conditions they must
	// meet.
	ErrBadInputs = fmt.Errorf("bad inputs provided")
	// ErrConstructingURL is returned when there is an error constructing the URL
	// to make a request to the API. The final URL is parsed and this process can
	// fail.
	ErrConstructingURL = fmt.Errorf("error constructing URL")
	// ErrEncodingRequest is returned when there is an error encoding the request
	// body to be sent to the API. The request body is encoded to JSON and this
	// process can fail.
	ErrEncodingRequest = fmt.Errorf("error encoding request")
	// ErrCreatingRequest is returned when there is an error creating the request
	// to be sent to the API. It will include the error returned by the
	// http.NewRequest
	ErrCreatingRequest = fmt.Errorf("error creating request")
	// ErrMakingRequest is returned when there is an error making the request to
	// the API. It will include the error returned by the http.Client.Do
	ErrMakingRequest = fmt.Errorf("error making request")
	// ErrNoStatusOk is returned when the server returns a non-OK status code.
	ErrNoStatusOk = fmt.Errorf("server returned non-OK status")
	// ErrDecodingResponse is returned when there is an error decoding the response
	// from the API. The response is decoded from JSON and this process can fail.
	ErrDecodingResponse = fmt.Errorf("error decoding response")
	// ErrAlreadyExists is returned when the resource already exists
	ErrAlreadyExists = fmt.Errorf("resource already exists")
)

Types

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

type HTTPclient

type HTTPclient struct {
	// contains filtered or unexported fields
}

HTTPclient is the Census3 API HTTP client.

func NewHTTPclient

func NewHTTPclient(addr *url.URL, bearerToken *uuid.UUID) (*HTTPclient, error)

NewHTTPclient creates a new HTTP(s) API Census3 client.

func (*HTTPclient) AllHoldersByStrategy

func (c *HTTPclient) AllHoldersByStrategy(strategyID uint64, truncateByDecimals bool) (map[common.Address]*big.Int, error)

AllHoldersByStrategy method queries the API for all the holders of a strategy, it receives the strategyID and returns a map of addresses and amounts and an error if something went wrong. This method is a wrapper around the HoldersByStrategy and HoldersByStrategyQueue methods. If truncateByDecimals is true, the amounts will be truncated by the decimals of the token (if > 0). Truncate only works for simple strategies (single token).

func (*HTTPclient) BearerToken

func (c *HTTPclient) BearerToken() *uuid.UUID

BearerToken returns the current bearer authentication token.

func (*HTTPclient) Census

func (c *HTTPclient) Census(censusID uint64) (*api.Census, error)

Census method returns a census by its ID from the API, it receives the censusID and returns a pointer to a GetCensusResponse and an error if something went wrong.

func (*HTTPclient) CensusesByStrategy

func (c *HTTPclient) CensusesByStrategy(strategyID uint64) ([]*api.Census, error)

CensusesByStrategy method returns the censuses of a strategy from the API, it receives the strategyID and returns a slice of GetCensusResponse pointers and an error if something went wrong.

func (*HTTPclient) CreateCensus

func (c *HTTPclient) CreateCensus(request *api.Census) (string, error)

CreateCensus method creates a new census from the API, it receives a CreateCensusRequest and returns a queueID and an error if something went wrong. The queueID is used to check the status of the census creation process, it can be checked with the CreateCensusQueue method.

func (*HTTPclient) CreateCensusQueue

func (c *HTTPclient) CreateCensusQueue(queueID string) (*api.CensusQueue, error)

CreateCensusQueue method checks the status of a census creation process from the API, it receives a queueID and returns a pointer to a CensusQueueResponse and an error if something went wrong.

func (*HTTPclient) CreateStrategy

func (c *HTTPclient) CreateStrategy(request *api.Strategy) (uint64, error)

CreateStrategy method sends a request to the API to create a new strategy, it receives the strategy data and returns the strategyID and an error if something went wrong.

func (*HTTPclient) CreateToken

func (c *HTTPclient) CreateToken(token *api.Token) error

CreateToken method creates a token in the API, it accepts a token to be created. The minimun required token attributes are: ID, type and chainID. Optional attributes: externalID, tags. If something goes wrong, it will return an error.

func (*HTTPclient) DeleteToken

func (c *HTTPclient) DeleteToken(tokenID string, chainID uint64, externalID string) (string, error)

DeleteToken method deletes a token in the API, it accepts the tokenID, chainID and externalID. If something goes wrong, it will return an error. It returns the queueID, that can be used to check the status of the deletion process using the DeleteTokenQueue method.

func (*HTTPclient) DeleteTokenQueue

func (c *HTTPclient) DeleteTokenQueue(tokenID string, chainID uint64, externalID,
	queueID string,
) (*api.DeleteTokenQueueResponse, error)

DeleteTokenQueue method checks the status of the deletion process of a token in the API, it accepts the tokenID, queueID, chainID and externalID. If something goes wrong, it will return an error. It returns the delete queue response.

func (*HTTPclient) HoldersByStrategy

func (c *HTTPclient) HoldersByStrategy(strategyID uint64, truncateByDecimals bool) (string, error)

HoldersByStrategy method queries the API for the holders of a strategy, it receives the strategyID and returns the queueID of the task and an error if something went wrong. The status of the task can be checked with the HoldersByStrategyQueue method. If truncateByDecimals is true, the amounts will be truncated by the decimals of the token (if > 0). Truncate only works for simple strategies (single token).

func (*HTTPclient) HoldersByStrategyQueue

func (c *HTTPclient) HoldersByStrategyQueue(strategyID uint64, queueID string) (
	map[common.Address]*big.Int, bool, error,
)

HoldersByStrategyQueue method checks the status of the query for the holders of a strategy from the API, it receives the strategyID and the queueID and returns a map of addresses and amounts, a boolean indicating if the queue task is completed and an error if something went wrong.

func (*HTTPclient) Info

func (c *HTTPclient) Info() (*api.APIInfo, error)

Info returns the API server info.

func (*HTTPclient) Request

func (c *HTTPclient) Request(method string, jsonBody any, urlPath ...string) ([]byte, int, error)

Request performs a `method` type raw request to the endpoint specified in urlPath parameter. Method is either GET or POST. If POST, a JSON struct should be attached. Returns the response, the status code and an error.

func (*HTTPclient) SetAuthToken

func (c *HTTPclient) SetAuthToken(token *uuid.UUID)

SetAuthToken configures the bearer authentication token.

func (*HTTPclient) SetHostAddr

func (c *HTTPclient) SetHostAddr(addr *url.URL) error

SetHostAddr configures the host address of the API server.

func (*HTTPclient) Strategies

func (c *HTTPclient) Strategies(pageSize int, nextCursor, prevCursor string) (
	[]*api.Strategy, error,
)

func (*HTTPclient) Strategy

func (c *HTTPclient) Strategy(strategyID uint64) (*api.Strategy, error)

func (*HTTPclient) Token

func (c *HTTPclient) Token(tokenID string, chainID uint64, externalID string) (*api.Token, error)

Token method returns a token from the API, it accepts the tokenID, chainID and externalID. If something goes wrong, it will return an error.

func (*HTTPclient) TokenHolder

func (c *HTTPclient) TokenHolder(tokenID string, chainID uint64, externalID, holderID string) (*big.Int, error)

TokenHolder method returns the balance of a token holder from the API, it accepts the tokenID, chainID, externalID and holderID. If something goes wrong, it will return an error.

func (*HTTPclient) TokenTypes

func (c *HTTPclient) TokenTypes() ([]string, error)

TokenTypes method returns the supported token types from the API. If something goes wrong, it will return an error. It returns the supported token types as a slice of strings.

func (*HTTPclient) Tokens

func (c *HTTPclient) Tokens(pageSize int, nextCursor, prevCursor string) ([]*api.TokenListItem, error)

Tokens method returns a list of tokens from the API, it accepts a pageSize, nextCursor and prevCursor. If the pageSize is -1 and cursors are empty, it will return all the tokens. If something goes wrong, it will return an error.