ChainRegistry

Title: ChainRegistry

Author: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80)

Chain-registry facet: a generic registry of chain identities keyed by the ERC-7930 chain key, per-chain native bridge-ecosystem ids, gateway coverage awareness (direct vs hub-routed), and addEvmChain — the one-action admin fan-out that adds an EVM chain across every enabled gateway adapter in a single structured call.

Stateless delegator — logic/storage live in ChainRegistryLib. FAN-OUT COUPLING: this facet compiles in the admin write paths of all ten adapter libs (CCIP, LayerZero, Wormhole, Axelar, ZetaChain, OP L2-to-L2, CCTP, Hyperlane, Stargate, Hyperbridge) as INTERNAL calls only. A diamond that cuts ChainRegistry without some adapter facet still works — the libs write to ERC-7201 slots that simply go unread until that facet is cut; leaving a section for an un-hosted adapter disabled is the admin's responsibility (see IChainRegistry.AddEvmChainConfig).

Note:

lattice-version: 0.1.0

Functions

chainKeyEvm

The chain key of an EVM chain: eip-155 chainType (0x0000) + the canonical minimal big-endian chain reference (exactly the InteroperableAddress.formatEvmV1 encoding — no leading zeros).

function chainKeyEvm(uint256 chainId) external pure virtual returns (bytes32);

Parameters

Name	Type	Description
chainId	`uint256`

Returns

Name	Type	Description
<none>	`bytes32`

chainKeyOf

The chain key of any ERC-7930 chain identity: keccak256(abi.encodePacked(chainType, chainReference)).

function chainKeyOf(bytes2 chainType, bytes calldata chainReference) external pure virtual returns (bytes32);

Parameters

Name	Type	Description
chainType	`bytes2`
chainReference	`bytes`

Returns

Name	Type	Description
<none>	`bytes32`

isRegistered

Whether chainKey is a registered chain identity.

function isRegistered(bytes32 chainKey) external view virtual returns (bool);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
<none>	`bool`

chainInfoOf

The registered ERC-7930 identity of chainKey (evmChainId is 0 for non-EVM chains).

function chainInfoOf(bytes32 chainKey)
        external
        view
        virtual
        returns (bytes2 chainType, bytes memory chainReference, uint256 evmChainId);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
chainType	`bytes2`
chainReference	`bytes`
evmChainId	`uint256`

nativeIdsOf

The informational native bridge-ecosystem ids of chainKey.

function nativeIdsOf(bytes32 chainKey) external view virtual returns (NativeIds memory);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
<none>	`NativeIds`

gatewaysOf

The gateway adapters recorded as covering chainKey (direct AND hub-routed).

function gatewaysOf(bytes32 chainKey) external view virtual returns (address[] memory);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
<none>	`address[]`

coverageOf

The total number of gateways covering chainKey (direct + hub-routed).

function coverageOf(bytes32 chainKey) external view virtual returns (uint256);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
<none>	`uint256`

directCoverageOf

The number of gateways covering chainKey DIRECTLY (hub-routed coverage never counts).

O(n) over the coverage set — admin-bounded small (one entry per local gateway adapter).

function directCoverageOf(bytes32 chainKey) external view virtual returns (uint256);

Parameters

Name	Type	Description
chainKey	`bytes32`

Returns

Name	Type	Description
<none>	`uint256`

registerChain

Registers a chain identity (EVM or non-EVM). Admin only. Reverts ChainRegistryAlreadyRegistered on re-register — chain identities are permanent in v1.

function registerChain(bytes2 chainType, bytes calldata chainReference, uint256 evmChainId) external virtual;

Parameters

Name	Type	Description
chainType	`bytes2`	The ERC-7930 chain type (0x0000 = eip-155).
chainReference	`bytes`	The ERC-7930 chain reference (for EVM chains use the canonical minimal big-endian chainId encoding, or use addEvmChain which builds it).
evmChainId	`uint256`	The EVM chainId (informational; 0 for non-EVM chains).

setNativeIds

Sets the informational native ids of a registered chain. Admin only.

function setNativeIds(bytes32 chainKey, NativeIds calldata ids) external virtual;

Parameters

Name	Type	Description
chainKey	`bytes32`
ids	`NativeIds`

setGatewayCoverage

Records (or clears) gateway's coverage of a registered chain. Admin only.

function setGatewayCoverage(bytes32 chainKey, address gateway, bool covered, bool hubRouted) external virtual;

Parameters

Name	Type	Description
chainKey	`bytes32`	The registered chain key.
gateway	`address`	The local gateway adapter (non-zero).
covered	`bool`	True to record coverage, false to remove it.
hubRouted	`bool`	True when the gateway reaches the chain only via an intermediate hub (e.g. the ZetaChain ZEVM hub) — hub-routed coverage never counts toward directCoverageOf.

addEvmChain

ONE structured admin action that adds an EVM chain everywhere: registers the chain identity (eip-155 + canonical minimal big-endian reference), records the native ids declared by the enabled sections, then fans the per-adapter config out into every ENABLED gateway adapter's own ERC-7201 storage via direct internal lib calls (msg.sender stays the admin — never external self-calls), and finally records the coverage entries. Admin only.

Reverts ChainRegistryAlreadyRegistered if the chain identity already exists. Sections for adapter facets the diamond does not host must be left disabled (see AddEvmChainConfig).

function addEvmChain(AddEvmChainConfig calldata cfg) external virtual;

Parameters

Name	Type	Description
cfg	`AddEvmChainConfig`

exportSelectors

ERC-8153 selector export: this facet's cuttable selectors, tightly packed (4 bytes each).

Excludes exportSelectors() itself (0x0ef22643) - it is never cut into a diamond. Order matches forge inspect ChainRegistry methodIdentifiers (alphabetical by signature); kept in exact parity by ExportSelectorsParityTest. Chunks: addEvmChain((uint256,(bool,uint64,address,uint256,bool),(bool,uint32,bytes32,uint128,uint128),(bool,uint16,address),(bool,string,bytes,bytes),(bool,address),(bool,address),(bool,uint32,uint256,uint32,bytes32),(bool,uint32,bytes32,uint256),(bool,uint32),(bool,bytes,uint64),(address[],bool[]))) 0xdae1aa2e chainInfoOf(bytes32) 0x6a419425 chainKeyEvm(uint256) 0x585f36e8 chainKeyOf(bytes2,bytes) 0xa0f8fb2f coverageOf(bytes32) 0xeede78f6 directCoverageOf(bytes32) 0xbcf041b6 gatewaysOf(bytes32) 0xa61e0052 isRegistered(bytes32) 0x27258b22 nativeIdsOf(bytes32) 0x281a6e02 registerChain(bytes2,bytes,uint256) 0x6f4cb737 setGatewayCoverage(bytes32,address,bool,bool) 0x6688921d setNativeIds(bytes32,(uint64,uint32,uint16,uint32,string,uint32)) 0xa9b2394a

function exportSelectors() external pure virtual returns (bytes memory selectors);

Returns

Name	Type	Description
selectors	`bytes`