DfuseClient | @dfuse/client

The DfuseClient interface is the back-bone of the library. Based on the Facade pattern, this client is your single go to point for interacting with dfuse Stream API as well as the dfuse REST API.

The client contains only top-level methods enabling you to retrieve all the information you need for your next-gen blockchain project.

The dfuse Client takes care for you of:

Management of WebSocket connection (automatic connection/disconnection when needed).
Management of the API key (API token retrieval, freshness and persistence).
Abstract dfuse API into simple to use top-level methods.
Error handling wrapping error received via WebSocket and REST into easy to use error.

group: Interfaces

Hierarchy

DfuseClient

Implemented by

DefaultClient

Properties

Readonly endpoints

endpoints: DfuseClientEndpoints

Returns the final resolved endpoints urls currenctly in used by the client to reach dfuse services.

This is useful when using Apollo Client passing it the computed url without effort.

 const wsLink = new WebSocketLink({
   uri: dfuseClient.endpoints.graphqlStreamUrl,
   ...,
 });

getTokenInfo

getTokenInfo: () => Promise<ApiTokenInfo>

Call this method each time you need an API token. Th returned API token is always valid. The expiration and the refresh of the token is handled automatically when using this method.

returns: A Promise that will resolve to a valid ApiTokenInfo instance, or will reject if an error occurs retrieving the API token.

Type declaration

- (): Promise<ApiTokenInfo>
- Returns Promise<ApiTokenInfo>

Methods

apiRequest

apiRequest<T>(path: string, method: string, params?: HttpQueryParameters, body?: any, headers?: HttpHeaders): Promise<T>

- Defined in src/types/client.ts:625
An helper method that can be used to perform a generic HTTP call using the library inner configured HttpClient.

This can be used to reach other REST API found on the nodeos process for example, those that are not directly included in the library but are still accessible via our endpoint like a /v1/chain/get_info or /v1/chain/push_transaction.

Type parameters
- T
Parameters
- path: string
  
  (required) The HTTP path on the endpoint
- method: string
  
  (required) The HTTP method to perform the request agaisnt
- Optional params: HttpQueryParameters
  
  (defaults {}) The HTTP query parameters to append to the url, they will be url-encoded and included in the final remote url. Has no effect when empty or undefined.
- Optional body: any
  
  (defaults undefined) The HTTP body to include in the request, assumed to be a JSON object that will be serialized to a string. Not included in the HTTP request when undefined.
- Optional headers: HttpHeaders
  
  (defaults {}) The extra HTTP headers to include in the request. Those will be merged with default ones ({ Authorization: ... }) and they override them if same key are specified.
Returns Promise<T>

A Promise that will resolve to the response body if it passes. Will reject with a DfuseApiError if it fits the dfuse Error Format or a generic DfuseError is it's something not fitting our expected format (nodeos erorr format for example).

authIssue

authIssue(apiKey?: undefined | string): Promise<AuthTokenResponse>

