getLogs
Returns a list of event logs matching the provided parameters.
Usage
By default, getLogs returns all events. In practice, you must use scoping to filter for specific events.
import { publicClient } from '.'
const logs = await publicClient.getLogs()
// [{ ... }, { ... }, { ... }]
Scoping
You can also scope to a set of given attributes.
import { parseAbiItem } from 'viem'
import { publicClient } from '.'
const logs = await publicClient.getLogs({
address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
},
fromBlock: 16330000n,
toBlock: 16330050n
})
By default, event accepts the AbiEvent type:
import { publicClient } from '.'
const filter = await publicClient.getLogs(publicClient, {
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: {
name: 'Transfer',
inputs: [
{ type: 'address', indexed: true, name: 'from' },
{ type: 'address', indexed: true, name: 'to' },
{ type: 'uint256', indexed: false, name: 'value' }
]
},
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
},
fromBlock: 16330000n,
toBlock: 16330050n
})
Address
A Filter can be scoped to an address:
const filter = await publicClient.getLogs({
address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})
Event
A Filter can be scoped to an event.
The event argument takes in an event in ABI format – we have a parseAbiItem utility that you can use to convert from a human-readable event signature → ABI.
import { parseAbiItem } from 'viem'
import { publicClient } from '.'
const filter = await publicClient.getLogs({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
})
Arguments
A Filter can be scoped to given indexed arguments:
const filter = await publicClient.getLogs({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
}
})
Only indexed arguments in event are candidates for args.
A Filter Argument can also be an array to indicate that other values can exist in the position:
const filter = await publicClient.getLogs({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
// '0xd8da...' OR '0xa5cc...' OR '0xa152...'
from: [
'0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
'0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
'0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
],
}
})
Block Range
A Filter can be scoped to a block range:
const filter = await publicClient.getLogs({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
fromBlock: 16330000n,
toBlock: 16330050n
})
Returns
A list of event logs.
Parameters
address
- Type:
Address | Address[]
A contract address or a list of contract addresses. Only logs originating from the contract(s) will be included in the result.
const logs = await publicClient.getLogs({
address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
})
event
- Type:
AbiEvent
The event in ABI format.
A parseAbiItem utility is exported from viem that converts from a human-readable event signature → ABI.
const logs = await publicClient.getLogs({
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
})
args
- Type: Inferred.
A list of indexed event arguments.
const logs = await publicClient.getLogs({
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
},
})
fromBlock
- Type:
bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'
Block to start including logs from. Mutually exclusive with blockHash.
const filter = await publicClient.createEventFilter({
fromBlock: 69420n
})
toBlock
- Type:
bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'
Block to stop including logs from. Mutually exclusive with blockHash.
const filter = await publicClient.createEventFilter({
toBlock: 70120n
})
blockHash
- Type:
'0x${string}'
Block hash to include logs from. Mutually exclusive with fromBlock/toBlock.
const logs = await publicClient.getLogs({
blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d'
})
Live Example
Check out the usage of getLogs in the live Event Logs Example below.