client

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2022 License: Apache-2.0 Imports: 15 Imported by: 15

README

Client

GoDoc

The Client package reduces the work required to communicate with a Rosetta server.

If you want a higher-level interface that automatically asserts that server responses are correct, check out the Fetcher.

Installation

go get github.com/coinbase/rosetta-sdk-go/client

Examples

Check out the examples to see how easy it is to connect to a Rosetta server.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ContextOAuth2 takes an oauth2.TokenSource as authentication for the request.
	ContextOAuth2 = contextKey("token")

	// ContextBasicAuth takes BasicAuth as authentication for the request.
	ContextBasicAuth = contextKey("basic")

	// ContextAccessToken takes a string oauth2 access token as authentication for the request.
	ContextAccessToken = contextKey("accesstoken")

	// ContextAPIKey takes an APIKey as authentication for the request
	ContextAPIKey = contextKey("apikey")
)
View Source 
var (

	// ErrRetriable is returned when a 502, 503, or 504 HTTP code is encountered.
	// These status codes may be returned by intermediate services when a Rosetta
	// implementation is overloaded and should not be considered failures.
	ErrRetriable = errors.New("retriable http status code received")
)

Functions

This section is empty.

Types

type APIClient 

type APIClient struct {
	AccountAPI *AccountAPIService

	BlockAPI *BlockAPIService

	CallAPI *CallAPIService

	ConstructionAPI *ConstructionAPIService

	EventsAPI *EventsAPIService

	MempoolAPI *MempoolAPIService

	NetworkAPI *NetworkAPIService

	SearchAPI *SearchAPIService
	// contains filtered or unexported fields
}

APIClient manages communication with the Rosetta API v1.4.12 In most cases there should be only one, shared, APIClient.

func NewAPIClient 

func NewAPIClient(cfg *Configuration) *APIClient

NewAPIClient creates a new API client. Requires a userAgent string describing your application. optionally a custom http.Client to allow for advanced features such as caching.

func (*APIClient) ChangeBasePath 

func (c *APIClient) ChangeBasePath(path string)

ChangeBasePath changes base path to allow switching to mocks

func (*APIClient) GetConfig 

func (c *APIClient) GetConfig() *Configuration

GetConfig allows for modification of underlying config for alternate implementations and testing Caution: modifying the configuration while live can cause data races and potentially unwanted behavior

type APIKey 

type APIKey struct {
	Key    string
	Prefix string
}

APIKey provides API key based authentication to a request passed via context using ContextAPIKey

type APIResponse 

type APIResponse struct {
	*http.Response `json:"-"`
	Message        string `json:"message,omitempty"`
	// Operation is the name of the OpenAPI operation.
	Operation string `json:"operation,omitempty"`
	// RequestURL is the request URL. This value is always available, even if the
	// embedded *http.Response is nil.
	RequestURL string `json:"url,omitempty"`
	// Method is the HTTP method used for the request.  This value is always
	// available, even if the embedded *http.Response is nil.
	Method string `json:"method,omitempty"`
	// Payload holds the contents of the response body (which may be nil or empty).
	// This is provided here as the raw response.Body() reader will have already
	// been drained.
	Payload []byte `json:"-"`
}

APIResponse stores the API response returned by the server.

func NewAPIResponse 

func NewAPIResponse(r *http.Response) *APIResponse

NewAPIResponse returns a new APIResonse object.

func NewAPIResponseWithError 

func NewAPIResponseWithError(errorMessage string) *APIResponse

NewAPIResponseWithError returns a new APIResponse object with the provided error message.

type AccountAPIService 

type AccountAPIService service

AccountAPIService AccountAPI service

func (*AccountAPIService) AccountBalance 

func (a *AccountAPIService) AccountBalance(
	ctx _context.Context,
	accountBalanceRequest *types.AccountBalanceRequest,
) (*types.AccountBalanceResponse, *types.Error, error)

AccountBalance Get an array of all AccountBalances for an AccountIdentifier and the BlockIdentifier at which the balance lookup was performed. The BlockIdentifier must always be returned because some consumers of account balance data need to know specifically at which block the balance was calculated to compare balances they compute from operations with the balance returned by the node. It is important to note that making a balance request for an account without populating the SubAccountIdentifier should not result in the balance of all possible SubAccountIdentifiers being returned. Rather, it should result in the balance pertaining to no SubAccountIdentifiers being returned (sometimes called the liquid balance). To get all balances associated with an account, it may be necessary to perform multiple balance requests with unique AccountIdentifiers. It is also possible to perform a historical balance lookup (if the server supports it) by passing in an optional BlockIdentifier.

func (*AccountAPIService) AccountCoins added in v0.6.0 

