# evm_register_contract_abi

Stores contract ABI metadata in the current database for block-aware log and revert decoding.

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

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

Stores contract ABI metadata in the current database for block-aware log and revert decoding.

## Overload 1: evm_register_contract_abi(UBIGINT, ADDRESS, JSON)

```sql
evm_register_contract_abi(UBIGINT, ADDRESS, JSON)
```

Registers one local ABI and optional inclusive validity range.

- Kind: scalar
- Execution context: Offline
- Behavior: Register Contract Abi
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Local Catalog State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: catalog_write

### Inputs

- `chain_id` (UBIGINT; required; positional) — Chain id.
- `address` (ADDRESS; required; positional) — Contract address.
- `abi` (JSON; required; positional) — Contract ABI JSON.

### Returns

Registration status

Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

- `registered` (BOOLEAN)

Registration status. Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

### Examples

_Local SQL · Local_

```sql
SELECT evm_register_contract_abi(
  1,
  '0x0000000000000000000000000000000000000500'::ADDRESS,
  '[{"type":"event","name":"Transfer","inputs":[{"name":"sender","type":"address","indexed":true},{"name":"recipient","type":"address","indexed":true},{"name":"value","type":"uint256","indexed":false}]}]'::JSON
) AS registered;
-- true
```

## Overload 2: evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR)

```sql
evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR)
```

Registers one local ABI and optional inclusive validity range.

- Kind: scalar
- Execution context: Offline
- Behavior: Register Contract Abi
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Local Catalog State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: catalog_write

### Inputs

- `chain_id` (UBIGINT; required; positional) — Chain id.
- `address` (ADDRESS; required; positional) — Contract address.
- `abi` (JSON; required; positional) — Contract ABI JSON.
- `label` (VARCHAR; required; positional) — Optional ABI label.

### Returns

Registration status

Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

- `registered` (BOOLEAN)

Registration status. Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

### Examples

_Local SQL · Local_

```sql
SELECT evm_register_contract_abi(
  1,
  '0x0000000000000000000000000000000000000501'::ADDRESS,
  '[{"type":"event","name":"Transfer","inputs":[{"name":"sender","type":"address","indexed":true},{"name":"recipient","type":"address","indexed":true},{"name":"value","type":"uint256","indexed":false}]}]'::JSON,
  'USDC Transfer'
) AS registered;
-- true
```

## Overload 3: evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR, UBIGINT)

```sql
evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR, UBIGINT)
```

Registers one local ABI and optional inclusive validity range.

- Kind: scalar
- Execution context: Offline
- Behavior: Register Contract Abi
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Local Catalog State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: catalog_write

### Inputs

- `chain_id` (UBIGINT; required; positional) — Chain id.
- `address` (ADDRESS; required; positional) — Contract address.
- `abi` (JSON; required; positional) — Contract ABI JSON.
- `label` (VARCHAR; required; positional) — Optional ABI label.
- `from_block` (UBIGINT; required; positional) — First valid block (inclusive).

### Returns

Registration status

Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

- `registered` (BOOLEAN)

Registration status. Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

### Examples

_Local SQL · Local_

```sql
SELECT evm_register_contract_abi(
  1,
  '0x0000000000000000000000000000000000000502'::ADDRESS,
  '[{"type":"event","name":"Transfer","inputs":[{"name":"sender","type":"address","indexed":true},{"name":"recipient","type":"address","indexed":true},{"name":"value","type":"uint256","indexed":false}]}]'::JSON,
  'USDC Transfer',
  20000000
) AS registered;
-- true
```

## Overload 4: evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR, UBIGINT, UBIGINT)

```sql
evm_register_contract_abi(UBIGINT, ADDRESS, JSON, VARCHAR, UBIGINT, UBIGINT)
```

Registers one local ABI and optional inclusive validity range.

- Kind: scalar
- Execution context: Offline
- Behavior: Register Contract Abi
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Local Catalog State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: catalog_write

### Inputs

- `chain_id` (UBIGINT; required; positional) — Chain id.
- `address` (ADDRESS; required; positional) — Contract address.
- `abi` (JSON; required; positional) — Contract ABI JSON.
- `label` (VARCHAR; required; positional) — Optional ABI label.
- `from_block` (UBIGINT; required; positional) — First valid block (inclusive).
- `to_block` (UBIGINT; required; positional) — Final valid block (inclusive).

### Returns

Registration status

Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

- `registered` (BOOLEAN)

Registration status. Returns true when canonicalized ABI metadata is inserted or when the exact registration is replayed. A successful call never returns false.

### Examples

_Local SQL · Local_

```sql
SELECT evm_register_contract_abi(
  1,
  '0x0000000000000000000000000000000000000503'::ADDRESS,
  '[{"type":"event","name":"Transfer","inputs":[{"name":"sender","type":"address","indexed":true},{"name":"recipient","type":"address","indexed":true},{"name":"value","type":"uint256","indexed":false}]}]'::JSON,
  'USDC Transfer',
  20000000,
  20000000
) AS registered;
-- true
```

## Guidance

### Register contextual ABI metadata

Registrations are stored only in the current database and are read by evm_decode_log_for and evm_decode_revert_for.

from_block and to_block are inclusive. A missing endpoint is unbounded.

ABI JSON is canonicalized before identity hashing. Replaying the exact chain, address, range, label, and canonical ABI is idempotent; any other overlapping inclusive range is rejected.

- Use separate non-overlapping ranges for proxy upgrades. Adjacent ranges must end at N and begin at N + 1.
- Mutation is isolated to the database where this function is called.

## Related functions

- [evm_decode_log_for](/docs/functions/evm_decode_log_for.md) — Usually Before
- [evm_decode_revert_for](/docs/functions/evm_decode_revert_for.md) — Usually Before