# log_decode_json

Returns a status-rich JSON description of one EVM log; use it when unknown, ambiguous, and malformed logs must remain distinguishable.

Canonical HTML: <https://determica.com/docs/functions/log_decode_json>

- Kind: scalar function
- Category: [Contracts and ABI](/docs/category/contracts-and-abi.md)
- Tags: Evm Encoding, ABI, Events, Diagnostics

Returns a status-rich JSON description of one EVM log; use it when unknown, ambiguous, and malformed logs must remain distinguishable.

## Overload 1: log_decode_json(JSON, BYTES32\[\], BYTES)

```sql
log_decode_json(JSON, BYTES32[], BYTES)
```

Decodes topics and data using an event ABI supplied as JSON.

- Kind: scalar
- Execution context: Offline
- Behavior: Status Rich Log Diagnostic
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: JSON
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `abi` (JSON; required; positional) — Event ABI JSON containing the event definition.
- `topics` (BYTES32[]; required; positional) — Event topics as BYTES32 values. For non-anonymous events, the first list element is EVM topic0; anonymous events begin with the first indexed argument.
- `data` (BYTES; required; positional) — Raw event data bytes.

### Returns

Log diagnostic JSON

Fields by decode_status: decoded has signature, name, and args (signature currently contains the event name for compatibility; registry decoding may add abi_label); unknown has topic0, topics, data, and data_words; ambiguous has topic0; decode_error has topic0 or error.

- `diagnostic` (JSON)

Log diagnostic JSON. Fields by decode_status: decoded has signature, name, and args (signature currently contains the event name for compatibility; registry decoding may add abi_label); unknown has topic0, topics, data, and data_words; ambiguous has topic0; decode_error has topic0 or error.

### Examples

_Local SQL · Local_

```sql
SELECT log_decode_json(
  '[{"type":"event","name":"Transfer","inputs":[
    {"name":"sender","type":"address","indexed":true},
    {"name":"recipient","type":"address","indexed":true},
    {"name":"value","type":"uint256","indexed":false}
  ]}]'::JSON,
  [
    event_signature('Transfer(address,address,uint256)'),
    evm_abi_word('0xcb83ca9633ad057bd88a48a5b6e8108d97ad4472'::ADDRESS),
    evm_abi_word('0xa1db2fc9b2ceaf3cdf41fd11ffcb38404eae3906'::ADDRESS)
  ],
  evm_abi_word(615568393::UINT256)::BYTES
) AS diagnostic;
-- diagnostic.decode_status = decoded
```

## Overload 2: log_decode_json(VARCHAR, BYTES32\[\], BYTES)

```sql
log_decode_json(VARCHAR, BYTES32[], BYTES)
```

Decodes topics and data using an event ABI supplied as VARCHAR.

- Kind: scalar
- Execution context: Offline
- Behavior: Status Rich Log Diagnostic
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: JSON
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `abi` (VARCHAR; required; positional) — Event ABI JSON containing the event definition.
- `topics` (BYTES32[]; required; positional) — Event topics as BYTES32 values. For non-anonymous events, the first list element is EVM topic0; anonymous events begin with the first indexed argument.
- `data` (BYTES; required; positional) — Raw event data bytes.

### Returns

Log diagnostic JSON

Fields by decode_status: decoded has signature, name, and args (signature currently contains the event name for compatibility; registry decoding may add abi_label); unknown has topic0, topics, data, and data_words; ambiguous has topic0; decode_error has topic0 or error.

- `diagnostic` (JSON)

Log diagnostic JSON. Fields by decode_status: decoded has signature, name, and args (signature currently contains the event name for compatibility; registry decoding may add abi_label); unknown has topic0, topics, data, and data_words; ambiguous has topic0; decode_error has topic0 or error.

### Examples

_Local SQL · Local_

```sql
SELECT log_decode_json(
  '[{"type":"event","name":"Transfer","inputs":[
    {"name":"sender","type":"address","indexed":true},
    {"name":"recipient","type":"address","indexed":true},
    {"name":"value","type":"uint256","indexed":false}
  ]}]'::VARCHAR,
  [
    event_signature('Transfer(address,address,uint256)'),
    evm_abi_word('0xcb83ca9633ad057bd88a48a5b6e8108d97ad4472'::ADDRESS),
    evm_abi_word('0xa1db2fc9b2ceaf3cdf41fd11ffcb38404eae3906'::ADDRESS)
  ],
  evm_abi_word(615568393::UINT256)::BYTES
) AS diagnostic;
-- diagnostic.decode_status = decoded
```

## Guidance

### Decode event rows

Use log_decode_json after fetching logs when one JSON value must preserve whether decoding succeeded, found no matching ABI, found multiple candidates, or failed. Required NULL inputs propagate NULL.

- Use table-shaped log functions when you need to join decoded event fields across many rows.
- Use event_decode_json when NULL on malformed input is preferable to diagnostic statuses.
- The canonical sample reconstructs USDC transaction 0x5cbf...3dde, log index 97, at Ethereum block 20,000,000 without an RPC call.
- Non-anonymous logs begin with topic0; anonymous logs begin with their first indexed parameter.
- Indexed dynamic parameters remain BYTES32 hashes. Unnamed inputs use arg0, arg1, and so on.
- Keep topic and data bytes alongside decoded JSON for review and troubleshooting.

## Related functions

- [event_decode](/docs/functions/event_decode.md) — Alternative
- [event_decode_json](/docs/functions/event_decode_json.md) — Alternative
- [evm_decode_log_for](/docs/functions/evm_decode_log_for.md) — Alternative
- [get_logs](/docs/functions/get_logs.md) — Usually After