func (a *AccountAPIService) AccountCoins(
	ctx _context.Context,
	accountCoinsRequest *types.AccountCoinsRequest,
) (*types.AccountCoinsResponse, *types.Error, error)

AccountCoins Get an array of all unspent coins for an AccountIdentifier and the BlockIdentifier at which the lookup was performed. If your implementation does not support coins (i.e. it is for an account-based blockchain), you do not need to implement this endpoint. If you implementation does support coins (i.e. it is fro a UTXO-based blockchain), you MUST also complete the /account/balance endpoint. It is important to note that making a coins request for an account without populating the SubAccountIdentifier should not result in the coins of all possible SubAccountIdentifiers being returned. Rather, it should result in the coins pertaining to no SubAccountIdentifiers being returned. To get all coins associated with an account, it may be necessary to perform multiple coin requests with unique AccountIdentifiers. Optionally, an implementation may choose to support updating an AccountIdentifier's unspent coins based on the contents of the mempool. Note, using this functionality breaks any guarantee of idempotency.

type BasicAuth 

type BasicAuth struct {
	UserName string `json:"userName,omitempty"`
	Password string `json:"password,omitempty"`
}

BasicAuth provides basic http authentication to a request passed via context using ContextBasicAuth

type BlockAPIService 

type BlockAPIService service

BlockAPIService BlockAPI service

func (*BlockAPIService) Block 

func (a *BlockAPIService) Block(
	ctx _context.Context,
	blockRequest *types.BlockRequest,
) (*types.BlockResponse, *types.Error, error)

Block Get a block by its Block Identifier. If transactions are returned in the same call to the node as fetching the block, the response should include these transactions in the Block object. If not, an array of Transaction Identifiers should be returned so /block/transaction fetches can be done to get all transaction information. When requesting a block by the hash component of the BlockIdentifier, this request MUST be idempotent: repeated invocations for the same hash-identified block must return the exact same block contents. No such restriction is imposed when requesting a block by height, given that a chain reorg event might cause the specific block at height n to be set to a different one.

func (*BlockAPIService) BlockTransaction 

func (a *BlockAPIService) BlockTransaction(
	ctx _context.Context,
	blockTransactionRequest *types.BlockTransactionRequest,
) (*types.BlockTransactionResponse, *types.Error, error)

BlockTransaction Get a transaction in a block by its Transaction Identifier. This endpoint should only be used when querying a node for a block does not return all transactions contained within it. All transactions returned by this endpoint must be appended to any transactions returned by the /block method by consumers of this data. Fetching a transaction by hash is considered an Explorer Method (which is classified under the Future Work section). This method can be used to let consumers to paginate results when the block trasactions count is too big to be returned in a single BlockResponse. Calling this endpoint requires reference to a BlockIdentifier because transaction parsing can change depending on which block contains the transaction. For example, in Bitcoin it is necessary to know which block contains a transaction to determine the destination of fee payments. Without specifying a block identifier, the node would have to infer which block to use (which could change during a re-org). Implementations that require fetching previous transactions to populate the response (ex: Previous UTXOs in Bitcoin) may find it useful to run a cache within the Rosetta server in the /data directory (on a path that does not conflict with the node).

type CallAPIService added in v0.5.0 

type CallAPIService service

CallAPIService CallAPI service

func (*CallAPIService) Call added in v0.5.0 

func (a *CallAPIService) Call(
	ctx _context.Context,
	callRequest *types.CallRequest,
) (*types.CallResponse, *types.Error, error)

Call Call invokes an arbitrary, network-specific procedure call with network-specific parameters. The guidance for what this endpoint should or could do is purposely left vague. In Ethereum, this could be used to invoke eth_call to implement an entire Rosetta API interface for some smart contract that is not parsed by the implementation creator (like a DEX). This endpoint could also be used to provide access to data that does not map to any Rosetta models instead of requiring an integrator to use some network-specific SDK and call some network-specific endpoint (like surfacing staking parameters). Call is NOT a replacement for implementing Rosetta API endpoints or mapping network-specific data to Rosetta models. Rather, it enables developers to build additional Rosetta API interfaces for things they care about without introducing complexity into a base-level Rosetta implementation. Simply put, imagine that the average integrator will use layered Rosetta API implementations that each surfaces unique data.

type Configuration 

type Configuration struct {
	BasePath      string            `json:"basePath,omitempty"`
	Host          string            `json:"host,omitempty"`
	Scheme        string            `json:"scheme,omitempty"`
	DefaultHeader map[string]string `json:"defaultHeader,omitempty"`
	UserAgent     string            `json:"userAgent,omitempty"`
	Debug         bool              `json:"debug,omitempty"`
	Servers       []ServerConfiguration
	HTTPClient    *http.Client
}

Configuration stores the configuration of the API client

func NewConfiguration 

