OCP-0003: Chain Registry Interoperability

Abstract

This OCP defines how OpenCrown implementations consume chain metadata from external registries (e.g., the ENS 'on.eth' Chain Registry, ERC-7828). It specifies standard-conformant chain identification, a registry-agnostic data architecture using CAIP-2 as the canonical key, and separation of chain-level metadata from crown-level IPFS metadata.

Motivation

On-Chain Chain Registries

Chain-name-to-identifier mappings have been maintained off-chain via centralized lists. This does not scale with L2 proliferation and does not cover non-EVM chains.

The ENS 'on.eth' Chain Registry (EP 6.34, ERC-7828) addresses this for the EVM ecosystem:

A curated, on-chain registry under a 3-of-5 multisig (transferring to ENS DAO governance)
Canonical labels like 'ethereum', 'arbitrum', 'base', 'solana', 'optimism' with alias support
ERC-7828 readable interoperable addresses (e.g., 'alice.eth@base')
ENSIP-10 wildcard resolution, ENSIP-24 arbitrary data, ERC-7930 interoperable addresses
Discovery via 'chainCount()' / 'getChainAtIndex()'

Multi-Chain Considerations

No single chain registry has universal adoption:

Non-EVM chains may develop their own naming infrastructure. Solana, Cosmos, and future ecosystems are not guaranteed to adopt ENS-based naming.
Adoption is gradual. Even within the EVM ecosystem, 'on.eth' is a proposal. Standards take time to be adopted by wallets, DEXes, and other infrastructure.
Governance independence. Depending on an external DAO's naming decisions for core protocol functionality creates an uncontrolled dependency.

The protocol MUST work on chains that have canonical registries, chains that have competing registries, and chains that have none.

Chain Data vs. Crown Data

Chain registries store chain-level metadata (chain name, chain ID, RPC URLs). Crown IPFS metadata stores token-level data (logo, description, socials). These layers have different ownership models and MUST remain separated. See Spec 3.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Spec 1: Conform to External Standards

OpenCrown implementations SHOULD conform to the chain identification conventions used by established external registries so that adopting those registries as data sources requires minimal changes.

Specifically:

Use the same chain labels. When an on-chain registry (such as 'on.eth') assigns a canonical label to a chain, OpenCrown implementations SHOULD use that same label as their internal identifier for that chain.
Support the same alias patterns. If a registry defines aliases (e.g., 'arb' for 'arbitrum', 'op' for 'optimism'), OpenCrown implementations SHOULD accept those same aliases as input.
Use CAIP-2 as the universal key. Regardless of which registry provides the human-readable label, CAIP-2 identifiers ('eip155:42161', 'solana:mainnet') remain the unambiguous, registry-independent chain identifier. All OpenCrown data structures MUST include CAIP-2 identifiers alongside any human-readable labels.

Spec 2: Registry-Agnostic Architecture

OpenCrown implementations MUST support multiple chain data sources. No single source is inherently primary.

''' ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ on.eth │ │ Local │ │ Future │ │ (EVM) │ │ Config │ │ Registries │ │ │ │ (all chains)│ │ (Solana,etc) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ └────────┬────────┘─────────────────┘ │ merged by operator ▼ ┌─────────────────────────────────────────────┐ │ Unified Chain Configuration │ │ CAIP-2 as the canonical key across sources │ └──────────────────┬──────────────────────────┘ │ consumed by ▼ ┌─────────────────────────────────────────────┐ │ Operator Layer │ │ APIs, frontends, SDKs, indexers │ └─────────────────────────────────────────────┘ '''

Data Source Requirements

Every OpenCrown implementation MUST maintain a local chain configuration that is loadable without any external network calls. This ensures the protocol functions on any chain regardless of whether an external registry exists for that chain. An operator serving crowns on one chain SHOULD NOT need RPC access to a different chain.

Operators MAY additionally consume data from one or more external chain registries (e.g., pulling chain metadata from '*.on.eth' for EVM chains). When consuming external sources:

Treat all sources as peers. No source is inherently authoritative over another.
Cache aggressively. Chain metadata changes infrequently. Implementations SHOULD cache with a TTL of at least 1 hour.
Degrade gracefully. If any single source is unreachable, the operator MUST continue functioning using other available sources. No core protocol operation SHALL depend on any specific external source.
Validate across sources. When the same chain appears in multiple sources, implementations SHOULD cross-check for consistency. Operators SHOULD alert on discrepancies (e.g., if a registry suddenly maps a label to a different chain ID).
CAIP-2 is the merge key. When combining data from multiple sources, CAIP-2 identifiers are the canonical join key. Human-readable labels may differ across sources — CAIP-2 does not.

