# Contract Runtime

Source: https://docs.settlemint.com/docs/architecture/components/infrastructure/contract-runtime
The Contract Runtime provides a secure abstraction for smart contract
interactions, managing ABI encoding, call execution, and state queries
with automatic retry and error classification.




## Overview [#overview]

The Contract Runtime translates high-level operations into smart contract calls. This component handles ABI encoding, call construction, and result decoding while abstracting blockchain interaction complexity.

Smart contracts present binary interfaces that require precise encoding. Method selectors, parameter encoding, and result parsing demand careful implementation. The Contract Runtime centralizes this complexity, providing typed interfaces for application code.

## Interaction patterns [#interaction-patterns]

<Mermaid
  chart="`flowchart TB
  subgraph APP[&#x22;Application layer&#x22;]
    OP(Asset Operation)
  end

  subgraph CR[&#x22;Contract Runtime&#x22;]
    ABI(ABI Registry)
    ENC(Encoder)
    DEC(Decoder)
  end

  subgraph TX[&#x22;Transaction Management&#x22;]
    TS(Transaction Signer)
  end

  subgraph BC[&#x22;Blockchain&#x22;]
    SC(Smart Contract)
  end

  OP --> ABI
  ABI --> ENC
  ENC --> TS
  TS --> SC
  SC --> DEC
  DEC --> OP

  style OP fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style ABI fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style ENC fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style DEC fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style TS fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style SC fill:#b661d9,stroke:#8a3fb3,stroke-width:2px,color:#fff`"
/>

## ABI management [#abi-management]

The Contract Runtime maintains an ABI registry for all deployed contracts. Contract deployment automatically registers ABIs. Version management tracks ABI changes across contract upgrades.

| ABI source         | Registration timing | Update mechanism     |
| ------------------ | ------------------- | -------------------- |
| Platform contracts | Build time          | Deployment pipeline  |
| User contracts     | Deployment time     | Automatic extraction |
| External contracts | Configuration time  | Manual registration  |

## Operation types [#operation-types]

### Read operations [#read-operations]

View and pure functions execute without transaction submission. Read calls route to Chain Gateway replica nodes for performance. Results decode through ABI definitions with type validation.

### Write operations [#write-operations]

State-modifying functions require transaction submission through the Transaction Signer. The runtime constructs complete transaction objects including:

* Target contract address
* Encoded function call data
* Gas limit estimation
* Value transfer (if applicable)

### Multicall batching [#multicall-batching]

Multiple read operations batch into single RPC calls when targeting compatible contracts. Batching reduces network round trips and improves response latency for complex queries.

## Error classification [#error-classification]

Contract calls can fail in multiple ways. The runtime classifies errors to enable appropriate handling:

| Error type         | Cause                           | Handling                    |
| ------------------ | ------------------------------- | --------------------------- |
| Revert             | Contract logic rejection        | Surface to workflow         |
| Out of gas         | Insufficient gas limit          | Retry with higher limit     |
| Nonce collision    | Concurrent transaction conflict | Resubmit with correct nonce |
| Contract not found | Invalid address                 | Configuration error         |
| Invalid parameters | ABI encoding mismatch           | Developer error             |

## Gas optimization [#gas-optimization]

The Contract Runtime implements gas optimization strategies:

**Efficient encoding**: Parameter encoding uses gas-optimal patterns where alternatives exist.

**Calldata compression**: Large parameters compress when contract supports decompression.

**Access list generation**: EIP-2930 access lists pre-warm storage for gas reduction.

**Simulation validation**: Complex transactions simulate before submission to catch failures before gas expenditure.

## Event decoding [#event-decoding]

Contract events decode through registered ABIs. The Chain Indexer uses Contract Runtime decoding for event processing. Event parameters extract with full type information for domain model construction.

## Upgrade handling [#upgrade-handling]

Contract upgrades require ABI registry updates. The runtime supports:

**Proxy patterns**: Transparent and UUPS proxies route through consistent addresses while ABIs update.

**Version tracking**: Multiple ABI versions coexist for historical data decoding.

**Migration support**: Upgrade workflows coordinate ABI updates with contract deployment.

## Security considerations [#security-considerations]

The Contract Runtime enforces security boundaries:

* Only approved contract addresses accept calls
* Parameter validation prevents injection attacks
* Value transfers require explicit authorization
* Administrative functions restrict to authorized roles

## See also [#see-also]

* [Transaction Signer](/docs/architecture/components/infrastructure/transaction-signer) for transaction submission
* [Chain Gateway](/docs/architecture/components/infrastructure/chain-gateway) for RPC connectivity
* [Chain Indexer](/docs/architecture/data-availability/chain-indexer) for event processing
* [SMART Protocol integration (ERC-3643)](/docs/architecture/components/asset-contracts/smart-protocol-integration) for contract architecture