Skip to main content

Query & Mutation Methods

The OCAP Client interacts with the blockchain through GraphQL. Methods are categorized into two main types:

  • Queries: These are read-only operations used to fetch data from the blockchain, such as retrieving the state of an account, listing transactions, or getting general chain information. They do not alter the state of the chain.
  • Mutations: These are write operations that modify the state of the blockchain. Sending a transaction is the primary example of a mutation.

This section provides a complete reference for all available query and mutation methods provided by the client.

Query Methods

Queries are used to retrieve data from the blockchain. Here is a complete list of all available query methods.

getAccountState

Retrieves the current state of a specific account, including its balance, nonce, and other details.

Parameters

  • address string (required) — The address of the account to query.
  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.
  • traceMigration boolean — If true, traces the account's migration history.

Returns

  • ResponseGetAccountState object — An object containing the response code and the account state.
    • code string — The status code of the response (e.g., 'OK').
    • state AccountState — The detailed state of the account.

getAssetState

Retrieves the current state of a specific asset (NFT).

Parameters

  • address string (required) — The address of the asset to query.
  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.

Returns

  • ResponseGetAssetState object — An object containing the response code and the asset state.
    • code string — The status code of the response.
    • state AssetState — The detailed state of the asset.

getFactoryState

Fetches the state of a specific asset factory.

Parameters

  • address string (required) — The address of the factory to query.

Returns

  • ResponseGetFactoryState object — An object containing the response code and the factory state.
    • code string — The status code of the response.
    • state AssetFactoryState — The detailed state of the asset factory.

getDelegateState

Retrieves the state of a delegation relationship.

Parameters

  • address string (required) — The address of the delegation to query.
  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.

Returns

  • ResponseGetDelegateState object — An object containing the response code and the delegation state.
    • code string — The status code of the response.
    • state DelegateState — The detailed state of the delegation.

getTokenState

Fetches the state of a specific fungible token.

Parameters

  • address string (required) — The address of the token to query.

Returns

  • ResponseGetTokenState object — An object containing the response code and the token state.
    • code string — The status code of the response.
    • state TokenState — The detailed state of the token.

getEvidenceState

Retrieves an evidence record by its hash.

Parameters

  • hash string (required) — The hash of the evidence to retrieve.

Returns

  • ResponseGetEvidenceState object — An object containing the response code and the evidence state.
    • code string — The status code of the response.
    • state EvidenceState — The detailed state of the evidence.

getForgeState

Fetches the overall configuration and state of the OCAP blockchain.

Parameters

  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.

Returns

  • ResponseGetForgeState object — An object containing the response code and the chain state.
    • code string — The status code of the response.
    • state ForgeState — The detailed state of the OCAP chain.

getTokenFactoryState

Retrieves the state of a specific token factory.

Parameters

  • address string (required) — The address of the token factory to query.

Returns

  • ResponseGetTokenFactoryState object — An object containing the response code and the token factory state.
    • code string — The status code of the response.
    • state TokenFactoryState — The detailed state of the token factory.

getTx

Fetches a single transaction by its hash.

Parameters

  • hash string (required) — The hash of the transaction to retrieve.

Returns

  • ResponseGetTx object — An object containing the response code and transaction details.
    • code string — The status code of the response.
    • info TransactionInfo — The detailed information of the transaction.

getBlock

Retrieves a single block by its height.

Parameters

  • height string (required) — The height of the block to retrieve.

Returns

  • ResponseGetBlock object — An object containing the response code and block details.
    • code string — The status code of the response.
    • block BlockInfo — The detailed information of the block.

getBlocks

Retrieves a list of blocks, with optional filters.

Parameters

  • paging PageInput — Pagination settings.
  • heightFilter RangeFilterInput — Filter blocks by a height range.
  • emptyExcluded boolean — If true, blocks with no transactions are excluded.

Returns

  • ResponseGetBlocks object — An object containing pagination info and a list of blocks.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • blocks BlockInfoSimple[] — An array of simplified block objects.

getUnconfirmedTxs

Fetches transactions that are in the mempool but not yet confirmed.

Parameters

  • paging PageInput — Pagination settings.

