# `Onchain.Log`
[🔗](https://github.com/ZenHive/onchain/blob/v0.5.0/lib/onchain/log.ex#L1)

Event log parsing for Ethereum contract events.

Computes event topic hashes from signatures and decodes raw log data
against event signatures with indexed parameter markers.

## Limitations

- Tuple-typed params (e.g. `(uint256,address)`) are not supported in event signatures.
  The comma-based parser cannot distinguish tuple-internal commas from param separators.
- Indexed dynamic types (string, bytes, arrays) return the raw keccak256 topic hash
  since the original value is not recoverable from the log.

## Error Format

- Invalid signature: `{:error, {:invalid_signature, input}}`
- Topic mismatch: `{:error, {:decode_error, {:topic_mismatch, [expected: ..., got: ...]}}}`
- Decode errors: `{:error, {:decode_error, reason}}`

## Functions

| Function | Purpose |
|----------|---------|
| `event_topic/1` | Event signature → keccak256 topic hash |
| `event_topic!/1` | Same, raises on error |
| `decode_event/2` | Raw log + signature → decoded param map |
| `decode_event!/2` | Same, raises on error |

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `decode_event!` | 2 | Decode a raw log map. Raises on error. | `log: value`, `signature: value` |
| `decode_event` | 2 | Decode a raw log map against an event signature with indexed markers. | `log: value`, `signature: value` |
| `event_topic!` | 1 | Compute the keccak256 topic hash. Raises on error. | `signature: value` |
| `event_topic` | 1 | Compute the keccak256 topic hash for an event signature. | `signature: value` |

# `decode_event`

```elixir
@spec decode_event(map(), String.t()) :: {:ok, map()} | {:error, term()}
```

Decode a raw log map against an event signature with indexed markers.

## Parameters

  * `log` - Raw log map with :topics (list of hex strings) and :data (hex string) keys (value)
  * `signature` - Event signature with indexed markers, e.g. "Transfer(address indexed from, address indexed to, uint256 value)" (value)

## Returns

Map with atom keys for each decoded parameter (`{:ok, map} | {:error, term}`)

```elixir
# descripex:contract
%{
  params: %{
    log: %{
      description: "Raw log map with :topics (list of hex strings) and :data (hex string) keys",
      kind: :value
    },
    signature: %{
      description: "Event signature with indexed markers, e.g. \"Transfer(address indexed from, address indexed to, uint256 value)\"",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, map} | {:error, term}",
    description: "Map with atom keys for each decoded parameter",
    example: "%{from: \"0xAb5...\", to: \"0xCd9...\", value: 1000000}"
  }
}
```

# `decode_event!`

```elixir
@spec decode_event!(map(), String.t()) :: map()
```

Decode a raw log map. Raises on error.

## Parameters

  * `log` - Raw log map with :topics and :data keys (value)
  * `signature` - Event signature with indexed markers (value)

## Returns

Map with atom keys for each decoded parameter (`map`)

```elixir
# descripex:contract
%{
  params: %{
    log: %{description: "Raw log map with :topics and :data keys", kind: :value},
    signature: %{
      description: "Event signature with indexed markers",
      kind: :value
    }
  },
  returns: %{
    type: :map,
    description: "Map with atom keys for each decoded parameter"
  }
}
```

# `event_topic`

```elixir
@spec event_topic(String.t()) :: {:ok, String.t()} | {:error, term()}
```

Compute the keccak256 topic hash for an event signature.

## Parameters

  * `signature` - Event signature without param names, e.g. "Transfer(address,address,uint256)" (value)

## Returns

0x-prefixed 32-byte keccak256 hash (`{:ok, hex_string} | {:error, term}`)

```elixir
# descripex:contract
%{
  params: %{
    signature: %{
      description: "Event signature without param names, e.g. \"Transfer(address,address,uint256)\"",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, hex_string} | {:error, term}",
    description: "0x-prefixed 32-byte keccak256 hash",
    example: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
  }
}
```

# `event_topic!`

```elixir
@spec event_topic!(String.t()) :: String.t()
```

Compute the keccak256 topic hash. Raises on error.

## Parameters

  * `signature` - Event signature string (value)

## Returns

0x-prefixed 32-byte keccak256 hash (`string`)

```elixir
# descripex:contract
%{
  params: %{signature: %{description: "Event signature string", kind: :value}},
  returns: %{type: :string, description: "0x-prefixed 32-byte keccak256 hash"}
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*