QueryBuilderV2

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

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

setDataQuery(dataQuery: UnbuiltSubquery[])

Sets the dataQuery to an array of UnbuiltSubquery objects.

setBuiltDataQuery

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

setComputeQuery(computeQuery: AxiomV2ComputeQuery)

Sets a computeQuery.

setCallback

setCallback(callback: AxiomV2Callback)

Set the callback you want to pass the proof to.

setOptions

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

getDataQuery(): UnbuiltSubquery[] | undefined

Returns the current set of unbuilt data subqueries or undefined.

getDataSubqueryCount

getDataSubqueryCount(): DataSubqueryCount

Returns the current count of each type of data subquery

getComputeQuery

getComputeQuery(): AxiomV2ComputeQuery | undefined

Returns the current compute query or undefined.

getCallback

getCallback(): AxiomV2Callback | undefined

Returns the current callback information or undefined.

getOptions

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

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

validate(): Promise<boolean>

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

build

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

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

Sends the query onchain to Axiom's smart contract.

sendQueryWithIpfs

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

append(dataSubqueries: UnbuiltSubquery[]): void

Appends a UnbuiltSubquery[] object to the current dataQuery

appendDataSubquery

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.

getQuerySchemaHash

getQuerySchema(): string

Returns the hash of the querySchema of the computeQuery

getDataQueryHash

getDataQueryHash(): string

Returns the hash of the data query

getQueryId

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

calculateFee(): string

Returns the amount of wei required to send this query