Returns

  • ResponseGetUnconfirmedTxs object — An object containing pagination info and a list of unconfirmed transactions.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • unconfirmedTxs UnconfirmedTxs — Details of unconfirmed transactions.

getChainInfo

Retrieves general information about the blockchain.

Parameters

This method does not take any parameters.

Returns

  • ResponseGetChainInfo object — An object containing the response code and chain information.
    • code string — The status code of the response.
    • info ChainInfo — The detailed information of the chain.

getConfig

Fetches the node's configuration.

Parameters

  • parsed boolean — If true, returns the parsed configuration.

Returns

  • ResponseGetConfig object — An object containing the response code and the configuration.
    • code string — The status code of the response.
    • config string — The node's configuration as a string.

getNetInfo

Retrieves network information, including connected peers.

Parameters

This method does not take any parameters.

Returns

  • ResponseGetNetInfo object — An object containing the response code and network information.
    • code string — The status code of the response.
    • netInfo NetInfo — Detailed network information.

getNodeInfo

Retrieves information about the specific node being queried.

Parameters

This method does not take any parameters.

Returns

  • ResponseGetNodeInfo object — An object containing the response code and node information.
    • code string — The status code of the response.
    • info NodeInfo — Detailed information about the node.

getValidatorsInfo

Fetches information about the current set of validators.

Parameters

This method does not take any parameters.

Returns

  • ResponseGetValidatorsInfo object — An object containing the response code and validators information.
    • code string — The status code of the response.
    • validatorsInfo ValidatorsInfo — Detailed information about the validators.

getForgeStats

Retrieves various statistics about the blockchain's activity.

Parameters

This method does not take any parameters.

Returns

  • ResponseGetForgeStats object — An object containing the response code and chain statistics.
    • code string — The status code of the response.
    • forgeStats ForgeStats — Various statistics about the OCAP chain.

listAssetTransactions

Lists all transactions related to a specific asset.

Parameters

  • address string (required) — The address of the asset.
  • paging PageInput — Pagination settings.

Returns

  • ResponseListAssetTransactions object — An object containing pagination info and a list of transactions.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • transactions IndexedTransaction[] — An array of transaction objects.

listAssets

Lists all assets, with filters for owner or factory.

Parameters

  • paging PageInput — Pagination settings.
  • ownerAddress string — Filter assets by the owner's address.
  • factoryAddress string — Filter assets by the factory's address.
  • timeFilter TimeFilterInput — Filter assets by a time range.

Returns

  • ResponseListAssets object — An object containing pagination info and a list of assets.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • assets IndexedAssetState[] — An array of asset state objects.

listBlocks

Lists blocks with various filtering options.

Parameters

  • paging PageInput — Pagination settings.
  • proposer string — Filter blocks by the proposer's address.
  • timeFilter TimeFilterInput — Filter blocks by a time range.
  • heightFilter RangeFilterInput — Filter blocks by a height range.
  • numTxsFilter RangeFilterInput — Filter blocks by the number of transactions.
  • numInvalidTxsFilter RangeFilterInput — Filter blocks by the number of invalid transactions.

Returns

  • ResponseListBlocks object — An object containing pagination info and a list of blocks.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • blocks IndexedBlock[] — An array of block objects.

listTopAccounts

Lists accounts with the highest balance of a specific token.

Parameters

  • paging PageInput — Pagination settings.
  • tokenAddress string — The address of the token. If not provided, it defaults to the native token.
  • timeFilter TimeFilterInput — Filter accounts by a time range.

Returns

  • ResponseListTopAccounts object — An object containing pagination info and a list of top accounts.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • accounts IndexedAccountState[] — An array of account state objects.

listTransactions

A powerful method to list transactions with a wide range of filters.

Parameters

  • paging PageInput — Pagination settings.
  • timeFilter TimeFilterInput — Filter transactions by a time range.
  • addressFilter AddressFilterInput — Filter transactions by sender or receiver address.
  • typeFilter TypeFilterInput — Filter by transaction type.
  • validityFilter ValidityFilterInput — Filter by transaction validity.
  • factoryFilter FactoryFilterInput — Filter by factory address.
  • tokenFilter TokenFilterInput — Filter by token address.
  • assetFilter AssetFilterInput — Filter by asset address.
  • accountFilter AccountFilterInput — Filter by account address.
  • txFilter TxFilterInput — Filter by transaction hash.
  • rollupFilter RollupFilterInput — Filter by rollup address.
  • stakeFilter StakeFilterInput — Filter by stake address.
  • delegationFilter DelegationFilterInput — Filter by delegation address.
  • tokenFactoryFilter TokenFactoryFilterInput — Filter by token factory address.

