> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ABI Decoding Overview

> Transform raw EVM event logs and transaction calldata into structured, typed rows using Solidity ABI definitions.

ABI decoding is an optional pipeline stage that transforms raw EVM event logs or transaction calldata into structured, typed rows using Solidity ABI definitions. It is activated when an `abi` section is present in your pipeline configuration.

## What is an ABI?

An **ABI** (Application Binary Interface) is the JSON description of a smart contract's interface: its functions and events, with the name and Solidity type of every input and output. EVM logs and transaction calldata are emitted as raw, unlabeled hex, and the ABI is the schema that says how to decode that hex back into named, typed fields. Block explorers use a contract's ABI to display human-readable events and function calls instead of raw bytes.

The Pipeline API applies the same idea at stream scale: you supply an ABI, and matching logs and calldata are decoded into structured, typed rows automatically.

## Applicability

ABI decoding only applies to the following topic entities:

* **`logs`** - raw event logs emitted by smart contracts.
* **`transactions`** - raw transaction calldata submitted to the network.

<Warning>
  ABI decoding is incompatible with the Kafka (raw) destination. Pipelines that combine ABI decoding with a Kafka destination are rejected at startup.
</Warning>

## Decoders

The pipeline provides two decoders, each responsible for a different entity type:

| Decoder             | Input Entity   | Output Tables                            |
| ------------------- | -------------- | ---------------------------------------- |
| **EventDecoder**    | `logs`         | `{chain_name}_evt_{event_name}` tables   |
| **FunctionDecoder** | `transactions` | `{chain_name}_fn_{function_name}` tables |

### Data Flow

```
╔═════════════════════╗      ╔═════════════════╗      ╔═══════════════════════════════════════════════════╗
║ logs stream         ║░ ──▶ ║ EventDecoder    ║░ ──▶ ║ base_evt_swap, base_evt_transfer, ...             ║░
╚═════════════════════╝░     ╚═════════════════╝░     ╚═══════════════════════════════════════════════════╝░
 ░░░░░░░░░░░░░░░░░░░░░░░      ░░░░░░░░░░░░░░░░░░░      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

╔═════════════════════╗      ╔═════════════════╗      ╔═══════════════════════════════════════════════════╗
║ transactions stream ║░ ──▶ ║ FunctionDecoder ║░ ──▶ ║ base_fn_exact_input_single, base_fn_transfer, ... ║░
╚═════════════════════╝░     ╚═════════════════╝░     ╚═══════════════════════════════════════════════════╝░
 ░░░░░░░░░░░░░░░░░░░░░░░      ░░░░░░░░░░░░░░░░░░░      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
```

Raw log or transaction rows flow through the appropriate decoder, which matches each record against the provided ABI. Matched records are emitted into named output tables derived from the event or function name. Unmatched records are either dropped or routed to a raw fallback table, depending on your configuration.

## Configuration

Add the `abi` section to your pipeline configuration to enable decoding:

```yaml theme={null}
abi:
  path: "/etc/pipeline-api/abi.json"
  contract_addresses:
    - "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45"
  unmatched: "skip"
```

### Fields

| Field                | Type   | Required | Default | Description                                                                                                                               |
| -------------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `path`               | string | Yes      | --      | Path to the ABI JSON file. Must conform to the standard Solidity ABI JSON format.                                                         |
| `contract_addresses` | list   | No       | --      | Optional list of contract addresses to filter on. When omitted, all contracts are decoded.                                                |
| `unmatched`          | string | No       | `skip`  | Strategy for records that do not match any ABI entry. `skip` drops the record; `raw_table` writes it to `raw_logs` or `raw_transactions`. |

## Next Steps

<CardGroup cols={3}>
  <Card title="Event Decoding" href="/goldrush-pipeline-api/abi-decoding/event-decoding">
    Decode event logs into structured evt\_ tables.
  </Card>

  <Card title="Function Decoding" href="/goldrush-pipeline-api/abi-decoding/function-decoding">
    Decode transaction calldata into structured fn\_ tables.
  </Card>

  <Card title="Reference" href="/goldrush-pipeline-api/abi-decoding/reference">
    ABI file format, type mappings, and filtering behavior.
  </Card>
</CardGroup>