ERC-7876 Unified network configuration for DApps (Ethereum Network Configuration for DApps)

Draft · Other · created 2025-01-03

A configuration standard that lets DApps manage an Ethereum-compatible network's RPC, native currency, contract addresses, and block explorer information in a single, unified JSON format.

Why it is needed

DApps support many Ethereum-compatible networks, but they often define network configuration in different formats of their own. This makes interoperability and configuration sharing between networks difficult. Without a standard, a network operator trying to get its chain consistently supported across multiple DApps, a smart contract developer trying to communicate address or ABI changes to multiple platforms, or an organization trying to unify configuration across multiple platforms such as iOS and Android internally all have to design a new format each time. Furthermore, without standard fields to express features unique to each chain, networks must keep separate custom configuration in external storage, making unified management even harder.

In depth

Top-level Configuration structure

The top-level Configuration object consists of version (a semver-formatted version), timestamp (an ISO 8601 formatted update time), summary (a short summary of the configuration), description (a detailed description), abiRoot (the root URL when the ABI is hosted externally, or null if none), and networks (a NetworkConfig record keyed by chain ID). The entire configuration MUST be a JSON object, and 2-space indentation is RECOMMENDED.

NetworkConfig fields

Each network is represented by a NetworkConfig. It includes name (the network name), testnet (a boolean indicating whether it is a testnet), nativeCurrency (native currency information consisting of name, symbol, decimals), relations (relationships with other networks), rpcs (an RpcConfig record keyed by node name), explorers (block explorer records), and contracts (a ContractConfig record keyed by contract name, with values null if not deployed). The unique identifier for a network is the chain ID key, not the network name.

ContractConfig and contract rules

ContractConfig consists of address (a checksummed address, MUST), abiUrl (the path to the ABI JSON file, which may be relative to abiRoot or absolute; if absent or null the ABI is unknown), and blockCreated (the block number at which it was deployed). Contracts listed in the configuration SHOULD be limited to the necessary scope, and the same contract name MUST be consistent across all networks. Bytecode may differ between networks but SHOULD represent different versions of the same contract, with differences conveyed via custom properties or a different abiUrl. Inlining the ABI directly in the configuration MUST NOT be done, and networks where a contract is not deployed MUST explicitly set the value to null. Where bytecode has been verified on a block explorer, it is RECOMMENDED that the contract name match the name in the Solidity source code.

ExplorerConfig and RpcConfig

ExplorerConfig consists of root (the explorer's root URL), block, address, tx, and nft (relative paths from root for each, or null if the feature is unavailable). Relative paths MUST include placeholders such as :block, :address, :tx, :token, which are substituted with actual values to build links. RpcConfig is a simple structure containing only a url, and multiple nodes can be registered under different keys (e.g. main, backup) in the rpcs record.

Extensions rules

Implementations MUST either ignore undocumented properties or support interpreting them where possible. This allows the configuration to be extended without breaking compatibility. New properties SHOULD be used to support new features but MUST NOT change or extend the base type of existing properties. Union types SHOULD NOT be used in extensions; changing blockCreated from a number to a hex string is given as an example of an improper extension. Extensions SHOULD use a flexible structure that allows properties to be added at any configuration layer (e.g. documentation: { url: string }[] instead of documentationUrls: string[]).

Use of chain ID and EIP-3085 compatibility

This standard uses the chain ID, rather than an arbitrary name, as the unique identifier for a network, because the chain ID is included in the Ethereum specification, is globally recognized, and is collision-free, improving interoperability with existing tooling. This standard is also designed to be as compatible as possible with EIP-3085, which covers wallet Add Ethereum Chain requests, but where EIP-3085's rigid structure would limit future extensibility, it is designed differently, prioritizing extensibility instead.

Current status of the standard

This standard is currently in Draft status and specifies EIP-55 (checksummed addresses) as a requirement. Because it is in Draft status, detailed fields or rules may change going forward, or discussion may be discontinued.

Things to watch out for

Original ERC · ← ERCs