Returns

  • ResponseListTransactions object — An object containing pagination info and a list of transactions.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • transactions IndexedTransaction[] — An array of transaction objects.

listTokens

Lists all fungible tokens on the chain.

Parameters

  • paging PageInput — Pagination settings.
  • issuerAddress string — Filter tokens by the issuer's address.
  • timeFilter TimeFilterInput — Filter tokens by a time range.

Returns

  • ResponseListTokens object — An object containing pagination info and a list of tokens.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • tokens IndexedTokenState[] — An array of token state objects.

listFactories

Lists all asset factories on the chain.

Parameters

  • paging PageInput — Pagination settings.
  • ownerAddress string — Filter factories by the owner's address.
  • addressList string[] — A list of factory addresses to query.
  • timeFilter TimeFilterInput — Filter factories by a time range.

Returns

  • ResponseListFactories object — An object containing pagination info and a list of factories.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • factories IndexedFactoryState[] — An array of factory state objects.

getAccountTokens

Retrieves the token balances for a specific account.

Parameters

  • address string (required) — The address of the account.
  • token string — Specific token address to query.

Returns

  • ResponseGetAccountTokens object — An object containing the response code and a list of account tokens.
    • code string — The status code of the response.
    • tokens AccountToken[] — An array of token balance objects.

getStakeState

Fetches the state of a specific stake.

Parameters

  • address string (required) — The address of the stake to query.
  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.

Returns

  • ResponseGetStakeState object — An object containing the response code and the stake state.
    • code string — The status code of the response.
    • state StakeState — The detailed state of the stake.

listStakes

Lists all stake records, with optional filters.

Parameters

  • paging PageInput — Pagination settings.
  • addressFilter AddressFilterInput — Filter stakes by sender or receiver address.
  • timeFilter TimeFilterInput — Filter stakes by a time range.
  • assetFilter AssetFilterInput — Filter stakes by asset address.

Returns

  • ResponseListStakes object — An object containing pagination info and a list of stakes.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • stakes IndexedStakeState[] — An array of stake state objects.

getRollupState

Retrieves the state of a specific rollup.

Parameters

  • address string (required) — The address of the rollup to query.
  • height string — Query the state at a specific block height.
  • keys string[] — Specific fields to retrieve.

Returns

  • ResponseGetRollupState object — An object containing the response code and the rollup state.
    • code string — The status code of the response.
    • state RollupState — The detailed state of the rollup.

listRollups

Lists all rollups on the chain.

Parameters

  • paging PageInput — Pagination settings.
  • tokenAddress string — Filter rollups by token address.
  • foreignTokenAddress string — Filter rollups by foreign token address.
  • timeFilter TimeFilterInput — Filter rollups by a time range.

Returns

  • ResponseListRollups object — An object containing pagination info and a list of rollups.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • rollups IndexedRollupState[] — An array of rollup state objects.

getRollupBlock

Fetches a specific block from a rollup sidechain.

Parameters

  • hash string — The hash of the rollup block.
  • height string — The height of the rollup block.
  • rollupAddress string (required) — The address of the rollup.

Returns

  • ResponseGetRollupBlock object — An object containing the response code and the rollup block.
    • code string — The status code of the response.
    • block RollupBlock — The detailed information of the rollup block.

listRollupBlocks

Lists blocks from a rollup sidechain.

Parameters

  • paging PageInput — Pagination settings.
  • rollupAddress string (required) — The address of the rollup.
  • tokenAddress string — Filter by token address.
  • proposer string — Filter by proposer address.
  • validatorFilter ValidatorFilterInput — Filter by validator.
  • txFilter TxFilterInput — Filter by transaction hash.
  • timeFilter TimeFilterInput — Filter by time range.

Returns

  • ResponseListRollupBlocks object — An object containing pagination info and a list of rollup blocks.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • blocks IndexedRollupBlock[] — An array of rollup block objects.

