Direct RPC queries
- squid-evm-typegen
- squid-substrate-typegen
- squid-ink-typegen
In order to make on-chain calls, one must set up a JSON-RPC endpoint using setRpcEndpoint(). We recommend using a private endpoint from e.g. BlastAPI or the SQD Cloud's RPC addon, and set it via an environment variable:
//...
.setRpcEndpoint(process.env.RPC_ETH_HTTP)
//...
You can define the RPC_ETH_HTTP
in three ways:
- for local runs, simply update the local
.env
file; - for squids deployed to Cloud define it as a secret on your Cloud account;
- if you are using the RPC addon, leave it to the Cloud to define it for you.
Contract
class
The EVM contract state is accessed using the Contract
class generated by squid-evm-typegen
. It takes a handler context and a contract address as constructor arguments. The state is always accessed at the context block height unless explicitly defined in the constructor.
For example, assume that we index an ERC721 contract. Typescript ABI module generated with squid-evm-typegen
will contain the following class:
export class Contract extends ContractBase {
//...
balanceOf(owner: string): Promise<ethers.BigNumber> {
return this.call('balanceOf', [owner])
}
//...
}
Now suppose we want to query our contract from the batch handler. To create a Contract
pass the context object and the current Block
to its constructor, then query the contract state at that block:
// ...
const CONTRACT_ADDRESS = '0xb654611f84a8dc429ba3cb4fda9fad236c505a1a'
processor.run(new TypeormDatabase(), async ctx => {
for (const block of ctx.blocks) {
const contract = new abi.Contract(ctx, block.header, CONTRACT_ADDRESS)
// query the contract state at the current block
const uri = await contract.balanceOf('0xd8da6bf26964af9d7eed9e03e53415d37aa96045')
// ...
}
})
Batch state queries
The MakerDAO Multicall contract was designed to batch multiple state queries into a single contract call. In the context of indexing, it normally significantly improves the indexing speed since JSON RPC calls are typically the bottleneck.
Multicall contracts are deployed in many EVM chains, see the contract repo for addresses. You can use any of them with a multicall
Typescript module that is generated when running squid-evm-typegen
with --multicall
option. The module exports a Multicall
class with this method:
tryAggregate<Args extends any[], R>(
func: Func<Args, {}, R>,
calls: [address: string, args: Args][],
paging?: number
): Promise<MulticallResult<R>[]>
The arguments are as follows:
func
: the contract function to be calledcalls
: an array of tuples[contractAddress: string, args]
. Each specified contract will be called with the specified arguments.paging
an (optional) argument for the maximal number of calls to be batched into a single JSON PRC request. Note that large page sizes may cause timeouts.
A typical usage is as follows:
// generated by evm-typegen
import { functions } from './abi/mycontract'
import { Multicall } from './abi/multicall'
const MY_CONTRACT = '0xac5c7493036de60e63eb81c5e9a440b42f47ebf5'
const MULTICALL_CONTRACT = '0x5ba1e12693dc8f9c48aad8770482f4739beed696'
processor.run(new TypeormDatabase(), async (ctx) => {
for (let c of ctx.blocks) {
// some logic
}
const lastBlock = ctx.blocks[ctx.blocks.length - 1]
const multicall = new Multicall(
ctx,
lastBlock,
MULTICALL_CONTRACT
)
// call MY_CONTRACT.myContractMethod('foo') and MY_CONTRACT.myContractMethod('bar')
const args = ['foo', 'bar']
const results = await multicall.tryAggregate(
functions.myContractMethod,
args.map(a => [MY_CONTRACT, a]) as [string, any[]],
100
)
results.forEach((res, i) => {
if (res.success) {
ctx.log.info(`Result for argument ${args[i]} is ${res.value}`)
}
})
})
It is sometimes impossible to extract the required data with only event and call data without querying the runtime state.
The context exposes a lightweight gRPC client to the chain node accessible via ctx._chain
.
It exposes low-level methods for accessing the storage. However, the recommended way to query the storage is with type-safe wrappers generated with squid-substrate-typegen
.
Substrate typegen tool exposes storage access wrappers at src/types/storage.ts
. The wrappers follow the general naming pattern used by Substrate typegen:
storage.${palletName}.${storageName}
with all identifiers lowerCamelCased. Each wrapper exposes a generated get()
query method and, if available, methods for multi-key queries, listing keys, key-value pairs and retrieving the default value.
Note that the generated getters always query historical blockchain state at the height derived from their block
argument.
Here is an example of one such wrapper:
import {sts, Block, Bytes, Option, Result, StorageType} from '../support'
import * as v1050 from '../v1050'
import * as v9420 from '../v9420'
export const account = {
v1050: new StorageType('Balances.Account', 'Default', [v1050.AccountId], v1050.AccountData) as AccountV1050,
v9420: new StorageType('Balances.Account', 'Default', [v9420.AccountId32], v9420.AccountData) as AccountV9420,
}
export interface AccountV1050 {
getDefault(block: Block): v1050.AccountData
get(block: Block, key: v1050.AccountId): Promise<v1050.AccountData | undefined>
getMany(block: Block, keys: v1050.AccountId[]): Promise<v1050.AccountData | undefined[]>
}
export interface AccountV9420 {
getDefault(block: Block): v9420.AccountData
get(block: Block, key: v9420.AccountId32): Promise<v9420.AccountData | undefined>
getMany(block: Block, keys: v9420.AccountId32[]): Promise<v9420.AccountData | undefined[]>
getKeys(block: Block): Promise<v9420.AccountId32[]>
getKeys(block: Block, key: v9420.AccountId32): Promise<v9420.AccountId32[]>
getKeysPaged(pageSize: number, block: Block): AsyncIterable<v9420.AccountId32[]>
getKeysPaged(pageSize: number, block: Block, key: v9420.AccountId32): AsyncIterable<v9420.AccountId32[]>
getPairs(block: Block): Promise<[k: v9420.AccountId32, v: v9420.AccountData | undefined][]>
getPairs(block: Block, key: v9420.AccountId32): Promise<[k: v9420.AccountId32, v: v9420.AccountData | undefined][]>
getPairsPaged(pageSize: number, block: Block): AsyncIterable<[k: v9420.AccountId32, v: v9420.AccountData | undefined][]>
getPairsPaged(pageSize: number, block: Block, key: v9420.AccountId32): AsyncIterable<[k: v9420.AccountId32, v: v9420.AccountData | undefined][]>
}
The generated access interface provides methods for accessing:
- the default storage value with
getDefault(block)
- a single storage value with
get(block, key)
- multiple values in a batch call with
getMany(block, keys[])
- all storage keys with
getKeys(block)
- all keys with a given prefix with
getKeys(block, keyPrefix)
(only if the storage keys are decodable) - paginated keys via
getKeysPaged(pageSize, block)
andgetKeysPaged(pageSize, block, keyPrefix)
- key-value pairs via
getPairs(block)
andgetPairs(block, keyPrefix)
- paginated key-value pairs via
getPairsPaged(pageSize, block)
andgetPairsPaged(pageSize, block, keyPrefix)
Example
import {storage} from './types'
processor.run(new TypeormDatabase(), async ctx => {
let aliceAddress = ss58.decode('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY').bytes
for (const blockData of ctx.blocks) {
if (storage.balances.account.v1050.is(blockData.header)) {
let aliceBalance = (await storage.balances.account.v1050.get(blockData.header, aliceAddress))?.free
ctx.log.info(`Alice free account balance at block ${blockData.header.height}: ${aliceBalance}`)
}
}
})
The generated Contract
class provides facades for all state calls that don't mutate the contract state. The info about the state mutability is taken from the contract metadata.
// Generated code:
export class Contract {
// optional blockHash indicates the block at which the state is queried
constructor(private ctx: ChainContext, private address: string, private blockHash?: string) { }
total_supply(): Promise<Balance> {
return this.stateCall('0xdb6375a8', [])
}
balance_of(owner: Uint8Array): Promise<bigint> {
return this.stateCall('0x6568382f', [owner])
}
}
Example
processor.run(new TypeormDatabase(), async ctx => {
for (let block of ctx.blocks) {
for (let event of block.events) {
// query the balance at the current block
const contract = new Contract(ctx, CONTRACT_ADDRESS, block.header.hash)
let aliceAddress = ss58.decode('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY').bytes
let aliceBalance = await contract.balance_of(aliceAddress)
}
}
})