AbiEvent

Utilities & types for working with Events on ABIs.

AbiEvent is a sub-type of AbiItem.

Examples

Below are some examples demonstrating common usages of the AbiEvent module:

Instantiating via JSON ABI

An AbiEvent can be instantiated from a JSON ABI by using AbiEvent.fromAbi:

import { Abi, AbiEvent } from 'ox'
 
const abi = Abi.from([
  'function foo()',
  'event Transfer(address owner, address to, uint256 tokenId)',
  'function bar(string a) returns (uint256 x)',
])
 
const 
const item: {
    readonly name: "Transfer";
    readonly type: "event";
    readonly inputs: readonly [...];
}item = AbiEvent.fromAbi(abi, 'Transfer')

Instantiating via Human-Readable ABI Item

An AbiEvent can be instantiated from a human-readable ABI by using AbiEvent.from:

import { AbiEvent } from 'ox'
 
const transfer = AbiEvent.from(
  'event Transfer(address indexed from, address indexed to, uint256 value)'
)
 
const transfer: {
    readonly name: "Transfer";
    readonly type: "event";
    readonly inputs: readonly [{
        readonly type: "address";
        readonly name: "from";
        readonly indexed: true;
    }, {
        readonly type: "address";
        readonly name: "to";
        readonly indexed: true;
    }, {
        ...;
    }];
}transfer

Encoding to Event Topics

Encode an AbiEvent into topics using AbiEvent.encode:

import { AbiEvent } from 'ox'
 
const transfer = AbiEvent.from(
  'event Transfer(address indexed from, address indexed to, uint256 value)'
)
 
const { topics } = AbiEvent.encode(transfer, {
  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
})
[
   '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0',
   '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
 ]

Decoding Event Topics and Data

Event topics and data can be decoded using AbiEvent.decode:

import { AbiEvent } from 'ox'
 
const transfer = AbiEvent.from(
  'event Transfer(address indexed from, address indexed to, uint256 value)'
)
 
const log = {
  // ...
  data: '0x0000000000000000000000000000000000000000000000000000000000000001',
  topics: [
    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    '0x000000000000000000000000a5cc3c03994db5b0d9a5eedd10cabab0813678ac',
    '0x000000000000000000000000a5cc3c03994db5b0d9a5eedd10cabab0813678ac',
  ],
} as const
 
const decoded = AbiEvent.decode(transfer, log)
{
   from: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
   to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
   value: 1n
 }

Functions

Name	Description
`AbiEvent.assertArgs`	Asserts that the provided arguments match the decoded log arguments.
`AbiEvent.decode`	ABI-Decodes the provided Log Topics and Data according to the ABI Event's parameter types (`input`).
`AbiEvent.encode`	ABI-encodes the provided event input (`inputs`) into an array of Event Topics.
`AbiEvent.format`	Formats an `AbiEvent.AbiEvent` into a Human Readable ABI Error.
`AbiEvent.from`	Parses an arbitrary JSON ABI Event or Human Readable ABI Event into a typed `AbiEvent.AbiEvent`.
`AbiEvent.fromAbi`	Extracts an `AbiEvent.AbiEvent` from an `Abi.Abi` given a name and optional arguments.
`AbiEvent.getSelector`	Computes the event selector (hash of event signature) for an `AbiEvent.AbiEvent`.

Errors

Name	Description
`AbiEvent.ArgsMismatchError`	Thrown when the provided arguments do not match the expected arguments.
`AbiEvent.DataMismatchError`	Thrown when the provided data size does not match the expected size from the non-indexed parameters.
`AbiEvent.FilterTypeNotSupportedError`	Thrown when the provided filter type is not supported.
`AbiEvent.InputNotFoundError`	Thrown when no argument was found on the event signature.
`AbiEvent.SelectorTopicMismatchError`	Thrown when the provided selector does not match the expected selector.
`AbiEvent.TopicsMismatchError`	Thrown when the provided topics do not match the expected number of topics.

Types

Name	Description
`AbiEvent.AbiEvent`	Root type for an `AbiItem.AbiItem` with an `event` type.
`AbiEvent.ExtractNames`
`AbiEvent.FromAbi`	Extracts an `AbiEvent.AbiEvent` item from an `Abi.Abi`, given a name.
`AbiEvent.Name`	Extracts the names of all `AbiError.AbiError` items in an `Abi.Abi`.