Skip to main content
Version: Old ArrowSquid docs

Data requests

info

Check out the Caveats section to avoid common mistakes.

Events

addEvent(options): Subscribe to Substrate runtime events. options has the following structure:

{
// data requests
name?: string[]
range?: {from: number, to?: number}

// related data retrieval
call?: boolean
stack?: boolean
extrinsic?: boolean
}

names must follow the convention ${Pallet}.${NameWithinPallet} with both parts usually capitalized, e.g. Balances.Transfer.

You may also request the data related to the events:

  • with call = true the processor will retrieve the parent call and add it to the calls iterable within the block data;
  • with stack = true it will do that with all calls in the entire call stack;
  • with extrinsic = true it will add the parent extrinsic to the extrinsics block data iterable.

Note than events can also be requested by the addCall() method as related data.

Selection of the exact data to be retrieved for each log and its optional parent transaction is done with the setFields() method documented on the Fields selection page.

Calls

addCall(options): Subscribe to runtime calls (even if wrapped into a system.sudo or util.batch extrinsic). options has the following structure:

{   
// data requests
name?: string[]
range?: {from: number, to?: number}

// related data retrieval
events?: boolean
stack?: boolean
extrinsic?: boolean
}

The name must follow the convention ${Pallet}.${call_name}. The pallet name is normally capitalized, and the call name is in the snake_case format, as in Balances.transfer_keep_alive.

By default, both successful and failed calls are fetched. Select the call.success field and later check it within the batch handler if you need to disambiguate.

You may also request the data related to the calls:

  • with events = true the processor will retrieve all the events that the call emitted and add them to the events iterable within the block data;
  • with stack = true it will add all calls in the stack of each matching call, including itself, to the calls iterable;
  • with extrinsic = true it will add the parent extrinsic to the extrinsics block data iterable.

Note than calls can also be requested by the addEvent() method as related data.

Selection of the exact data to be retrieved for each log and its optional parent transaction is done with the setFields() method documented on the Fields selection page.

Specialized setters

addEvmLog()
addEthereumTransaction()
Subscribe to Frontier EVM transactions and event logs. See EVM Support.

addContractsContractEmitted()
Subscribe to events emitted by a WASM contract. See WASM Support.

addGearMessageEnqueued() addGearUserMessageSent() Subscribe to messages emitted by a Gear program. See Gear Support.

Caveats

  • Processor data subscription methods guarantee that all data matching their data requests will be retrieved, but for technical reasons non-matching data may be added to the batch context iterables. As such, it is important to always filter the data within the batch handler. For example, a processor config like this

    src/procesor.ts
    export const processor = new SubstrateBatchProcessor()
    .addEvent({
    name: ['Balances.Transfer']
    })
    // the rest of the configuration

    should always be matched with

    src/main.ts
    processor.run(database, async ctx => {
    // ...
    for (let block of ctx.blocks) {
    for (let event of block.events) {
    if (event.name==='Balances.Transfer') { // <- this filter
    // process Balances.Transfer
    }
    }
    }
    // ...
    })

    even if no other events were requested.

  • The meaning of passing [] as a set of parameter values has been changed in the ArrowSquid release: now it selects no data. Some data might still arrive (see above), but that's not guaranteed. Pass undefined for a wildcard selection:

    .addEvent({name: []}) // selects no events
    .addEvent({}) // selects all events