Axiom V2 Docs
Comment on page


Get started with Axiom V2 on Goerli Testnet
The absolute fastest way to get started is to clone the Axiom Quickstart repository and run the examples there. We will walk through how to do that in this guide.


git clone --recurse-submodules --shallow-submodules -j8
cd axiom-quickstart
The quickstart uses Node.js and Foundry, so you'll need to install them. For convenience, here's the install commands:
# install nvm
curl -o- | bash
source ~/.bashrc
# Install latest LTS node
nvm install --lts
# install Foundry using Foundryup
curl -L | bash
You will also need to export a JSON-RPC provider URL as an environmental variable:
export PROVIDER_URI_GOERLI=<your provider url>
For the quickstart to work, your JSON-RPC provider will need to have access to an archive node.
Lastly we install the packages in the quickstart repo itself:
npm install
forge install

Writing an Axiom Query

An Axiom Query is specified by writing a special Axiom client circuit that uses historical Ethereum data and performs compute on that data. This can be done in Typescript using the @axiom-crypto/client package.
For this quickstart we'll just use an example circuit in axiom/circuit.ts. The circuit code is defined in a function called nonceIncrementor. This circuit takes in a variable blockNumber and address as input, makes a request to Axiom to verify the nonce of the address at the given blockNumber, and increments the nonce by 1 inside the circuit. The circuit outputs, which are forwarded to your callback contract, are [blockNumber, address, nonce + 1] as a bytes32[] array.

Smart Contract Integration

We need to provide a smart contract that the AxiomV2Query contract will call after Axiom has fulfilled the query specified above. This contract is what receives the outputs of the circuit we wrote above.
We have an example smart contract AxiomNonceIncrementor in src/AxiomNonceIncrementor.sol. This contract inherits the abstract contract AxiomV2Client which implements some generic scaffolding to set up a contract to receive Axiom callbacks. The functions to override are _validateAxiomV2Call and _axiomV2Callback.
In our example, in _axiomV2Callback we receive [blockNumber, address, nonceInc] from the callback and simply store nonceInc in a mapping blockToAddrToNonceInc[blockNumber][address] = nonceInc and emit an event.
We have provided a Foundry test in test/AxiomNonceIncrementor.t.sol of deploying the example contract, sending a query, pranking Axiom fulfillment, and executing the callback. You can run it with
forge test --mt testAxiomFulfillQuery -vvvv
The verbose output of the test will show the details of the callback and the event our AxiomNonceIncrementor contract emits at the end of the callback function.

Testing On-Chain

In our Foundry test, we pranked the AxiomV2Query fulfillment for developer convenience. This means that the historical data of the account nonce was unverified. To fully test the Axiom integration, you will need to send your query on-chain for Axiom to fulfill. To learn how to do that, go to Sending Queries On-Chain.

Next Steps

Congratulations, you've finished the quickstart! For a more in-depth explanation of how to build this quickstart from scratch, head over to Getting Started.
Last modified 4d ago