Integrating EVM Networks With Chainlink Services
Before an EVM blockchain network can integrate with Chainlink, it must meet certain technical requirements. These requirements are critical for Chainlink nodes and Chainlink services to function correctly on a given network.
Standard EVM requirements
Solidity global variables and opcode implementation
Solidity global variables and opcode implementation constructs must meet the following requirements in order for Chainlink services to operate correctly and as expected:
- Global variables: Support all global variables as specified in the Solidity Block and Transaction Properties documentation. For example, the following variables must be supported:
block.blockhash
must return the hash of the requested block for the last 256 blocksblock.number
must return the respective chain's block numberblock.chainID
must return the current chain IDblock.timestamp
must return the current block timestamp as seconds since unix epoch
- Opcodes: Support all opcodes and expected behaviors from the OpCodes.sol contract
- Precompiles: Must support all precompile contracts and expected behaviors listed in the Solidity Mathematical and Cryptographic Functions documentation
- Contract size: Must support the maximum contract size defined in EIP-170
- Nonce: The transaction nonce must increase as transactions are confirmed and propagated to all nodes in the network.
Finality
Blockchain development teams must ensure that blocks with a commitment level of finalized are actually final. The properties of the finality mechanism, including underlying assumptions and conditions under which finality violations could occur, must be clearly documented and communicated to application developers in the blockchain ecosystem.
Furthermore, this information should be accessible through RPC API tags finalized from the JSON-RPC specification tags described later in this document.
Standardized RPCs with SLAs
Chainlink nodes use RPCs to communicate with the chain and perform soak testing. It is not possible to ensure the functionality of Chainlink services if RPCs are unstable, underperforming, or nonexistent. RPCs must meet the following requirements:
Dedicated RPC node:
- The chain must provide instructions and hardware requirements to set up and run a full node.
- The archive node setup must also be provided and allow queries of blocks from genesis with transaction history and logs.
- The RPC node must enable and allow configurable settings for the following items:
- Batch calls
- Log lookbacks
- HTTPS and WSS connections
RPC providers:
- Three separate independent RPC providers must be available.
- RPC providers must ensure there is no rate limit.
- RPC providers must have a valid SSL certificate.
- During the trailing 30 days, the RPC providers must meet the following RPC performance requirements:
- Uptime: At least 99.9%
- Throughput: Support at least 300 calls per second
- Latency: Less than 250ms
- Support SLA: For SEV1 issues, provide a Time to Answer (TTA) of at most 1 hour
Support the Ethereum JSON-RPC Specification
The chain must support the Ethereum JSON-RPC Specification. Chainlink services use several methods to operate on the chain and require a specific response format to those calls in line with the JSON RPC standard of Ethereum. If a response does not match this required format, the call fails and the Chainlink node will stop functioning properly.
The following methods are specifically required and must follow the Ethereum RPC API specification:
- GetCode
- Call
- ChainID
- SendTransaction
- SendRawTransaction
- GetTransactionReceipt
- GetTransactionByHash
- EstimateGas
- GasPrice
- Must accept the
blockhash
param as defined in EIP-234
- Must accept the
- GetTransactionCount
- GetLogs
- Must follow the spec as defined in EIP-1474. The "latest" block number returned by
GetBlockByNumber
must also be served byGetLogs
with logs.
- Must follow the spec as defined in EIP-1474. The "latest" block number returned by
- GetBalance
- GetBlockByNumber
- GetBlockByHash
The above RPC methods must have the expected request and response params with expected data types and values as described in the Execution-api spec and Ethereum RPC API Spec.
The network must also support the following items:
- Subscription Methods: Websocket JSON-RPC subscription methods
eth_subscribe
with support for subscription tonewHeads
andlogs
- Tags: The RPC methods must support the
finalized
,latest
, andpending
tags where applicable. They must also support natural numbers for blocks. - Batch Requests: Must support batching of requests for the
GetLogs
andGetBlockByNumber
methods. - Response size: Any RPC request including the batch requests must be within the allowed size limit of around 173MB.
eth_sendRawTransaction
error message mapping to Geth client error messages
Chains must provide an error message mapping between their specific implementation to the error messages detailed below.
When the eth_sendRawTransaction
call fails, Chainlink nodes must be able to recognize these error categories and determine the next appropriate action. If the error categories are different or cannot be mapped correctly, the Chainlink node will stop functioning properly and stop sending transactions to the chain. The following error messages are specifically critical:
Error | Description |
---|---|
NonceTooLow | Returned when the nonce used for the transaction is too low to use. This nonce likely has been already used on the chain previously. |
NonceTooHigh | Returned when the nonce used for the transaction is higher than what the chain can use right now. |
ReplacementTransactionUnderpriced | Returned when the transaction gas price used is too low. There is another transaction with the same nonce in the queue, with a higher price. |
LimitReached | Returned when there are too many outstanding transactions on the node. |
TransactionAlreadyInMempool | Returned when this current transaction was already received and stored. |
TerminallyUnderpriced | Returned when the transaction's gas price is too low and won't be accepted by the node. |
InsufficientEth | Returned when the account doesn't have enough funds to send this transaction. |
TxFeeExceedsCap | Returned when the transaction gas fees exceed the configured cap by this node, and won't be accepted. |
L2FeeTooLow | Specific for Ethereum L2s only. Returned when the gas fees are too low, When this error occurs the Suggested Gas Price is fetched again transaction is retried. |
L2FeeTooHigh | Specific for Ethereum L2s only. Returned when the total fee is too high. When this error occurs the Suggested Gas Price is fetched again transaction is retried. |
L2Full | Specific for Ethereum L2s only. The node is too full, and cannot handle more transactions. |
TransactionAlreadyMined | Returned when the current transaction was already accepted and mined into a block. |
Fatal | Return when something is seriously wrong with the transaction, and the transaction will never be accepted in the current format. |
For examples of how other chains or clients are using these categories, see the error.go file in the go-ethereum repo on GitHub.
For chains with zk-proofs, chains must reject transactions that cause zk-proof overflow with a uniquely identifiable error message.
Any other reasons why transactions might be rejected by a node or sequencer other than malformed input/gasLimits must be detailed.
Clarify use of transaction types
For transaction types other than 0x0 - Legacy
, 0x1 - Access List
, 0x2 - Dynamic
, and 0x3 - Blob
, networks must clarify how each transaction type is used. Chainlink nodes must know if the chain uses other types for regular transactions with regular gas so it can correctly estimate gas costs.
Multi-signature wallet support
The chain must provide a supported and audited multi-signature wallet implementation with a UI.
Block explorer support
The chain must provide a block explorer and support for contract and verification APIs.