This standard defines a universal format for specifying network configurations to decentralized applications (DApps). The configuration includes essential information about Ethereum networks, such as available RPC URLs, native currencies, contract addresses, and block explorers. Configurations are intended to be provided by:
Given that different EVM-compatible chains introduce unique features, this standard also supports extensibility, allowing networks to specify additional configuration parameters beyond the base requirements. This flexibility prevents networks from resorting to external storage for their unique configurations, preserving the goal of a unified and comprehensive network configuration standard.
Currently, decentralized applications (DApps) support numerous EVM-compatible networks and often define network configurations in inconsistent formats, which complicates interoperability and sharing of configurations. This standard introduces a unified network configuration format that can be adopted by EVM-based networks, making it easier for developers to integrate with multiple networks and providing consistent configuration management.
The proposed configuration format includes essential details required by DApps, including:
The goal of this standard is to simplify network configuration for DApp developers and enhance interoperability across Ethereum-compatible networks.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
The configuration MUST use a JSON object, which DApp developers can use to define multiple Ethereum networks.
The specification interface is provided in the TypeScript type definition format, which is widely used to define JSON file formats for Ethereum DApps. Refer to Example Configuration for an illustrative implementation of this standard.
Contracts listed SHOULD be limited to the subset necessary to perform specific functionality, as defined by the configuration author.
Implementations MUST ensure that contract names are consistent across all networks. While the contract binary code deployed to different networks under the same name in the configuration can differ, implementations SHOULD ensure they represent different versions of the same contract. Differences SHOULD be communicated through additional custom properties or different abiUrl. See Extensions.
Inlining contract ABIs MUST NOT be used to ensure effective memory management is possible in resource-constrained environments.
It is RECOMMENDED for a contract name to match the name in Solidity source code if the contract bytecode is verified on block explorers.
If a contract is not deployed on a specific network, the value null MUST explicitly indicate the absence of a contract.
Implementations MUST ignore non-documented properties or support their interpretation where technically feasible. This ensures the standard remains adaptable to future use cases, enabling developers to extend configurations without breaking compatibility. See Example Extensions.
Non-documented properties SHOULD support new features or extensions, but they MUST NOT modify or extend the basic types of existing properties. Union types SHOULD NOT be used in extensions. Their usage contradicts the Rationale of the standard. See Incorrect Extension Example.
Extensions SHOULD use extensible data structures by making sure additional properties can be added at any configuration layer.
Example of rigid and extensible data structures:
The design of this standard leverages the following key goals:
Use JSON as a universally supported data interchange format, with libraries available in virtually all modern programming languages and platforms. This ensures:
The human-readable structure makes it ideal for configuration files:
name and description provide context and improve usability for engineers working with the configuration.This standard is designed to support extensions by using JSON objects rather than rigid structures like basic types or arrays.
See Extensions.
This standard uses the chain ID as the unique identifier for networks rather than custom names because:
This standard emphasizes extensibility while maintaining backward compatibility where feasible. It ensures adaptability to the evolving requirements of Ethereum network configurations by prioritizing flexibility in its structure.
This standard aligns with EIP-3085, the Ethereum standard for wallet Add Ethereum Chain requests, wherever applicable. However, it diverges in scenarios where EIP-3085's rigid structure limits future enhancements.
By prioritizing extensibility over strict adherence to EIP-3085, this standard ensures compatibility with existing tools while enabling future-proof enhancements to network configurations.
Below is an example configuration for an ERC-721 project deployed to Ethereum Mainnet and Sepolia. This illustrates how the standard can represent multi-network setups.
Note: It is RECOMMENDED to use a two-space indentation format for better readability and debugging.
Here is an example implementation of a configuration loader in Swift Programming Language, demonstrating how to load and parse a configuration file compliant with this standard:
This Swift code provides a structured way to handle the configuration JSON and includes utility methods for accessing contract-related information.
Example of an extension that MUST be supported: adding an API token alongside the RPC URL when it cannot be embedded directly into the URL
(e.g., passed via an Authorization: Bearer <token> header).
Ensure Security Considerations are followed to protect your API key.
Example of an extension that MUST be supported: incorporating additional attributes to support ERC-1967 transparent proxies and ERC-165 interface identification.
Example of an incorrect extension that MUST NOT be supported: representing blockCreated as a hexadecimal string instead of an integer.
It causes existing implementation to fail parsing blockCreated property expecting it to be a number, not a string.
The network configuration defined by this standard is intended to include only public information that is already accessible through tools like block explorers. By structuring this information in a standardized format, the configuration becomes more convenient and efficient for developers to use while maintaining the integrity of public data.
To ensure security and privacy, the following considerations MUST be adhered to:
Exposing API keys must be handled with caution and accompanied by a thorough evaluation of associated risks. When including API keys, the following restrictions and best practices SHOULD be implemented:
Scope Restrictions:
Rate Limits:
Usage:
The configuration MUST NOT include the following sensitive data:
The overall security risks of using this standard are minimal due to its compatibility with established Ethereum ecosystem security practices, including:
By aligning with proven methodologies and widely accepted protocols, the standard minimizes potential vulnerabilities while ensuring robust functionality.
Copyright and related rights waived via CC0.