func NewConfiguration(basePath string, userAgent string, httpClient *http.Client) *Configuration

NewConfiguration returns a new Configuration object

func (*Configuration) AddDefaultHeader 

func (c *Configuration) AddDefaultHeader(key string, value string)

AddDefaultHeader adds a new HTTP header to the default header in the request

func (*Configuration) ServerURL 

func (c *Configuration) ServerURL(index int, variables map[string]string) (string, error)

ServerURL returns URL based on server settings

type ConstructionAPIService 

type ConstructionAPIService service

ConstructionAPIService ConstructionAPI service

func (*ConstructionAPIService) ConstructionCombine added in v0.3.0 

func (a *ConstructionAPIService) ConstructionCombine(
	ctx _context.Context,
	constructionCombineRequest *types.ConstructionCombineRequest,
) (*types.ConstructionCombineResponse, *types.Error, error)

ConstructionCombine Combine creates a network-specific transaction from an unsigned transaction and an array of provided signatures. The signed transaction returned from this method will be sent to the /construction/submit endpoint by the caller.

func (*ConstructionAPIService) ConstructionDerive added in v0.3.0 

func (a *ConstructionAPIService) ConstructionDerive(
	ctx _context.Context,
	constructionDeriveRequest *types.ConstructionDeriveRequest,
) (*types.ConstructionDeriveResponse, *types.Error, error)

ConstructionDerive Derive returns the AccountIdentifier associated with a public key. Blockchains that require an on-chain action to create an account should not implement this method.

func (*ConstructionAPIService) ConstructionHash added in v0.3.0 

func (a *ConstructionAPIService) ConstructionHash(
	ctx _context.Context,
	constructionHashRequest *types.ConstructionHashRequest,
) (*types.TransactionIdentifierResponse, *types.Error, error)

ConstructionHash TransactionHash returns the network-specific transaction hash for a signed transaction.

func (*ConstructionAPIService) ConstructionMetadata added in v0.1.2 

func (a *ConstructionAPIService) ConstructionMetadata(
	ctx _context.Context,
	constructionMetadataRequest *types.ConstructionMetadataRequest,
) (*types.ConstructionMetadataResponse, *types.Error, error)

ConstructionMetadata Get any information required to construct a transaction for a specific network. Metadata returned here could be a recent hash to use, an account sequence number, or even arbitrary chain state. The request used when calling this endpoint is created by calling /construction/preprocess in an offline environment. You should NEVER assume that the request sent to this endpoint will be created by the caller or populated with any custom parameters. This must occur in /construction/preprocess. It is important to clarify that this endpoint should not pre-construct any transactions for the client (this should happen in /construction/payloads). This endpoint is left purposely unstructured because of the wide scope of metadata that could be required.

func (*ConstructionAPIService) ConstructionParse added in v0.3.0 

func (a *ConstructionAPIService) ConstructionParse(
	ctx _context.Context,
	constructionParseRequest *types.ConstructionParseRequest,
) (*types.ConstructionParseResponse, *types.Error, error)

ConstructionParse Parse is called on both unsigned and signed transactions to understand the intent of the formulated transaction. This is run as a sanity check before signing (after /construction/payloads) and before broadcast (after /construction/combine).

func (*ConstructionAPIService) ConstructionPayloads added in v0.3.0 

func (a *ConstructionAPIService) ConstructionPayloads(
	ctx _context.Context,
	constructionPayloadsRequest *types.ConstructionPayloadsRequest,
) (*types.ConstructionPayloadsResponse, *types.Error, error)

ConstructionPayloads Payloads is called with an array of operations and the response from /construction/metadata. It returns an unsigned transaction blob and a collection of payloads that must be signed by particular AccountIdentifiers using a certain SignatureType. The array of operations provided in transaction construction often times can not specify all \effects\ of a transaction (consider invoked transactions in Ethereum). However, they can deterministically specify the \intent\ of the transaction, which is sufficient for construction. For this reason, parsing the corresponding transaction in the Data API (when it lands on chain) will contain a superset of whatever operations were provided during construction.

func (*ConstructionAPIService) ConstructionPreprocess added in v0.3.0 

func (a *ConstructionAPIService) ConstructionPreprocess(
	ctx _context.Context,
	constructionPreprocessRequest *types.ConstructionPreprocessRequest,
) (*types.ConstructionPreprocessResponse, *types.Error, error)

ConstructionPreprocess Preprocess is called prior to /construction/payloads to construct a request for any metadata that is needed for transaction construction given (i.e. account nonce). The options object returned from this endpoint will be sent to the /construction/metadata endpoint UNMODIFIED by the caller (in an offline execution environment). If your Construction API implementation has configuration options, they MUST be specified in the /construction/preprocess request (in the metadata field).