- Defined in src/types/client.ts:259
POST /v1/auth/issue (on https://auth.dfuse.io by default, see DfuseClientOptions.authUrl)

Issues dfuse API token for the following API key.

see

https://docs.dfuse.io/#rest-api-post-https-auth-dfuse-io-v1-auth-issue

Parameters
- Optional apiKey: undefined | string
  
  (defaults undefined, uses the one defined on the client) The apiKey to generate an API token for. If left undefined, the client will provide the one it is configured with, if present.
Returns Promise<AuthTokenResponse>

fetchBlockIdByTime

fetchBlockIdByTime(time: string | Date, comparator: ComparisonOperator): Promise<BlockIdByTimeResponse>

- Defined in src/types/client.ts:279
GET /v0/block_id/by_time

Fetches the block ID, block time and block number for the given timestamp.

Parameters
- time: string | Date
  
  The reference timestamp to query for. If it's a string, assumed to be in ISO8601 extended format, i.e. 2019-03-04T10:36:14.5Z. If it's a date, it's going to be turned into an ISO8601 extended format relative to UTC.
- comparator: ComparisonOperator
  Comparison operator for the block time. Should be one of:
  - gt (Greater Than time)
  - gte (Greater Than or Equal to time)
  - lt (Lower Than time)
  - lte (Lower Than or Equal totime)
  - eq (Strictly equal to time)
Returns Promise<BlockIdByTimeResponse>

A promise resolving to a BlockIdByTimeResponse object if the request was correct, or rejects with a DfuseApiError when it failed (or a more DfuseError when an unexpected error occurs).

fetchTransaction

fetchTransaction(id: string): Promise<TransactionLifecycle>

- Defined in src/types/client.ts:295
GET /v0/transactions/:id

Retrieves a TransactionLifecycle object representing the transaction that has for id <id>.

Parameters
- id: string
  
  The transaction id to search for.
Returns Promise<TransactionLifecycle>

A promise resolving to a TransactionLifecycle object if the request was correct, or rejects with a DfuseApiError when it failed (or a more DfuseError when an unexpected error occurs).

graphql

graphql<T>(document: string | GraphqlDocument, options?: undefined | { operationType?: Exclude<GraphqlOperationType, "subscription">; variables?: GraphqlVariables }): Promise<GraphqlResponse<T>>
graphql<T>(document: string | GraphqlDocument, onMessage: OnGraphqlStreamMessage<T>, options?: undefined | { operationType?: GraphqlOperationType; variables?: GraphqlVariables }): Promise<Stream>

- Defined in src/types/client.ts:102
Perform a query or mutation via the HTTP transport layer. The semantic of this method is to resolve the promise with the GraphQL response when the operation succeed on the server, whenever the actual GraphQL response contains an errors field or not.

If an error at the HTTP error, the promise will be rejected.

Type parameters
- T = any
Parameters
- document: string | GraphqlDocument
  
  (required) The GraphQL operation document to perform. It must be either a query or mutation operation. A subscription operation is not supported by this method. You must use the method that accept options.onMessage to make it work.
- Optional options: undefined | { operationType?: Exclude<GraphqlOperationType, "subscription">; variables?: GraphqlVariables }
  
  (optional) Specific options that can be provided
Returns Promise<GraphqlResponse<T>>
- Defined in src/types/client.ts:135
Perform a query, mutation or subscription via the WebSocket transport layer. The semantic of this method is to resolve the promise with the Stream object if the connection was established correctly (or if it was already established) and the initial subscription message was sent correctly (this does not check if it was received correctly).

Each message for the subscription will be sent to the onMessage handler defined on the options field.

The Stream object can be used to control the stream. It can be marked via Stream.mark (so on reconnect, this stream restarts at the last marked location), joined via Stream.join (so you wait until the stream actually finishes) or closed via Stream.close.

If we are unable to establish the connection or the initial send message cannot be sent, then the promise will reject with the appropriate error.

Type parameters
- T = any
Parameters
- document: string | GraphqlDocument
  
  (required) The GraphQL operation document to perform.
- onMessage: OnGraphqlStreamMessage<T>
- Optional options: undefined | { operationType?: GraphqlOperationType; variables?: GraphqlVariables }
  
  (required) Specific options that can be provided
Returns Promise<Stream>

release

release(): void

- Defined in src/types/client.ts:80
Release any resources hold by this DfuseClient instance. Must be tolerant to being called multiple times.

Once called, the instance is assumed unsuable and should never be invoked anymore.

Returns void

searchTransactions

searchTransactions(q: string, options?: undefined | { blockCount?: undefined | number; cursor?: undefined | string; limit?: undefined | number; sort?: SearchSortType; startBlock?: undefined | number; withReversible?: undefined | false | true }): Promise<SearchTransactionsResponse>

- Defined in src/types/client.ts:318
GET /v0/search/transactions

Search an EOSIO blockchain for transactions based on free-form criterias, using the simple dfuse Search query language.

see

https://docs.dfuse.io/#rest-api-get-v0-search-transactions

Parameters
- q: string
  
  Search query string. See Search language (https://docs.dfuse.io/#ref-search-query-specs) specs for details.
- Optional options: undefined | { blockCount?: undefined | number; cursor?: undefined | string; limit?: undefined | number; sort?: SearchSortType; startBlock?: undefined | number; withReversible?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<SearchTransactionsResponse>

stateAbi

stateAbi(account: string, options?: undefined | { blockNum?: undefined | number; json?: undefined | false | true }): Promise<StateAbiResponse>

- Defined in src/types/client.ts:345
GET /v0/state/abi

Fetches the ABI for a given contract account, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-abi

Parameters
- account: string
  
  Contract account targeted by the action.
- Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<StateAbiResponse>

stateAbiBinToJson

stateAbiBinToJson<T>(account: string, table: string, hexRows: string[], options?: undefined | { blockNum?: undefined | number }): Promise<StateAbiToJsonResponse<T>>

- Defined in src/types/client.ts:370
GET /v0/state/abi/bin_to_json

Fetches the ABI for a given contract account, at any block height.

see

https://docs.dfuse.io/#rest-api-post-v0-state-abi-bin_to_json

Type parameters
- T = unknown
Parameters
- account: string
  
  Contract account targeted by the action.
- table: string
  
  The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- hexRows: string[]
  
  An array of hexadecimal rows to decode. Each row must be a valid hexadecimal string representation of the row to decode against the ABI.
- Optional options: undefined | { blockNum?: undefined | number }
  
  (optional) Optional parameters
Returns Promise<StateAbiToJsonResponse<T>>

stateKeyAccounts

stateKeyAccounts(publicKey: string, options?: undefined | { blockNum?: undefined | number }): Promise<StateKeyAccountsResponse>

- Defined in src/types/client.ts:391
GET /v0/state/key_accounts

Fetches the accounts controlled by the given public key, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-key_accounts

Parameters
- publicKey: string
  
  The public key to fetch controlled accounts for.
- Optional options: undefined | { blockNum?: undefined | number }
  
  (optional) Optional parameters
Returns Promise<StateKeyAccountsResponse>

statePermissionLinks

statePermissionLinks(account: string, options?: undefined | { blockNum?: undefined | number }): Promise<StatePermissionLinksResponse>

- Defined in src/types/client.ts:410
GET /v0/state/permission_links

Fetches snapshots of any account's linked authorizations on the blockchain, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-permission_links

Parameters
- account: string
  
  Contract account targeted by the action.
- Optional options: undefined | { blockNum?: undefined | number }
  
  (optional) Optional parameters
Returns Promise<StatePermissionLinksResponse>

stateTable

stateTable<T>(account: string, scope: string, table: string, options?: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }): Promise<StateResponse<T>>

- Defined in src/types/client.ts:465
GET /v0/state/table

Fetches the state of any table, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-table

Type parameters
- T = unknown
Parameters
- account: string
  
  Contract account targeted by the action.
- scope: string
  
  The name-encoded scope of the table you are requesting. For example, user balances for tokens live in their account name's scope. This is contract dependent, so inspect the ABI for the contract you are interested in.
- table: string
  
  The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<StateResponse<T>>

stateTableRow

stateTableRow<T>(account: string, scope: string, table: string, primaryKey: string, options?: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }): Promise<StateTableRowResponse<T>>

- Defined in src/types/client.ts:512
GET /v0/state/table/row

Fetches a single row from the state of any table, at any block height.

preview

This endpoint is preview mode. This means it might be changed or removed and is not covered by breaking compatiblity policy of the project until it's out of preview.

see

https://docs.dfuse.io/#rest-api-get-v0-state-table-row

Type parameters
- T = unknown
Parameters
- account: string
  
  Contract account targeted by the action.
- scope: string
  
  The name-encoded scope of the table you are requesting. For example, user balances for tokens live in their account name's scope. This is contract dependent, so inspect the ABI for the contract you are interested in.
- table: string
  
  The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- primaryKey: string
  
  The string representation of the primary key that you want to retrieve. The primaryKey is always a string, but can be encoded differently, for example name encoded like an account. The keyType is used to know how to transform the value in the string to the correct type.
- Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<StateTableRowResponse<T>>

stateTableScopes

stateTableScopes(account: string, table: string, options?: undefined | { blockNum?: undefined | number }): Promise<StateTableScopesResponse>

- Defined in src/types/client.ts:431
GET /v0/state/table_scopes

Fetches a list of scopes, for a given table on a contract account, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-table_scopes

Parameters
- account: string
  
  Contract account holding the requested table.
- table: string
  
  The name-encoded table name you want to retrieve scopes from. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- Optional options: undefined | { blockNum?: undefined | number }
  
  (optional) Optional parameters
Returns Promise<StateTableScopesResponse>

stateTablesForAccounts

stateTablesForAccounts<T>(accounts: string[], scope: string, table: string, options?: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }): Promise<MultiStateResponse<T>>

