Skip to main content
Version: FireSquid

EVM logs

addLog(contract: string | string[], options?): Subscribe to EVM log data (events) emitted by specific contracts.

The optional options? argument defines:

  • filters by block range and topic, and
  • data selectors to specify the data provided by the corresponding item:
{
range?: Range,
filter?: EvmTopicSet[],
data?: {
evmLog: {
// data selection, a subset of EvmLog fields
},
transaction: {
// data selection for the associated transaction,
// a subset of EvmTransaction fields
}
}
}

Filters

Topic filter format is a (fully expressive) subset of Ethers.js filter specification.

FilterMatching Logs
[ A ]topic[0] == A
[ [], B ]topic[1] == B
[ A, B ] or [A, [B]](topic[0] == A) AND (topic[1] = B)
[[ A, B ]](topic[0] == A) OR (topic[1] = B)
[ [ A, B ], [ C, D ] ][ (topic[0] == A) OR (topic[0] == B) ] AND [ (topic[1] == C) OR (topic[1] == D) ]

The difference here is due to EvmTopicSet being a non-nullable type: instead of nulls empty lists [] must be used. See examples below.

EvmBatchProcessors subscribed to events also always retrieve the transactions that emitted the events and place them immediately after their event log items in the batch.

Data Selectors

The optional data? field is expected to contain a data selector:

data: {
evmLog: {
// data selector for the event item
},
transaction: {
// data selector for the tx emitted the event
}
}

The requested fields will be populated in the corresponding items of the processor.run() context.

Examples

  1. Fetch NewGravatar(uint256,address,string,string) and UpdateGravatar(uint256,address,string,string) event logs emitted by 0x2E645469f354BB4F5c8a05B3b30A929361cf77eC. For each log, fetch transaction input, topic set and log data.
const processor = new EvmBatchProcessor()
.setDataSource({
archive: lookupArchive('eth-mainnet'),
})
.addLog('0x2e645469f354bb4f5c8a05b3b30a929361cf77ec', {
filter: [[
// topic: 'NewGravatar(uint256,address,string,string)'
'0x9ab3aefb2ba6dc12910ac1bce4692cf5c3c0d06cff16327c64a3ef78228b130b',
// topic: 'UpdatedGravatar(uint256,address,string,string)'
'0x76571b7a897a1509c641587568218a290018fbdc8b9a724f17b77ff0eec22c0c',
]],
data: {
evmLog: {
topics: true,
data: true,
},
transaction: {
input: true
}
},
})
  1. Fetch every Transfer(address,address,uint256) event on Ethereum mainnet where topic2 is set to the destination address (a common but non-standard practice) and the destination is vitalik.eth a.k.a. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045. For each log, fetch transaction hash and log data.
const processor = new EvmBatchProcessor()
.setDataSource({
archive: 'https://eth.archive.subsquid.io'
})
.addLog([], {
filter: [
// topic0: 'Transfer(address,address,uint256)'
[ '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef' ],
// topic1: anything goes
[],
// topic2: vitalik.eth
[ '0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045' ]
],
data: {
evmLog: { id: true, data: true },
transaction: { hash: true }
} as const
})
info

Typescript ABI modules generated by squid-evm-typegen provide event signatures/topic0 values as constants, e.g.

  import * as gravatarAbi from './abi/gravatar'
// ...
filter: [[
gravatarAbi.events.NewGravatar.topic,
gravatarAbi.events.UpdatedGravatar.topic,
]],
// ...