func (*ConstructionAPIService) ConstructionSubmit added in v0.1.2 

func (a *ConstructionAPIService) ConstructionSubmit(
	ctx _context.Context,
	constructionSubmitRequest *types.ConstructionSubmitRequest,
) (*types.TransactionIdentifierResponse, *types.Error, error)

ConstructionSubmit Submit a pre-signed transaction to the node. This call should not block on the transaction being included in a block. Rather, it should return immediately with an indication of whether or not the transaction was included in the mempool. The transaction submission response should only return a 200 status if the submitted transaction could be included in the mempool. Otherwise, it should return an error.

type EventsAPIService added in v0.6.0 

type EventsAPIService service

EventsAPIService EventsAPI service

func (*EventsAPIService) EventsBlocks added in v0.6.0 

func (a *EventsAPIService) EventsBlocks(
	ctx _context.Context,
	eventsBlocksRequest *types.EventsBlocksRequest,
) (*types.EventsBlocksResponse, *types.Error, error)

EventsBlocks /events/blocks allows the caller to query a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state. Following BlockEvents allows lightweight clients to update their state without needing to implement their own syncing logic (like finding the common parent in a reorg). /events/blocks is considered an \indexer\ endpoint and Rosetta implementations are not required to complete it to adhere to the Rosetta spec. However, any Rosetta \indexer\ MUST support this endpoint.

type MempoolAPIService 

type MempoolAPIService service

MempoolAPIService MempoolAPI service

func (*MempoolAPIService) Mempool 

func (a *MempoolAPIService) Mempool(
	ctx _context.Context,
	networkRequest *types.NetworkRequest,
) (*types.MempoolResponse, *types.Error, error)

Mempool Get all Transaction Identifiers in the mempool

func (*MempoolAPIService) MempoolTransaction 

func (a *MempoolAPIService) MempoolTransaction(
	ctx _context.Context,
	mempoolTransactionRequest *types.MempoolTransactionRequest,
) (*types.MempoolTransactionResponse, *types.Error, error)

MempoolTransaction Get a transaction in the mempool by its Transaction Identifier. This is a separate request than fetching a block transaction (/block/transaction) because some blockchain nodes need to know that a transaction query is for something in the mempool instead of a transaction in a block. Transactions may not be fully parsable until they are in a block (ex: may not be possible to determine the fee to pay before a transaction is executed). On this endpoint, it is ok that returned transactions are only estimates of what may actually be included in a block.

type NetworkAPIService 

type NetworkAPIService service

NetworkAPIService NetworkAPI service

func (*NetworkAPIService) NetworkList added in v0.1.2 

func (a *NetworkAPIService) NetworkList(
	ctx _context.Context,
	metadataRequest *types.MetadataRequest,
) (*types.NetworkListResponse, *types.Error, error)

NetworkList This endpoint returns a list of NetworkIdentifiers that the Rosetta server supports.

func (*NetworkAPIService) NetworkOptions added in v0.1.2 

func (a *NetworkAPIService) NetworkOptions(
	ctx _context.Context,
	networkRequest *types.NetworkRequest,
) (*types.NetworkOptionsResponse, *types.Error, error)

NetworkOptions This endpoint returns the version information and allowed network-specific types for a NetworkIdentifier. Any NetworkIdentifier returned by /network/list should be accessible here. Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network.

func (*NetworkAPIService) NetworkStatus 

func (a *NetworkAPIService) NetworkStatus(
	ctx _context.Context,
	networkRequest *types.NetworkRequest,
) (*types.NetworkStatusResponse, *types.Error, error)

NetworkStatus This endpoint returns the current status of the network requested. Any NetworkIdentifier returned by /network/list should be accessible here.

type SearchAPIService added in v0.6.0 

type SearchAPIService service

SearchAPIService SearchAPI service

func (*SearchAPIService) SearchTransactions added in v0.6.0 

func (a *SearchAPIService) SearchTransactions(
	ctx _context.Context,
	searchTransactionsRequest *types.SearchTransactionsRequest,
) (*types.SearchTransactionsResponse, *types.Error, error)

SearchTransactions /search/transactions allows the caller to search for transactions that meet certain conditions. Some conditions include matching a transaction hash, containing an operation with a certain status, or containing an operation that affects a certain account. /search/transactions is considered an \indexer\ endpoint and Rosetta implementations are not required to complete it to adhere to the Rosetta spec. However, any Rosetta \indexer\ MUST support this endpoint.

type ServerConfiguration 

type ServerConfiguration struct {
	URL         string
	Description string
	Variables   map[string]ServerVariable
}

ServerConfiguration stores the information about a server

type ServerVariable 

type ServerVariable struct {
	Description  string
	DefaultValue string
	EnumValues   []string
}

ServerVariable stores the information about a server variable

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.