# AbiEvent

Utilities & types for working with [Events](https://docs.soliditylang.org/en/latest/abi-spec.html#json) on ABIs.

`AbiEvent` is a sub-type of [`AbiItem`](/api/AbiItem).

## Examples

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

* [Instantiating via JSON ABI](#instantiating-via-json-abi)

* [Instantiating via Human-Readable ABI Item](#instantiating-via-human-readable-abi-item)

* [Encoding to Event Topics](#encoding-to-event-topics)

* [Decoding Event Topics and Data](#decoding-event-topics-and-data)

### Instantiating via JSON ABI

An `AbiEvent` can be instantiated from a JSON ABI by using [`AbiEvent.fromAbi`](/api/AbiEvent/fromAbi):

```ts twoslash
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 item = AbiEvent.fromAbi(abi, 'Transfer') // [!code focus]
//    ^?
```

### Instantiating via Human-Readable ABI Item

An `AbiEvent` can be instantiated from a human-readable ABI by using [`AbiEvent.from`](/api/AbiEvent/from):

```ts twoslash
import { AbiEvent } from 'ox'

const transfer = AbiEvent.from(
  'event Transfer(address indexed from, address indexed to, uint256 value)' // [!code hl]
)

transfer
//^?
```

### Encoding to Event Topics

Encode an `AbiEvent` into topics using [`AbiEvent.encode`](/api/AbiEvent/encode):

```ts twoslash
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', // [!code hl]
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8' // [!code hl]
})
// @log: [
// @log:   '0x406dade31f7ae4b5dbc276258c28dde5ae6d5c2773c5745802c493a2360e55e0',
// @log:   '0x00000000000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266',
// @log:   '0x0000000000000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8'
// @log: ]
```

### Decoding Event Topics and Data

Event topics and data can be decoded using [`AbiEvent.decode`](/api/AbiEvent/decode):

```ts twoslash
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)
// @log: {
// @log:   from: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
// @log:   to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
// @log:   value: 1n
// @log: }
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`AbiEvent.assertArgs`](/api/AbiEvent/assertArgs) | Asserts that the provided arguments match the decoded log arguments. |
| [`AbiEvent.decode`](/api/AbiEvent/decode) | ABI-Decodes the provided [Log Topics and Data](https://info.etherscan.com/what-is-event-logs/) according to the ABI Event's parameter types (`input`). |
| [`AbiEvent.decodeLog`](/api/AbiEvent/decodeLog) | Extracts an [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent) from an [`Abi.Abi`](/api/Abi/types#abi) and decodes its arguments from a Log. |
| [`AbiEvent.encode`](/api/AbiEvent/encode) | ABI-encodes the provided event input (`inputs`) into an array of [Event Topics](https://info.etherscan.com/what-is-event-logs/). |
| [`AbiEvent.extractLogs`](/api/AbiEvent/extractLogs) | Extracts and decodes Logs that match an ABI Event in an ABI. |
| [`AbiEvent.format`](/api/AbiEvent/format) | Formats an [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent) into a **Human Readable ABI Error**. |
| [`AbiEvent.from`](/api/AbiEvent/from) | Parses an arbitrary **JSON ABI Event** or **Human Readable ABI Event** into a typed [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent). |
| [`AbiEvent.fromAbi`](/api/AbiEvent/fromAbi) | Extracts an [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent) from an [`Abi.Abi`](/api/Abi/types#abi) given a name and optional arguments. |
| [`AbiEvent.getSelector`](/api/AbiEvent/getSelector) | Computes the event selector (hash of event signature) for an [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent). |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`AbiEvent.ArgsMismatchError`](/api/AbiEvent/errors#abieventargsmismatcherror) | Thrown when the provided arguments do not match the expected arguments. |
| [`AbiEvent.DataMismatchError`](/api/AbiEvent/errors#abieventdatamismatcherror) | Thrown when the provided data size does not match the expected size from the non-indexed parameters. |
| [`AbiEvent.FilterTypeNotSupportedError`](/api/AbiEvent/errors#abieventfiltertypenotsupportederror) | Thrown when the provided filter type is not supported. |
| [`AbiEvent.InputNotFoundError`](/api/AbiEvent/errors#abieventinputnotfounderror) | Thrown when no argument was found on the event signature. |
| [`AbiEvent.SelectorTopicMismatchError`](/api/AbiEvent/errors#abieventselectortopicmismatcherror) | Thrown when the provided selector does not match the expected selector. |
| [`AbiEvent.SelectorTopicNotFoundError`](/api/AbiEvent/errors#abieventselectortopicnotfounderror) | Thrown when the selector topic is not found. |
| [`AbiEvent.TopicsMismatchError`](/api/AbiEvent/errors#abieventtopicsmismatcherror) | Thrown when the provided topics do not match the expected number of topics. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abieventabievent) | Root type for an [`AbiItem.AbiItem`](/api/AbiItem/types#abiitem) with an `event` type. |
| [`AbiEvent.ExtractNames`](/api/AbiEvent/types#abieventextractnames) |  |
| [`AbiEvent.FromAbi`](/api/AbiEvent/types#abieventfromabi) | Extracts an [`AbiEvent.AbiEvent`](/api/AbiEvent/types#abievent) item from an [`Abi.Abi`](/api/Abi/types#abi), given a name. |
| [`AbiEvent.Name`](/api/AbiEvent/types#abieventname) | Extracts the names of all [`AbiError.AbiError`](/api/AbiError/types#abierror) items in an [`Abi.Abi`](/api/Abi/types#abi). |