- Defined in src/types/client.ts:550
GET /v0/state/tables/accounts

Fetches a table for a given contract account for a group of scopes, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-tables-accounts

Type parameters
- T = unknown
Parameters
- accounts: string[]
  
  An AccountName list a maximum of 1500 elements can be present in the list.
- scope: string
  
  A Name list, a maximum of 1500 elements can be present in the list.
- table: string
  
  The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<MultiStateResponse<T>>

stateTablesForScopes

stateTablesForScopes<T>(account: string, scopes: string[], table: string, options?: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }): Promise<MultiStateResponse<T>>

- Defined in src/types/client.ts:587
GET /v0/state/tables/scopes

Fetches a table for a given contract account for a group of scopes, at any block height.

see

https://docs.dfuse.io/#rest-api-get-v0-state-tables-scopes

Type parameters
- T = unknown
Parameters
- account: string
  
  Contract account targeted by the action.
- scopes: string[]
- table: string
  
  The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
- Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true; keyType?: StateKeyType; withAbi?: undefined | false | true; withBlockNum?: undefined | false | true }
  
  (optional) Optional parameters
Returns Promise<MultiStateResponse<T>>

streamActionTraces

streamActionTraces(data: GetActionTracesMessageData, onMessage: OnStreamMessage, options?: StreamOptions): Promise<Stream>

