# AbiFunction

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

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

## Examples

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

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

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

* [Encoding to Function Data](#encoding-to-function-data)

* [Decoding a Function's Result](#decoding-a-function's-result)

### Instantiating via JSON ABI

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

```ts twoslash
import { Abi, AbiFunction } 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 = AbiFunction.fromAbi(abi, 'bar') // [!code focus]
//    ^?
```

### Instantiating via Human-Readable ABI Item

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

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

const bar = AbiFunction.from(
  'function bar(string a) returns (uint256 x)'
)

bar
//^?
```

### Encoding to Function Data

A Function and its arguments can be ABI-encoded into data using the [`AbiFunction.encodeData`](/api/AbiFunction/encodeData) function. The output of this function can then be passed to `eth_sendTransaction` or `eth_call` as the `data` parameter.

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

const approve = AbiFunction.from(
  'function approve(address, uint256)'
)

const data = AbiFunction.encodeData(
  // [!code focus]
  approve, // [!code focus]
  ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 69420n] // [!code focus]
) // [!code focus]
// @log: '0x095ea7b3000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa960450000000000000000000000000000000000000000000000000000000000010f2c'
```

### Decoding a Function's Result

A Function's result can be ABI-decoded using the [`AbiFunction.decodeResult`](/api/AbiFunction/decodeResult) function.

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

const data =
  '0x000000000000000000000000000000000000000000000000000000000000002a'
//    ↑ Example data that could be returned from a contract call via `eth_call`.

const totalSupply = AbiFunction.from(
  'function totalSupply() returns (uint256)'
)

const output = AbiFunction.decodeResult(totalSupply, data) // [!code focus]
// @log: 42n
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`AbiFunction.decodeData`](/api/AbiFunction/decodeData) | ABI-decodes function arguments according to the ABI Item's input types (`inputs`). |
| [`AbiFunction.decodeResult`](/api/AbiFunction/decodeResult) | ABI-decodes a function's result according to the ABI Item's output types (`outputs`). |
| [`AbiFunction.encodeData`](/api/AbiFunction/encodeData) | ABI-encodes function arguments (`inputs`), prefixed with the 4 byte function selector. |
| [`AbiFunction.encodeResult`](/api/AbiFunction/encodeResult) | ABI-encodes a function's result (`outputs`). |
| [`AbiFunction.format`](/api/AbiFunction/format) | Formats an [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction) into a **Human Readable ABI Function**. |
| [`AbiFunction.from`](/api/AbiFunction/from) | Parses an arbitrary **JSON ABI Function** or **Human Readable ABI Function** into a typed [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction). |
| [`AbiFunction.fromAbi`](/api/AbiFunction/fromAbi) | Extracts an [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction) from an [`Abi.Abi`](/api/Abi/types#abi) given a name and optional arguments. |
| [`AbiFunction.getSelector`](/api/AbiFunction/getSelector) | Computes the [4-byte selector](https://solidity-by-example.org/function-selector/) for an [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction). |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunctionabifunction) | Root type for an [`AbiItem.AbiItem`](/api/AbiItem/types#abiitem) with a `function` type. |
| [`AbiFunction.ExtractNames`](/api/AbiFunction/types#abifunctionextractnames) |  |
| [`AbiFunction.FromAbi`](/api/AbiFunction/types#abifunctionfromabi) | Extracts an [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction) item from an [`Abi.Abi`](/api/Abi/types#abi), given a name. |
| [`AbiFunction.Name`](/api/AbiFunction/types#abifunctionname) | Extracts the names of all [`AbiFunction.AbiFunction`](/api/AbiFunction/types#abifunction) items in an [`Abi.Abi`](/api/Abi/types#abi). |