> ## 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 Reference

> ABI file format, Solidity type mapping, contract address filtering, and unmatched record handling.

## ABI File Format

The pipeline accepts standard Solidity ABI JSON files. Only `event` and `function` entries are used - all other entry types (constructor, fallback, receive) are ignored.

```json theme={null}
[
  {
    "type": "event",
    "name": "Transfer",
    "inputs": [
      { "name": "from", "type": "address", "indexed": true },
      { "name": "to", "type": "address", "indexed": true },
      { "name": "value", "type": "uint256", "indexed": false }
    ]
  },
  {
    "type": "function",
    "name": "transfer",
    "stateMutability": "nonpayable",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ]
  }
]
```

You can obtain ABI files from:

* Block explorers (Etherscan, Basescan) under the "Contract" tab
* Solidity compiler output (`artifacts/` directory)
* The `cast interface` command from Foundry

<Tip>
  You can combine multiple contract ABIs into a single file. The decoder uses event signature hashes and function selectors for matching, so entries from different contracts do not conflict as long as names are unique.
</Tip>

## Solidity Type Mapping

| Solidity Type              | Column Type | Notes                             |
| -------------------------- | ----------- | --------------------------------- |
| `address`                  | STRING      | Hex-encoded, checksummed          |
| `uint8` through `uint256`  | STRING      | Full precision as decimal strings |
| `int8` through `int256`    | STRING      | Full precision as decimal strings |
| `bool`                     | BOOLEAN     |                                   |
| `bytes`                    | STRING      | Hex-encoded with `0x` prefix      |
| `bytes1` through `bytes32` | STRING      | Hex-encoded with `0x` prefix      |
| `string`                   | STRING      |                                   |
| `tuple`                    | JSON        | JSON-serialized object            |
| Arrays (e.g., `uint256[]`) | JSON        | JSON-serialized array             |

<Note>
  All integer types are stored as decimal strings to preserve full precision. Solidity `uint256` values can exceed the range of 64-bit integers, so string representation avoids truncation.
</Note>

## Contract Address Filtering

When `contract_addresses` is specified in the ABI config, only matching records are decoded:

| Decoding Mode     | Filter Field       | Description                         |
| ----------------- | ------------------ | ----------------------------------- |
| Event decoding    | `contract_address` | The contract that emitted the event |
| Function decoding | `to_address`       | The contract that was called        |

When the list is empty or omitted, all records are decoded regardless of contract address.

Records from contracts not in the filter list are subject to the `unmatched` strategy.

## Unmatched Records

When a log or transaction does not match any ABI signature (either because it's from a non-matching contract or because the signature is not in the ABI file):

| `unmatched` Setting | Behavior                                                                     |
| ------------------- | ---------------------------------------------------------------------------- |
| `skip` (default)    | Drop the record silently                                                     |
| `raw_table`         | Write to `raw_logs` or `raw_transactions` table with original columns intact |

Use `raw_table` when you want to capture all records and handle unmatched ones separately in your downstream processing.

## Configuration Reference

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

| Field                | Type   | Required | Default | Description                                                   |
| -------------------- | ------ | -------- | ------- | ------------------------------------------------------------- |
| `path`               | string | yes      | -       | Path to ABI JSON file                                         |
| `contract_addresses` | list   | no       | all     | Contract address whitelist. Decodes all contracts when empty. |
| `unmatched`          | string | no       | `skip`  | How to handle records that don't match any ABI signature      |

## Validation

The pipeline validates ABI configuration at startup:

* ABI file must exist and be valid JSON
* ABI file must contain at least one `event` or `function` entry relevant to the topic entity
* ABI decoding is only compatible with `logs` and `transactions` topic entities
* ABI decoding is incompatible with the Kafka (raw) destination type
* Output table names from ABI entries must not collide with each other or with normalizer output tables

<Warning>
  If validation fails, the pipeline will not start. Check the error message in the GoldRush Platform dashboard for details on which validation check failed.
</Warning>