- Defined in src/types/client.ts:168
Retrieve a stream of actions, filtered by receiver(s), account(s) and action name(s).

see

https://docs.dfuse.io/#websocket-based-api-get_action_traces

Parameters
- data: GetActionTracesMessageData
  
  (required) Specific stream options used to filter
- onMessage: OnStreamMessage
  
  (required) The callback that will be invoked for each message received for this specific stream.
- Optional options: StreamOptions
  
  (defaults undefined) The stream common options that can be used, see StreamOptions for more details and default values.
Returns Promise<Stream>

streamHeadInfo

streamHeadInfo(onMessage: OnStreamMessage, options?: StreamOptions): Promise<Stream>

- Defined in src/types/client.ts:224
Retrieve a stream of informations about the chain as it moves forward

see

https://docs.dfuse.io/#websocket-based-api-get_head_info

Parameters
- onMessage: OnStreamMessage
  
  (required) The callback that will be invoked for each message received for this specific stream.
- Optional options: StreamOptions
  
  (defaults undefined) The stream common options that can be used, see StreamOptions for more details and default values.
Returns Promise<Stream>

streamTableRows

streamTableRows(data: GetTableRowsMessageData, onMessage: OnStreamMessage, options?: StreamOptions): Promise<Stream>

- Defined in src/types/client.ts:189
Retrieve a stream of changes to the tables, the side effects of transactions/actions being executed.

see

https://docs.dfuse.io/#websocket-based-api-get_table_rows

Parameters
- data: GetTableRowsMessageData
  
  (required)
- onMessage: OnStreamMessage
  
  (required) The callback that will be invoked for each message received for this specific stream.
- Optional options: StreamOptions
  
  (defaults undefined) The stream common options that can be used, see StreamOptions for more details and default values.
Returns Promise<Stream>

streamTransaction

streamTransaction(data: GetTransactionLifecycleMessageData, onMessage: OnStreamMessage, options?: StreamOptions): Promise<Stream>

- Defined in src/types/client.ts:208
Retrieve a transaction_lifecycle (when fetch is true) and follow its life-cycle (when listen is true).

see

https://docs.dfuse.io/#websocket-based-api-get_transaction_lifecycle

Parameters
- data: GetTransactionLifecycleMessageData
  
  (required)
- onMessage: OnStreamMessage
  
  (required) The callback that will be invoked for each message received for this specific stream.
- Optional options: StreamOptions
  
  (defaults undefined) The stream common options that can be used, see StreamOptions for more details and default values.
Returns Promise<Stream>

Hierarchy

Implemented by

Index

Properties

Methods

Properties

Readonly endpoints

getTokenInfo

Type declaration

Returns Promise<ApiTokenInfo>

Methods

apiRequest

Type parameters

T

Parameters

path: string

method: string

Optional params: HttpQueryParameters

Optional body: any

Optional headers: HttpHeaders

Returns Promise<T>

authIssue

Parameters

Optional apiKey: undefined | string

Returns Promise<AuthTokenResponse>

fetchBlockIdByTime

Parameters

time: string | Date

comparator: ComparisonOperator

Returns Promise<BlockIdByTimeResponse>

fetchTransaction

Parameters

id: string

Returns Promise<TransactionLifecycle>

graphql

Type parameters

T = any

Parameters

document: string | GraphqlDocument

Optional options: undefined | { operationType?: Exclude<GraphqlOperationType, "subscription">; variables?: GraphqlVariables }

Returns Promise<GraphqlResponse<T>>

Type parameters

T = any

Parameters

document: string | GraphqlDocument

onMessage: OnGraphqlStreamMessage<T>

Optional options: undefined | { operationType?: GraphqlOperationType; variables?: GraphqlVariables }

Returns Promise<Stream>

release

Returns void

searchTransactions

Parameters

q: string

Optional options: undefined | { blockCount?: undefined | number; cursor?: undefined | string; limit?: undefined | number; sort?: SearchSortType; startBlock?: undefined | number; withReversible?: undefined | false | true }

Returns Promise<SearchTransactionsResponse>

stateAbi

Parameters

account: string

Optional options: undefined | { blockNum?: undefined | number; json?: undefined | false | true }

Returns Promise<StateAbiResponse>

stateAbiBinToJson

Type parameters

T = unknown

Parameters

account: string

table: string

hexRows: string[]

Optional options: undefined | { blockNum?: undefined | number }

Returns Promise<StateAbiToJsonResponse<T>>

stateKeyAccounts

Parameters

publicKey: string

Optional options: undefined | { blockNum?: undefined | number }

Returns Promise<StateKeyAccountsResponse>

statePermissionLinks

Parameters

account: string

Optional options: undefined | { blockNum?: undefined | number }

Returns Promise<StatePermissionLinksResponse>

stateTable