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
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
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
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
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
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
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
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
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
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
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
- Transaction Signer for transaction submission
- Chain Gateway for RPC connectivity
- Chain Indexer for event processing
- SMART Protocol integration (ERC-3643) for contract architecture
Transaction Signer
The Transaction Signer service handles secure preparation, signing, and broadcasting of blockchain transactions with intelligent gas management, nonce coordination, and support for both direct key signing and account abstraction patterns.
Chain Indexer
The Chain Indexer transforms blockchain-optimized event logs and storage into domain model data structures optimized for application queries, providing millisecond-latency access to historical blockchain state.