listRollupValidators

Lists the validators for a specific rollup.

Parameters

  • paging PageInput — Pagination settings.
  • rollupAddress string (required) — The address of the rollup.

Returns

  • ResponseListRollupValidators object — An object containing pagination info and a list of rollup validators.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • validators IndexedRollupValidator[] — An array of rollup validator objects.

listDelegations

Lists all delegation records.

Parameters

  • paging PageInput — Pagination settings.
  • from string — Filter by the delegator's address.
  • to string — Filter by the delegatee's address.
  • timeFilter TimeFilterInput — Filter by time range.

Returns

  • ResponseListDelegations object — An object containing pagination info and a list of delegations.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • delegations IndexedDelegationState[] — An array of delegation state objects.

search

Performs a keyword search for accounts, assets, or transactions.

Parameters

  • paging PageInput — Pagination settings.
  • keyword string (required) — The keyword to search for.

Returns

  • ResponseSearch object — An object containing pagination info and search results.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • results SearchResult[] — An array of search result objects.

estimateGas

Estimates the gas required for a transaction.

Parameters

  • typeUrl string (required) — The type URL of the transaction.
  • tx string (required) — The encoded transaction string.

Returns

  • ResponseEstimateGas object — An object containing the response code and the gas estimate.
    • code string — The status code of the response.
    • estimate GasEstimate — The estimated gas.

listTokenFlows

Traces the flow of tokens between accounts.

Parameters

  • paging PageInput — Pagination settings.
  • accountAddress string (required) — The address of the account to trace.
  • tokenAddress string — The address of the token to trace.
  • depth number — The depth of the trace.
  • direction TokenFlowDirection — The direction of the flow (IN or OUT).

Returns

  • ResponseListTokenFlows object — An object containing pagination info and token flow data.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • data IndexedTokenFlow[] — An array of token flow objects.

verifyAccountRisk

Assesses the risk profile of a given account.

Parameters

  • accountAddress string (required) — The address of the account to verify.
  • tokenAddress string — The address of the token for context.

Returns

  • ResponseVerifyAccountRisk object — An object containing the response code and the risk verification result.
    • code string — The status code of the response.
    • data VerifyAccountRiskResult — The result of the risk verification.

getTokenDistribution

Retrieves the distribution statistics for a given token.

Parameters

  • tokenAddress string (required) — The address of the token.

Returns

  • ResponseGetTokenDistribution object — An object containing the response code and token distribution data.
    • code string — The status code of the response.
    • data TokenDistribution — The token distribution statistics.

listTokenFactories

Lists all token factories on the chain.

Parameters

  • paging PageInput — Pagination settings.
  • tokenAddress string — Filter by token address.
  • reserveAddress string — Filter by reserve token address.
  • owner string — Filter by owner address.
  • timeFilter TimeFilterInput — Filter by time range.

Returns

  • ResponseListTokenFactories object — An object containing pagination info and a list of token factories.
    • code string — The status code of the response.
    • page PageInfo — Pagination information.
    • tokenFactories IndexedTokenFactoryState[] — An array of token factory state objects.

Mutation Methods

Mutations are used to send transactions that modify the state of the blockchain.

sendTx

Broadcasts a pre-signed transaction to the network. This is the fundamental method for all write operations. For creating and signing transactions, see the High-level API and Transaction Lifecycle guides.

Parameters

  • tx string (required) — The encoded transaction string.
  • wallet object (required) — The wallet object used for signing.
  • token string — Authentication token, if required.
  • commit boolean (default: true) — If true, waits for the transaction to be committed to a block.
  • extra string — Extra data to be included.

Returns

  • ResponseSendTx object — An object containing the response code and the transaction hash.
    • code string — The status code of the response.
    • hash string — The hash of the submitted transaction.

Example

javascript
// This example assumes `signedTx` is a properly encoded and signed transaction string.
// See other guides for how to create it.

const signedTx = '...';
const wallet = { ... }; // The wallet that signed the transaction

try {
  const { hash } = await client.sendTx({ tx: signedTx, wallet });
  console.log('Transaction sent successfully! Hash:', hash);
} catch (error) {
  console.error('Failed to send transaction:', error);
}