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

# Event Log Decoding

> Decode raw EVM event logs into structured evt_ tables using Solidity ABI event definitions.

The EventDecoder transforms raw event log rows into structured, typed output tables. Each matched event produces a table named `{chain_name}_evt_{event_name_snake_case}` with columns derived from the event's ABI parameters.

## How It Works

<Steps>
  <Step title="Normalization">
    The LogsNormalizer upstream produces rows containing `raw_log_topics` (a JSON array of 32-byte hex topics) and `raw_log_data` (a hex-encoded byte string).
  </Step>

  <Step title="Signature Matching">
    The EventDecoder reads `topics[0]`, which is the keccak256 hash of the event signature (e.g., `Transfer(address,address,uint256)`), and matches it against event entries in the provided ABI file.
  </Step>

  <Step title="Indexed Parameter Decoding">
    Indexed parameters are decoded from `topics[1..N]`. Each indexed parameter occupies exactly one topic slot. Note that dynamic types (`string`, `bytes`, arrays) produce a keccak256 hash rather than the original value when indexed.
  </Step>

  <Step title="Non-Indexed Parameter Decoding">
    Non-indexed parameters are ABI-decoded from `raw_log_data` according to standard Solidity ABI encoding rules.
  </Step>

  <Step title="Table Emission">
    The decoded row is emitted to a table named `{chain_name}_evt_{event_name_snake_case}`. For example, a `Swap` event on the Base chain produces rows in the `base_evt_swap` table.
  </Step>
</Steps>

## Output Schema

Every `{chain_name}_evt_` table includes a set of envelope columns inherited from the raw log, followed by the decoded ABI parameters.

### Envelope Columns

| Column             | Type      | Source             |
| ------------------ | --------- | ------------------ |
| `block_height`     | UINT64    | From logs envelope |
| `block_signed_at`  | TIMESTAMP | From logs envelope |
| `tx_hash`          | STRING    | From logs envelope |
| `log_offset`       | UINT32    | From logs envelope |
| `contract_address` | STRING    | From logs envelope |

### ABI Parameter Columns

Each parameter defined in the event ABI becomes an additional column. The column name is the parameter name converted to `snake_case`, and the column type is determined by the [Solidity type mapping](/goldrush-pipeline-api/abi-decoding/reference#solidity-type-mapping).

## Worked Example: Uniswap V3 Swap

Consider the Uniswap V3 `Swap` event:

```solidity theme={null}
event Swap(
    address indexed sender,
    address indexed recipient,
    int256 amount0,
    int256 amount1,
    uint160 sqrtPriceX96,
    uint128 liquidity,
    int24 tick
);
```

* `sender` and `recipient` are **indexed** - decoded from `topics[1]` and `topics[2]`.
* `amount0`, `amount1`, `sqrtPriceX96`, `liquidity`, and `tick` are **non-indexed** - decoded from `raw_log_data`.

### Resulting `base_evt_swap` Table

| Column             | Type      |
| ------------------ | --------- |
| `block_height`     | UINT64    |
| `block_signed_at`  | TIMESTAMP |
| `tx_hash`          | STRING    |
| `log_offset`       | UINT32    |
| `contract_address` | STRING    |
| `sender`           | STRING    |
| `recipient`        | STRING    |
| `amount0`          | STRING    |
| `amount1`          | STRING    |
| `sqrt_price_x96`   | STRING    |
| `liquidity`        | STRING    |
| `tick`             | STRING    |

<Info>
  Integer types (`int256`, `uint160`, `uint128`, `int24`) are represented as STRING columns to preserve full precision. See the [type mapping reference](/goldrush-pipeline-api/abi-decoding/reference#solidity-type-mapping) for details.
</Info>

## Indexed Dynamic Types

When a dynamic type (`string`, `bytes`, or an array type) is marked as `indexed`, the EVM stores a keccak256 hash of the value in the topic slot rather than the value itself. The EventDecoder writes this hash as a hex string. There is no way to recover the original value from the hash alone.