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 blocks
  • block.number must return the respective chain's block number
  • block.chainID must return the current chain ID
  • block.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
• GetTransactionCount
• GetLogs
  • Must follow the spec as defined in EIP-1474. The "latest" block number returned by GetBlockByNumber must also be served by GetLogs with logs.
  • Must accept the blockhash param as defined in EIP-234
• 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 to newHeads and logs
• Tags: The RPC methods must support the finalized, latest, and pending tags where applicable. They must also support natural numbers for blocks.
• Batch Requests: Must support batching of requests for the GetLogs and GetBlockByNumber 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:

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.