Explanation of the different QueryBuilderV2 methods available in the Axiom SDK for building and submitting Queries.

The Axiom SDK is an npm library with a collection of APIs and query tools.

To install the package into your dApp as a project dependency, use your favorite package manager (npm, yarn, or pnpm)

npm i @axiom-crypto/core

Building and Submitting Queries

The QueryBuilderV2 class which helps users construct queries in the Axiom Query Format and submit them on-chain. An instance of QueryBuilderV2 is created by the following call:

import { Axiom, QueryV2 } from "@axiom-crypto/core";

const axiom = new Axiom({
  providerUri: process.env.PROVIDER_URI_GOERLI as string,
  privateKey: process.env.PRIVATE_KEY_GOERLI as string,
  version: "v2",
  chainId: 5, // Goerli
  mock: true, // generate Mock proofs for faster development
const query = (axiom.query as QueryV2).new();


setDataQuery(dataQuery: UnbuiltSubquery[])

Sets the dataQuery to an array of UnbuiltSubquery objects.


setBuiltDataQuery(dataQuery: AxiomV2DataQuery): void

Appends an already-built DataQuery. This is used when receiving a DataQuery from a ComputeQuery. Setting this will take precedence over setting any UnbuiltSubqueries via append()/appendDataSubquery().


setComputeQuery(computeQuery: AxiomV2ComputeQuery)

Sets a computeQuery.


setCallback(callback: AxiomV2Callback)

Set the callback you want to pass the proof to.


setOptions(options: AxiomV2QueryOptions): AxiomV2QueryOptions

Developers can set the following options in their query:

    // Maximum fee per unit of gas for callback
    maxFeePerGas?: string
    // Gas limit you are willing to set for the callback
    callbackGasLimit?: number
    // Warn if the calldata size is above this threshold
    dataQueryCalldataGasWarningThreshold?: number
    // The address that can claim the refund for any unused Ether
    refundee?: string

Returns the options, AxiomV2QueryOptions.


getDataQuery(): UnbuiltSubquery[] | undefined

Returns the current set of unbuilt data subqueries or undefined.


getDataSubqueryCount(): DataSubqueryCount

Returns the current count of each type of data subquery


getComputeQuery(): AxiomV2ComputeQuery | undefined

Returns the current compute query or undefined.


getCallback(): AxiomV2Callback | undefined

Returns the current callback information or undefined.


getOptions(): AxiomV2QueryOptions

Returns the current Query options.

Developers can set the following options in their query:

    maxFeePerGas?: string
    callbackGasLimit?: number
    dataQueryCalldataGasWarningThreshold?: number
    refundee?: string

These will default to a set value and the refundee will default to the current wallet address


getBuiltQuery(): BuiltQueryV2 | undefined

Returns the built Query or undefined if Query has not been built yet. Built Query resets if any data is changed.


validate(): Promise<boolean>

Returns a boolean validating the subqueries. Specifically, it checks that values are in the correct ranges.


async build(): Promise<BuiltQueryV2>

Queries the required subquery data and builds the entire Query object into the format required by the backend/ZK circuit.

Returns A built Query.


sendOnchainQuery( paymentAmountWei: string, cb?: (receipt: ethers.ContractTransactionReceipt) => void ): Promise<string>

Sends the query onchain to Axiom's smart contract.


sendQueryWithIpfs(paymentAmountWei: string, cb?: (receipt: ethers.ContractTransactionReceipt) => void ): Promise<string>

Returns an IPFS CID.

Used for pinning the encoded Query data to IPFS. The user still submits a transaction on-chain for the Prover to start the proving process, but instead of sending the encoded Query data as calldata, the user will include an IPFS CID hash which the Prover can then use to get the Query, decode it, and generate a ZK proof of it.


append(dataSubqueries: UnbuiltSubquery[]): void

Appends a UnbuiltSubquery[] object to the current dataQuery


appendDataSubquery(dataSubquery: UnbuiltSubquery): void

Appends a single subquery to the current dataQuery. Developers can optionally pass the type of the subquery to append. If one is not provided, the type will be inferred from the keys of the subquery.


getQuerySchema(): string

Returns the hash of the querySchema of the computeQuery


getDataQueryHash(): string

Returns the hash of the data query


getQueryId(caller?: string): Promise<string>

Returns a uint256 queryId for a built Query (requires `privateKey` to be set in AxiomConfig if no `caller` is supplied to the function)


calculateFee(): string

Returns the amount of wei required to send this query

Last updated