@crossecute/protocol 0.0.0 → 0.1.1

package/contracts/registry/ChainRegistry.sol

@@ -0,0 +1,667 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+import {IVmDeriver} from "../derivation/IVmDeriver.sol";
+import {AddressDerive} from "../derivation/AddressDerive.sol";
+import {Provenance} from "./Provenance.sol";
+import {ProviderDeployment, Status} from "./IChainRegistryRefs.sol";
+import {IRefValidator} from "./IRefValidator.sol";
+import {ICommitmentScheme, SchemeFold} from "./ICommitmentScheme.sol";
+import {Erc7930} from "../addressing/Erc7930.sol";
+import {Move} from "../addressing/Move.sol";
+import {PROXY_DEPLOYER, proxySalt} from "../conduit/ProxyDeployer.sol";
+
+/// @notice A provider a registry is born knowing, with the CREATE2 inputs its contracts
+///         deploy from.
+struct ProviderSeed {
+    string name;
+    bytes32 salt;
+    bytes32 proxyInitCodeHash;
+}
+
+/// @notice What a registry is born knowing: enough for a transceiver on this chain to accept,
+///         with no owner call, the bootstrap that creates its owner (the governor's conduit).
+/// @dev Identical on every chain, so the registry lands at one CREATE2 address on each. Empty
+///      on a chain configured by its owner from the start.
+struct RegistrySeed {
+    /// The governor's home chain, as an ERC-7930 chain identifier.
+    bytes governorHome;
+    Provenance governorHomeGrade;
+    /// The account that deployed every seeded provider's transceiver on the home, and the
+    /// registry's initial `currentDeployer`. Required when a home and providers are seeded.
+    address deployer;
+    ProviderSeed[] providers;
+}
+
+/// @dev One slot.
+struct ChainSupport {
+    address deployedBy;
+    Status status;
+}
+
+/// @title ChainRegistry
+/// @notice One per chain, shared by every provider there: the directory of every chain this one
+///         talks to, and of what can be known about addresses on each.
+///
+/// @dev It answers questions about a chain, never about a counterpart: a transceiver's
+///      location is per provider and lives on that provider's transceiver, while how well an
+///      address on a chain can be known is the same for every provider, so it is answered here
+///      once.
+///
+/// @dev It holds a directory of chainKeys and message providers, and the per-chain policy a
+///      transceiver consults before recording anything: `provenanceFor`, `isSuspended`,
+///      `validateLocation`, `expectedTransceiver`, and `commitmentFor`. It holds no routes and
+///      no counterparts, and no conduit reads it, so a compromised registry cannot misroute a
+///      conduit's payload.
+///
+/// @dev Fixed: no proxy and no upgrade path, and a transceiver's pointer to it is write-once.
+///      A chain's grade is write-once too, and so is the deployer a provider is added on a chain
+///      under; the plugins (validator,
+///      deriver, derive params, commitment scheme) stay rebindable so their mistakes can be
+///      fixed, and every change waits out the owning timelock.
+contract ChainRegistry is Ownable {
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+
+    /* ================================= storage ================================= */
+
+    /// Set of keccak256(canonical ERC-7930 chain identifier).
+    EnumerableSet.Bytes32Set private _chainKeys;
+    /// chainKey => the canonical chain identifier it hashes from. Kept after removal.
+    mapping(bytes32 => bytes) private _chainIdentifier;
+
+    /// Set of keccak256(message provider name).
+    EnumerableSet.Bytes32Set private _messageProviders;
+    /// messageProvider => the name it hashes from.
+    mapping(bytes32 => string) private _messageProviderName;
+    /// messageProvider => the CREATE2 inputs its transceiver and conduits deploy from.
+    mapping(bytes32 => ProviderDeployment) private _deployment;
+
+    /// The deployer a provider added from now on is recorded under. See `setCurrentDeployer`.
+    address public currentDeployer;
+    /// chainKey => messageProvider => who deployed that provider's transceiver there, and whether
+    /// sends may reach it. Packs into one slot.
+    mapping(bytes32 => mapping(bytes32 => ChainSupport)) private _support;
+
+    /// messageProvider => the transceiver on this chain that serves it.
+    mapping(bytes32 => address) private _localTransceiver;
+    /// The reverse: which provider a transceiver on this chain serves.
+    mapping(address => bytes32) private _providerOfTransceiver;
+
+    /// chainKey => the contract that computes addresses on that chain, so callers never
+    /// branch on VM.
+    mapping(bytes32 => IVmDeriver) private _deriverOf;
+    /// chainKey => the abi-encoded `(Scheme, bytes)` its deriver expects. Stored so
+    /// `expectedTransceiver` takes no inputs.
+    mapping(bytes32 => bytes) private _deriveParams;
+
+    /// chainKey => optional value-range validator for what ERC-7930 cannot express, e.g.
+    /// Starknet felts.
+    mapping(bytes32 => IRefValidator) private _validatorOf;
+    /// chainKey => what an address claim about this chain is worth, given at registration.
+    /// @dev `Unique` for chains this contract cannot recompute: Starknet (Pedersen), and
+    ///      zkSync and Tron (different CREATE2).
+    mapping(bytes32 => Provenance) private _provenanceOf;
+    /// chainKey => whether transceivers refuse it. See `setSuspended`.
+    mapping(bytes32 => bool) private _suspended;
+
+    /// chainKey => messageProvider => abi-encoded `Move.MoveQualifier` for that provider's
+    /// transceiver there.
+    /// @dev A Move call target is `address::module::function`, so the address alone does not
+    ///      identify it. Advisory: only a destination executor off-chain reads it.
+    mapping(bytes32 => mapping(bytes32 => bytes)) private _qualifiers;
+
+    /// chainKey => the primitive that chain's receiver hashes commitments with.
+    /// @dev A mapping rather than the `Scheme` enum, which is compiled into every locked
+    ///      transmitter and cannot grow. Mutable because nothing enforces with it: a receiver
+    ///      checks its own compiled fold.
+    mapping(bytes32 => ICommitmentScheme) private _commitmentSchemeOf;
+
+    /* ================================== events ================================= */
+
+    event ChainKeyAdded(bytes32 indexed chainKey, bytes chainIdentifier, Provenance provenance);
+    event ChainKeyRemoved(bytes32 indexed chainKey);
+    event MessageProviderAdded(bytes32 indexed messageProvider, string name);
+    event MessageProviderRemoved(bytes32 indexed messageProvider);
+    event LocalTransceiverSet(bytes32 indexed messageProvider, address transceiver);
+    event ProviderDeploymentSet(bytes32 indexed messageProvider, bytes32 salt, bytes32 proxyInitCodeHash);
+    event CurrentDeployerSet(address deployer);
+    event ProviderAddedOnChain(bytes32 indexed chainKey, bytes32 indexed messageProvider, address deployedBy);
+    event PendingRekeyed(bytes32 indexed chainKey, bytes32 indexed messageProvider, address deployedBy);
+    event MarkedLive(bytes32 indexed chainKey, bytes32 indexed messageProvider);
+    event DeriverSet(bytes32 indexed chainKey, address deriver);
+    event DeriveParamsSet(bytes32 indexed chainKey, uint8 scheme, bytes32 paramsHash);
+    event ValidatorSet(bytes32 indexed chainKey, address validator);
+    event SuspendedSet(bytes32 indexed chainKey, bool suspended);
+    event QualifierSet(bytes32 indexed chainKey, bytes32 indexed messageProvider, bytes32 qualifierHash);
+    event CommitmentSchemeSet(bytes32 indexed chainKey, address scheme);
+
+    /* ================================== errors ================================= */
+
+    /// @dev A write-once value, once recorded, is fixed: a provider deployment, a chain's grade,
+    ///      the deployer a provider was added on a chain under, or a Move qualifier.
+    error AlreadySet();
+    /// @dev Only an `eip155` chain can be `Predetermined`: that is the grade the EVM CREATE2
+    ///      prediction trusts.
+    error NotEvmChain();
+    error NoCounterpart();
+    /// @dev No salt recorded for this provider.
+    error NoProviderDeployment();
+    error ZeroSalt();
+    error ZeroDeployedBy();
+    /// @dev The call named a deployer other than `currentDeployer`: a registry that applied a
+    ///      rotation in another order refuses instead of recording a different one.
+    error DeployerMismatch(address expected, address current);
+    /// @dev The provider was never added on this chain.
+    error NotOnChain(bytes32 chainKey, bytes32 messageProvider);
+    /// @dev Only a `Pending` entry can be re-keyed or marked live.
+    error NotPending(bytes32 chainKey, bytes32 messageProvider);
+    error ZeroInitCodeHash();
+    error UnknownChainKey();
+    error UnknownMessageProvider();
+    error EmptyName();
+    error NoDeriver();
+    error NoDeriveParams();
+    error DeriverChainMismatch();
+    error SchemeNotSupported();
+    /// @dev No primitive registered for this chain. Reverting beats returning a digest the
+    ///      destination might never match; see `Commitment._hash`.
+    error NoCommitmentScheme();
+    error NoQualifier();
+
+    /* =============================== constructor =============================== */
+
+    /// @param owner_ This chain's timelock.
+    /// @dev Seeding goes through the same internal setters the owner uses later, so a seeded
+    ///      entry is write-once exactly like one added afterwards.
+    constructor(address owner_, RegistrySeed memory seed) Ownable(owner_) {
+        if (seed.deployer != address(0)) _setCurrentDeployer(seed.deployer);
+        bytes32 home;
+        if (seed.governorHome.length != 0) home = _addChainKey(seed.governorHome, seed.governorHomeGrade);
+        for (uint256 i; i < seed.providers.length; ++i) {
+            ProviderSeed memory p = seed.providers[i];
+            bytes32 provider = _addMessageProvider(p.name);
+            _setProviderDeployment(provider, p.salt, p.proxyInitCodeHash);
+            if (home != bytes32(0)) _addProviderOnChain(home, provider, seed.deployer, Status.Live);
+        }
+    }
+
+    /* ================================ directory ================================ */
+
+    /// @notice Register a chain by its ERC-7930 chain identifier, with what an address claim
+    ///         about it is worth.
+    /// @dev Takes the envelope, not a hash, so `parseStrict` rejects a non-canonical framing
+    ///      before it becomes a permanent key.
+    /// @dev The grade is write-once and has no default, so whether the chain reports its
+    ///      receivers is fixed when it is first registered, even across a removal. The same
+    ///      grade again is a no-op.
+    /// @param identifier ERC-7930 bytes. A conduit envelope is accepted and reduced to
+    ///                   its chain identifier form.
+    function addChainKey(bytes calldata identifier, Provenance provenance)
+        external
+        onlyOwner
+        returns (bytes32 chainKey)
+    {
+        return _addChainKey(identifier, provenance);
+    }
+
+    function _addChainKey(bytes memory identifier, Provenance provenance) private returns (bytes32 chainKey) {
+        bytes memory canonical = Erc7930.toChainIdentifier(identifier);
+        chainKey = keccak256(canonical);
+
+        if (_chainIdentifier[chainKey].length != 0) {
+            if (_provenanceOf[chainKey] != provenance) revert AlreadySet();
+        } else {
+            if (provenance == Provenance.Predetermined && Erc7930.parseStrict(canonical).chainType != Erc7930.CT_EIP155)
+            {
+                revert NotEvmChain();
+            }
+            _chainIdentifier[chainKey] = canonical;
+            _provenanceOf[chainKey] = provenance;
+        }
+
+        if (_chainKeys.add(chainKey)) emit ChainKeyAdded(chainKey, canonical, provenance);
+    }
+
+    /// @notice Drop a chain from the directory.
+    /// @dev Stops onboarding only: `validateLocation` requires membership, so no transceiver
+    ///      can record a new counterpart there. Its identifier and grade stay, so transceivers
+    ///      keep bootstrapping to it and accepting its reports; removal must not strand
+    ///      conduits. Cutting a chain off is `setSuspended`, which still applies after removal.
+    function removeChainKey(bytes32 chainKey) external onlyOwner {
+        if (!_chainKeys.remove(chainKey)) revert UnknownChainKey();
+        emit ChainKeyRemoved(chainKey);
+    }
+
+    /// @notice Refuse a chain, or stop refusing it.
+    /// @dev Every transceiver here reads this with the grade, in `_counterpartOn`, so a
+    ///      suspended chain gets no bootstrap or report and is accepted as no origin. It can only
+    ///      refuse, so lifting it is as safe as setting it. Conduits already standing on the
+    ///      chain still send to each other directly. Applies to a removed chain too: any chain
+    ///      ever registered can be cut off.
+    function setSuspended(bytes32 chainKey, bool suspended) external onlyOwner {
+        if (_chainIdentifier[chainKey].length == 0) revert UnknownChainKey();
+        _suspended[chainKey] = suspended;
+        emit SuspendedSet(chainKey, suspended);
+    }
+
+    /// @notice Whether transceivers refuse `chainKey`.
+    function isSuspended(bytes32 chainKey) external view returns (bool) {
+        return _suspended[chainKey];
+    }
+
+    /// @notice Register a message provider by name; the key is keccak256 of the name.
+    function addMessageProvider(string calldata name) external onlyOwner returns (bytes32 messageProvider) {
+        return _addMessageProvider(name);
+    }
+
+    function _addMessageProvider(string memory name) private returns (bytes32 messageProvider) {
+        if (bytes(name).length == 0) revert EmptyName();
+        messageProvider = keccak256(bytes(name));
+        if (_messageProviders.add(messageProvider)) {
+            _messageProviderName[messageProvider] = name;
+            emit MessageProviderAdded(messageProvider, name);
+        }
+    }
+
+    function removeMessageProvider(bytes32 messageProvider) external onlyOwner {
+        if (!_messageProviders.remove(messageProvider)) revert UnknownMessageProvider();
+        delete _messageProviderName[messageProvider];
+        emit MessageProviderRemoved(messageProvider);
+    }
+
+    /* ============================== configuration ============================== */
+
+    /// @notice Record the transceiver on this chain that serves one message provider. Zero
+    ///         retires the provider's entry.
+    function setLocalTransceiver(bytes32 messageProvider, address transceiver_) external onlyOwner {
+        if (!_messageProviders.contains(messageProvider)) revert UnknownMessageProvider();
+
+        address prev = _localTransceiver[messageProvider];
+        if (prev != address(0)) delete _providerOfTransceiver[prev];
+
+        _localTransceiver[messageProvider] = transceiver_;
+        if (transceiver_ != address(0)) _providerOfTransceiver[transceiver_] = messageProvider;
+
+        emit LocalTransceiverSet(messageProvider, transceiver_);
+    }
+
+    /// @notice Record the CREATE2 inputs a provider's contracts share on every chain.
+    ///
+    /// @dev Write-once: changing the salt or initcode hash moves the provider's transceiver on
+    ///      every chain and every conduit under it. The identical record again is a no-op.
+    ///
+    /// @dev Deploys nothing; it lets any chain reproduce the addresses. A record that does not
+    ///      match the deployment yields predictions that match nothing.
+    function setProviderDeployment(bytes32 messageProvider, bytes32 salt, bytes32 proxyInitCodeHash)
+        external
+        onlyOwner
+    {
+        _setProviderDeployment(messageProvider, salt, proxyInitCodeHash);
+    }
+
+    function _setProviderDeployment(bytes32 messageProvider, bytes32 salt, bytes32 proxyInitCodeHash) private {
+        if (!_messageProviders.contains(messageProvider)) {
+            revert UnknownMessageProvider();
+        }
+        if (salt == bytes32(0)) revert ZeroSalt();
+        if (proxyInitCodeHash == bytes32(0)) revert ZeroInitCodeHash();
+
+        ProviderDeployment storage d = _deployment[messageProvider];
+        if (d.salt != bytes32(0)) {
+            if (d.salt != salt || d.proxyInitCodeHash != proxyInitCodeHash) revert AlreadySet();
+            return;
+        }
+
+        _deployment[messageProvider] = ProviderDeployment({salt: salt, proxyInitCodeHash: proxyInitCodeHash});
+        emit ProviderDeploymentSet(messageProvider, salt, proxyInitCodeHash);
+    }
+
+    function providerDeployment(bytes32 messageProvider) external view returns (ProviderDeployment memory) {
+        return _deployment[messageProvider];
+    }
+
+    /* ============================ deployer rotation ============================ */
+
+    /// @notice Change the deployer later `addProviderOnChain` calls must name.
+    /// @dev Touches no entry already recorded, so no existing address moves.
+    function setCurrentDeployer(address deployer) external onlyOwner {
+        _setCurrentDeployer(deployer);
+    }
+
+    function _setCurrentDeployer(address deployer) private {
+        if (deployer == address(0)) revert ZeroDeployedBy();
+        currentDeployer = deployer;
+        emit CurrentDeployerSet(deployer);
+    }
+
+    /// @notice Record that a provider's transceiver on `chainKey` is deployed by `expectedDeployer`,
+    ///         `Pending` until `markLive`.
+    /// @dev Write-once. `expectedDeployer` must be `currentDeployer`, so a registry that applies
+    ///      this before or after a rotation reverts instead of recording a different deployer
+    ///      than its peers. The same deployer again is a no-op.
+    function addProviderOnChain(bytes32 chainKey, bytes32 messageProvider, address expectedDeployer)
+        external
+        onlyOwner
+    {
+        _addProviderOnChain(chainKey, messageProvider, expectedDeployer, Status.Pending);
+    }
+
+    function _addProviderOnChain(bytes32 chainKey, bytes32 messageProvider, address expectedDeployer, Status status)
+        private
+    {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        if (!_messageProviders.contains(messageProvider)) revert UnknownMessageProvider();
+        if (_deployment[messageProvider].salt == bytes32(0)) revert NoProviderDeployment();
+        if (expectedDeployer == address(0)) revert ZeroDeployedBy();
+
+        ChainSupport storage s = _support[chainKey][messageProvider];
+        if (s.status != Status.None) {
+            if (s.deployedBy != expectedDeployer) revert AlreadySet();
+            return;
+        }
+        if (expectedDeployer != currentDeployer) revert DeployerMismatch(expectedDeployer, currentDeployer);
+
+        s.deployedBy = expectedDeployer;
+        s.status = status;
+        emit ProviderAddedOnChain(chainKey, messageProvider, expectedDeployer);
+    }
+
+    /// @notice Change the deployer a `Pending` entry is predicted under, for a chain added before
+    ///         a rotation and not yet deployed.
+    /// @dev Never a `Live` entry: its transceiver exists and its address is fixed.
+    function rekeyPending(bytes32 chainKey, bytes32 messageProvider, address newDeployer) external onlyOwner {
+        ChainSupport storage s = _support[chainKey][messageProvider];
+        if (s.status != Status.Pending) revert NotPending(chainKey, messageProvider);
+        if (newDeployer == address(0)) revert ZeroDeployedBy();
+        s.deployedBy = newDeployer;
+        emit PendingRekeyed(chainKey, messageProvider, newDeployer);
+    }
+
+    /// @notice Allow sends to a provider's transceiver on `chainKey`.
+    /// @dev Call only after the deployment is checked without the deployer's help: code at the
+    ///      predicted address, the implementation's code hash, and `owner()`, `chainRegistry()` and
+    ///      `messageProvider()`. This contract cannot read another chain's code, so the check is
+    ///      the proposers' and the timelock delay is its review window.
+    function markLive(bytes32 chainKey, bytes32 messageProvider) external onlyOwner {
+        ChainSupport storage s = _support[chainKey][messageProvider];
+        if (s.status != Status.Pending) revert NotPending(chainKey, messageProvider);
+        s.status = Status.Live;
+        emit MarkedLive(chainKey, messageProvider);
+    }
+
+    /// @notice Whether sends to `messageProvider`'s transceiver on `chainKey` are allowed.
+    function isLive(bytes32 chainKey, bytes32 messageProvider) external view returns (bool) {
+        return _support[chainKey][messageProvider].status == Status.Live;
+    }
+
+    /// @notice The state of `messageProvider` on `chainKey`.
+    function statusOf(bytes32 chainKey, bytes32 messageProvider) external view returns (Status) {
+        return _support[chainKey][messageProvider].status;
+    }
+
+    /// @notice Who deployed, or will deploy, `messageProvider`'s transceiver on `chainKey`; zero
+    ///         where it was never added.
+    function deployedBy(bytes32 chainKey, bytes32 messageProvider) external view returns (address) {
+        return _support[chainKey][messageProvider].deployedBy;
+    }
+
+    /* ========================= PATH 2: salted derivation ======================= */
+
+    /// @notice Where a provider's transceiver lands on `chainKey`, recomputed from
+    ///         `PROXY_DEPLOYER`, the deployer recorded for that chain, and the provider's
+    ///         salt and initcode hash.
+    function predictTransceiver(bytes32 chainKey, bytes32 messageProvider) public view returns (address) {
+        ProviderDeployment memory d = _deployment[messageProvider];
+        if (d.salt == bytes32(0)) revert NoProviderDeployment();
+        _requireEvmDerivable(chainKey);
+        address by = _support[chainKey][messageProvider].deployedBy;
+        if (by == address(0)) revert NotOnChain(chainKey, messageProvider);
+        return AddressDerive.create2(PROXY_DEPLOYER, proxySalt(by, d.salt), d.proxyInitCodeHash);
+    }
+
+    /// @notice Where an owner's conduit lands on `chainKey`, before it exists: the
+    ///         transceiver from the provider's salt, then the conduit from the transceiver.
+    /// @dev The conduit salt must match `TransceiverCore._conduitSalt`; it is written out
+    ///      rather than imported, and `test/SaltedDeployment.t.sol` asserts the two agree.
+    /// @param homeChainKey The chain the conduit is homed on, which need not be `chainKey`.
+    function predictConduit(
+        bytes32 chainKey,
+        bytes32 messageProvider,
+        address owner,
+        bytes32 salt,
+        bytes32 homeChainKey
+    ) external view returns (address) {
+        ProviderDeployment memory d = _deployment[messageProvider];
+        if (d.salt == bytes32(0)) revert NoProviderDeployment();
+
+        address transceiver = predictTransceiver(chainKey, messageProvider);
+        return AddressDerive.create2(transceiver, keccak256(abi.encode(owner, salt, homeChainKey)), d.proxyInitCodeHash);
+    }
+
+    /// @dev Plain CREATE2 derivation holds only on a chain graded `Predetermined`.
+    function _requireEvmDerivable(bytes32 chainKey) private view {
+        if (!_isEvmDerivable(chainKey)) revert NoCounterpart();
+    }
+
+    function _isEvmDerivable(bytes32 chainKey) private view returns (bool) {
+        return uint8(provenanceFor(chainKey)) >= uint8(Provenance.Predetermined);
+    }
+
+    /// @notice What an address claim about `chainKey` is worth, as given at registration.
+    /// @dev Answers for a removed chain; reverts only for one never registered.
+    function provenanceFor(bytes32 chainKey) public view returns (Provenance) {
+        if (_chainIdentifier[chainKey].length == 0) revert UnknownChainKey();
+        return _provenanceOf[chainKey];
+    }
+
+    /// @notice Whether conduits on `chainKey` must report their own address home.
+    /// @dev True exactly where this contract cannot recompute addresses, so it cannot
+    ///      disagree with the grades. Where a receiver landed is held by its transmitter, not
+    ///      here. The home's side of `TransceiverExtension.addressesDiverge`.
+    function requiresReceiverCallback(bytes32 chainKey) external view returns (bool) {
+        return !_isEvmDerivable(chainKey);
+    }
+
+    /// @notice Check a location against everything this chain says about its addresses: the
+    ///         ERC-7930 canonicity rules, that it is on `chainKey`, and the chain's validator.
+    /// @dev A transceiver calls this before recording a counterpart, so one validator per chain serves
+    ///      every provider.
+    function validateLocation(bytes32 chainKey, bytes calldata interop) external view {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        // `parseStrict` runs inside: rejects bad versions, length mismatches, trailing
+        // bytes, and non-minimal eip155 chain references.
+        if (Erc7930.chainKey(interop) != chainKey) revert UnknownChainKey();
+
+        IRefValidator v = _validatorOf[chainKey];
+        if (address(v) != address(0)) v.validateRef(interop);
+    }
+
+    /// @notice Attach a value-range validator to a chain.
+    function setValidator(bytes32 chainKey, IRefValidator validator) external onlyOwner {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        _validatorOf[chainKey] = validator;
+        emit ValidatorSet(chainKey, address(validator));
+    }
+
+    /* ============================ Move qualifiers ============================= */
+
+    /// @notice Attach a qualified name to a provider's transceiver on a Move chain.
+    /// @dev Write-once: the same qualifier again is a no-op and a different one reverts
+    ///      `AlreadySet`, since re-pointing a call target is re-pointing the counterpart.
+    function setQualifier(bytes32 chainKey, bytes32 messageProvider, Move.MoveQualifier calldata q) external onlyOwner {
+        bytes memory identifier = _chainIdentifier[chainKey];
+        if (identifier.length == 0) revert UnknownChainKey();
+        if (!_messageProviders.contains(messageProvider)) revert UnknownMessageProvider();
+        Move.validate(q, Erc7930.parseStrict(identifier).chainType);
+
+        bytes32 qh = Move.hash(q);
+        bytes memory existing = _qualifiers[chainKey][messageProvider];
+        if (existing.length != 0) {
+            if (Move.hash(abi.decode(existing, (Move.MoveQualifier))) != qh) revert AlreadySet();
+            return;
+        }
+        _qualifiers[chainKey][messageProvider] = abi.encode(q);
+        emit QualifierSet(chainKey, messageProvider, qh);
+    }
+
+    /// @notice The qualified name a destination executor needs to build the call.
+    function qualifier(bytes32 chainKey, bytes32 messageProvider) external view returns (Move.MoveQualifier memory q) {
+        bytes memory raw = _qualifiers[chainKey][messageProvider];
+        if (raw.length == 0) revert NoQualifier();
+        q = abi.decode(raw, (Move.MoveQualifier));
+    }
+
+    /* ========================== commitment preview ============================ */
+
+    /// @notice Teach this registry the primitive `chainKey`'s receiver hashes with.
+    /// @dev Rebindable: it redirects nothing, so a wrong primitive must be fixable. Zero
+    ///      unregisters, and `commitmentFor` then reverts rather than answer wrongly.
+    function setCommitmentScheme(bytes32 chainKey, ICommitmentScheme scheme) external onlyOwner {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        _commitmentSchemeOf[chainKey] = scheme;
+        emit CommitmentSchemeSet(chainKey, address(scheme));
+    }
+
+    /// @notice Preview the commitment `chainKey`'s receiver will require over `elements`.
+    /// @dev For `eth_call` by a signer checking a payload; nothing on-chain may enforce with
+    ///      it. The fold is `SchemeFold`'s.
+    function commitmentFor(bytes32 chainKey, bytes[] calldata elements) external view returns (bytes32) {
+        ICommitmentScheme scheme = _commitmentSchemeOf[chainKey];
+        if (address(scheme) == address(0)) revert NoCommitmentScheme();
+        return SchemeFold.hashCalls(scheme, chainKey, elements);
+    }
+
+    /* ================= PATH 1 (uniform): per-chain derivation ================== */
+
+    /// @notice Point a chain at the contract that computes addresses on it.
+    function setDeriver(bytes32 chainKey, IVmDeriver deriver) external onlyOwner {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        _deriverOf[chainKey] = deriver;
+        emit DeriverSet(chainKey, address(deriver));
+    }
+
+    /// @notice Store the derivation inputs for a chain, checked against its deriver now
+    ///         rather than at the first resolve.
+    /// @param params abi.encode(VmDeriver.Scheme, bytes): shape is the scheme's business.
+    function setDeriveParams(bytes32 chainKey, bytes calldata params) external onlyOwner {
+        IVmDeriver d = _deriverOf[chainKey];
+        if (address(d) == address(0)) revert NoDeriver();
+
+        uint16 ct = Erc7930.parseStrict(_chainIdentifier[chainKey]).chainType;
+        (uint8 scheme,) = abi.decode(params, (uint8, bytes));
+        if (!d.supportsScheme(ct, scheme)) revert SchemeNotSupported();
+
+        _deriveParams[chainKey] = params;
+        emit DeriveParamsSet(chainKey, scheme, keccak256(params));
+    }
+
+    /// @notice The transceiver envelope expected on `chainKey`, recomputed now, whatever VM
+    ///         that chain runs.
+    /// @dev A deriver is external code: without the chainKey re-check a wrong one could return
+    ///      another chain's envelope for a transceiver to record as this chain's counterpart.
+    function expectedTransceiver(bytes32 chainKey) public view returns (bytes memory interop) {
+        IVmDeriver d = _deriverOf[chainKey];
+        if (address(d) == address(0)) revert NoDeriver();
+        bytes memory params = _deriveParams[chainKey];
+        if (params.length == 0) revert NoDeriveParams();
+
+        interop = d.deriveAddress(_chainIdentifier[chainKey], params);
+        if (Erc7930.chainKey(interop) != chainKey) revert DeriverChainMismatch();
+    }
+
+    /// @notice Every destination at once: the expected transceiver on each registered chain.
+    /// @dev Unconfigured or underivable chains yield an empty entry rather than reverting.
+    function expectedTransceivers() external view returns (bytes32[] memory keys, bytes[] memory interops) {
+        keys = _chainKeys.values();
+        uint256 n = keys.length;
+        interops = new bytes[](n);
+
+        for (uint256 i; i < n; ++i) {
+            if (address(_deriverOf[keys[i]]) == address(0)) continue;
+            if (_deriveParams[keys[i]].length == 0) continue;
+            // forge-lint: disable-next-line(calls-loop) a view self-call; failure is caught
+            try this.expectedTransceiver(keys[i]) returns (bytes memory io) {
+                interops[i] = io;
+            } catch {
+                // Leave empty: an underivable chain is expected, not exceptional.
+            }
+        }
+    }
+
+    /// @notice The stored derivation inputs for a chain.
+    function deriveParams(bytes32 chainKey) external view returns (bytes memory) {
+        return _deriveParams[chainKey];
+    }
+
+    /* ============================ configuration reads ========================== */
+
+    /// @notice The transceiver on this chain that serves `messageProvider`.
+    function localTransceiver(bytes32 messageProvider) external view returns (address) {
+        return _localTransceiver[messageProvider];
+    }
+
+    /// @notice Which provider a transceiver on this chain serves.
+    function providerOfTransceiver(address transceiver_) external view returns (bytes32) {
+        return _providerOfTransceiver[transceiver_];
+    }
+
+    function deriverOf(bytes32 chainKey) external view returns (IVmDeriver) {
+        return _deriverOf[chainKey];
+    }
+
+    function validatorOf(bytes32 chainKey) external view returns (IRefValidator) {
+        return _validatorOf[chainKey];
+    }
+
+    function commitmentSchemeOf(bytes32 chainKey) external view returns (ICommitmentScheme) {
+        return _commitmentSchemeOf[chainKey];
+    }
+
+    /* ============================== directory reads ============================ */
+
+    function chainKeyCount() external view returns (uint256) {
+        return _chainKeys.length();
+    }
+
+    function chainKeyAt(uint256 i) external view returns (bytes32) {
+        return _chainKeys.at(i);
+    }
+
+    function chainKeys() external view returns (bytes32[] memory) {
+        return _chainKeys.values();
+    }
+
+    function hasChainKey(bytes32 chainKey) external view returns (bool) {
+        return _chainKeys.contains(chainKey);
+    }
+
+    /// @notice The canonical ERC-7930 chain identifier a `chainKey` hashes from.
+    function chainIdentifier(bytes32 chainKey) external view returns (bytes memory) {
+        if (!_chainKeys.contains(chainKey)) revert UnknownChainKey();
+        return _chainIdentifier[chainKey];
+    }
+
+    function messageProviderCount() external view returns (uint256) {
+        return _messageProviders.length();
+    }
+
+    function messageProviderAt(uint256 i) external view returns (bytes32) {
+        return _messageProviders.at(i);
+    }
+
+    function messageProviders() external view returns (bytes32[] memory) {
+        return _messageProviders.values();
+    }
+
+    function hasMessageProvider(bytes32 messageProvider) external view returns (bool) {
+        return _messageProviders.contains(messageProvider);
+    }
+
+    function messageProviderName(bytes32 messageProvider) external view returns (string memory) {
+        if (!_messageProviders.contains(messageProvider)) revert UnknownMessageProvider();
+        return _messageProviderName[messageProvider];
+    }
+}