Coordinator Manifest

The 'OpenCrownCoordinator' contract's manifest (IPFS-hosted JSON linked via '_manifestCID') MAY include an optional 'registryRef' field per chain, pointing consumers to external registries where authoritative chain metadata can be found:

'''json { "chains": { "arbitrum": { "caip2": "eip155:42161", "contracts": { "registry": "0x...", "deals": "0x..." }, "registryRef": { "ens": "arbitrum.on.eth" } }, "solana": { "caip2": "solana:mainnet", "contracts": { "registry": "...", "deals": "..." }, "registryRef": null } } } '''

The 'registryRef' field is informational — it helps consumers discover where to find additional chain metadata. A 'null' value means no known external registry entry exists for this chain yet.

Spec 3: Crown Metadata Independence

Crown-level metadata remains on IPFS, independent of any chain registry:

Data Layer	Storage	Controlled By	Examples
Chain metadata	Local config + optional external registries	Chain operators / registry governance	Chain name, chain ID, RPC URLs, explorer
Protocol metadata	On-chain (Coordinator manifest via IPFS)	OpenCrown DAO governance	Contract addresses, supported chains
Crown metadata	IPFS (via 'metadataUri' / 'highlightsUri')	Crown holder or delegated manager	Logo, description, socials, links, tags

Crown metadata MUST NOT duplicate chain-level data (RPC URLs, explorer links, chain IDs) that belongs to the chain data layer. Crown holders MUST NOT store chain-level metadata in crown IPFS documents.

Rationale

Why Conform Rather Than Invent

OpenCrown previously maintained custom chain shorthand ('arb', 'sol', 'bsc'). These identifiers served an internal purpose but created maintenance burden and diverged from ecosystem conventions. Conforming to the labels used by chains themselves and by emerging registries eliminates this friction and ensures that when a registry like 'on.eth' is production-ready, OpenCrown can adopt it with a configuration change rather than a migration.

This does not mean OpenCrown is locked to any particular registry's decisions. CAIP-2 remains the canonical, registry-independent identifier. Human-readable labels are a convenience layer that should match whatever the ecosystem uses — today that means matching the labels chains use in their own branding, which happen to align with 'on.eth''s canonical labels.

Why "A Source of Truth" Not "The Source of Truth"

The multi-chain ecosystem does not have — and may never have — a single universal chain registry. ENS is Ethereum-native. Solana has SNS. Cosmos has IBC chain IDs. Spec 2's peer model follows from this observation. If a universal registry emerges, Spec 1's conformance requirement makes adoption straightforward. If none does, Spec 2 ensures the protocol still functions.

Registry-level risks (governance changes, deprecation, loss of neutrality) do not cascade into protocol failures under this model.

Why Crown Metadata Stays on IPFS

Crown metadata is rich (JSON + media, often several KB — unsuitable for on-chain storage or ENS text records) and follows the industry standard for NFT metadata (IPFS URIs). The chain/crown separation defined in Spec 3 preserves owner control and cross-chain CID sharing.

Backwards Compatibility

This OCP introduces no backwards incompatibilities at the protocol level. No smart contract modifications are required. Crown NFTs, the OpenCrownRegistry, OpenCrownCoordinator, and deal contracts are unaffected.

The Coordinator manifest schema gains an optional 'registryRef' field. This is additive — existing manifests without this field remain valid.

Security Considerations

External Registry Trust

Consuming data from external chain registries introduces a trust surface. Mitigations:

No protocol-critical operations SHALL depend on any single external source. Core operations function with whichever chain data sources are available.
Validation against known values. Operators SHOULD cross-check externally-sourced chain data against their local configuration and alert on discrepancies.
Cache with TTL. Local caching reduces exposure to registry downtime or transient manipulation.

Registry Governance Risk

An external registry's governance could make decisions that conflict with OpenCrown's chain support (e.g., de-listing a chain, reassigning a label). Because no single registry gates protocol operations (Spec 2), such decisions do not impact the protocol.

Chain Name Confusion

If multiple registries assign different labels to the same chain, operators MUST resolve the conflict. CAIP-2 identifiers serve as the disambiguation layer — human-readable labels are convenience, CAIP-2 is truth. Implementations MUST match on CAIP-2, not on label strings, for any protocol-critical operation.