@crossecute/protocol 0.0.0-stage → 0.1.0

package/contracts/messaging/transceiver/TransceiverCore.sol

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {OutboundBase} from "../outbound/OutboundBase.sol";
+import {Roles} from "../Roles.sol";
+import {Envelope} from "../Envelope.sol";
+import {DeliveryGas} from "../DeliveryGas.sol";
+import {ChainKey} from "../../addressing/ChainKey.sol";
+import {Erc7930} from "../../addressing/Erc7930.sol";
+import {IChainRegistryRefs} from "../../registry/IChainRegistryRefs.sol";
+import {Provenance} from "../../registry/Provenance.sol";
+import {IBootstrapAllowlist} from "./IBootstrapAllowlist.sol";
+import {ProxyInitCode} from "../../conduit/ProxyInitCode.sol";
+import {Create2} from "@openzeppelin/contracts/utils/Create2.sol";
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+
+/// @notice What a transceiver needs from the transmitter logic it arms a conduit with.
+interface ITransmitterInit {
+    function initialize(address owner, address transceiver, bytes32 salt) external;
+}
+
+/// @notice The one thing a transceiver tells a conduit after creating it.
+/// @dev The single exception to a transceiver having no authority over a conduit: the
+///      conduit cannot learn its receiver's address on a chain this one cannot derive, and
+///      only its transceiver authenticates the message carrying it.
+interface IConduitReceiverReport {
+    function onDestinationReceiverReported(bytes32 chainKey, bytes calldata receiver) external;
+}
+
+/// @notice What a transceiver is configured with, once, at initialization.
+/// @dev A struct, not loose arguments: initializers sit near the stack limit at `paris`.
+struct TransceiverConfig {
+    /// The only chance to name gateways (see `Roles.grantRole`).
+    address[] gateways;
+    address transmitterImplementation;
+    address receiverImplementation;
+    /// The governor's conduit, named by its owner, salt, and home: its transmitter
+    /// on that home, its receiver everywhere else. It owns this transceiver.
+    address governorOwner;
+    bytes32 governorSalt;
+    /// The governor's home as an ERC-7930 chain identifier, which becomes its route here.
+    bytes governorHome;
+    /// Where bootstrap fees go and the report float leaves to. Write-once.
+    address treasury;
+    /// The routing `setRouting` would set, so that on any chain but the governor's home this
+    /// transceiver can accept the bootstrap that creates its owner; the home must be
+    /// `Predetermined` and not suspended. Zero leaves it to the owner, which only the governor's
+    /// home can do.
+    IChainRegistryRefs chainRegistry;
+    bytes32 messageProvider;
+    Provenance minCounterpartProvenance;
+}
+
+/// @title TransceiverCore
+/// @notice The state, events, errors, and internal logic a transceiver's two contracts share:
+///         `TransceiverBase`, which holds the paths every message takes, and
+///         `TransceiverExtension`, which holds initialization, owner configuration, and views and
+///         runs by `DELEGATECALL` from `TransceiverBase`'s `fallback`.
+///
+/// @dev Both inherit this contract and nothing else that declares sequential storage before it,
+///      so the fields below sit at the same slots in each (R8.2). A provider's own fields come
+///      after them and are never touched by the extension.
+abstract contract TransceiverCore is Initializable, OutboundBase, Roles, OwnableUpgradeable {
+    /// This chain's chainKey: the home of every conduit this transceiver creates as a
+    /// transmitter.
+    /// @dev An immutable of each implementation, fixed when it is deployed on this chain, so a
+    ///      chain split cannot move a conduit's derivation. `TransceiverBase` refuses an
+    ///      extension whose value differs from its own.
+    bytes32 public immutable localChainKey;
+
+    /// @notice The initcode hash every crossecute conduit deploys from, for transmitters and
+    ///         receivers alike. See `Proxy` for why it has no constructor arguments.
+    /// @dev An input to Ethereum's CREATE2 formula only. zkSync deploys from a zksolc artifact
+    ///      hash instead; see `_predictConduit`.
+    /// @dev Immutable, not constant: a constant is evaluated at runtime, which would put the
+    ///      initcode in every runtime that reads this (#70); an immutable puts it in initcode only.
+    ///      Computed rather than written out so a build with other compiler settings, such as
+    ///      `forge coverage`'s unoptimized one, derives the conduits it deploys.
+    bytes32 public immutable PROXY_INIT_CODE_HASH = ProxyInitCode.hash();
+
+    /// The transmitter logic every conduit homed here is armed with. Write-once: conduits
+    /// lock when armed, so a change would split them into two logic versions by creation time.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    address internal _transmitterImplementation;
+    /// The receiver logic every conduit homed elsewhere is armed with. Write-once.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    address internal _receiverImplementation;
+
+    /// Whether conduit addresses here differ from Ethereum's CREATE2. When true, every receiver
+    /// created here is reported to its home, which cannot derive it. Write-once, and set by the
+    /// contract rather than its caller, so it cannot disagree with `_predictConduit`.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    bool internal _addressesDiverge;
+
+    /// The registry this transceiver reads provenance and derivations from.
+    IChainRegistryRefs internal _chainRegistry;
+    /// keccak256 of this transceiver's message provider name, e.g. "layerzero".
+    bytes32 internal _messageProvider;
+    /// The weakest counterpart provenance this transceiver will send to or accept from.
+    /// @dev A parity-chain counterpart is `Predetermined`. Solana, Sui, Aptos, Starknet, zkSync,
+    ///      and Tron reach only `Unique`, so this decides whether this transceiver talks to them.
+    Provenance internal _minCounterpartProvenance;
+
+    /// chainKey => what standing a conduit up there costs, on top of the message fee.
+    /// @dev Pays for the return leg on a chain that has one: a diverging chain reports each
+    ///      conduit home from its float. Zero by default, so parity destinations, which never
+    ///      report, pay nothing. The fee lands in this chain's treasury in this chain's
+    ///      currency; the float there is funded out of band.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    mapping(bytes32 => uint256) internal _bootstrapFee;
+
+    /// Where a bootstrap fee goes, the moment it is charged, and the only address the report
+    /// float leaves to. Write-once.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    address internal _treasury;
+
+    /// True only while a receiver report is being sent, which pays from this contract's float.
+    bool internal _reporting;
+
+    /// May set bootstrap fees besides the owner. The owner is the governor's conduit, which off
+    /// the governor's home acts only through a cross-chain message, so this lets a local key
+    /// price or halt bootstraps (#78). Set and replaced by the owner.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverExtension`
+    address internal _operator;
+
+    /// Where set, the only conduits that may bootstrap or be quoted one. Set by the owner; zero
+    /// lets every conduit.
+    // forge-lint: disable-next-line(unused-state-variables) read only by `TransceiverBase` and `TransceiverExtension`
+    IBootstrapAllowlist internal _bootstrapAllowlist;
+
+    event ConduitCreated(address indexed owner, address indexed conduit, bytes32 salt, bytes32 homeChainKey);
+    /// @dev Path B's record, since a transceiver is not an ERC-7786 gateway source and emits
+    ///      no `MessageSent`. `(chainKey, owner, salt)` identifies the conduit.
+    event BootstrapSent(bytes32 indexed destinationChainKey, address indexed owner, bytes32 salt);
+    event TransmitterImplementationSet(address implementation);
+    event ReceiverImplementationSet(address implementation);
+    event AddressesDivergeSet(bool addressesDiverge);
+    event RoutingSet(address chainRegistry, bytes32 messageProvider, Provenance minCounterpartProvenance);
+    event BootstrapFeeSet(bytes32 indexed chainKey, uint256 fee);
+    event OperatorSet(address operator);
+    event BootstrapAllowlistSet(address allowlist);
+    event BootstrapFeePaid(bytes32 indexed chainKey, address indexed to, uint256 amount);
+    event DestinationReceiverReported(bytes32 indexed chainKey, address indexed owner, bytes32 salt, address conduit);
+    event ReceiverReported(bytes32 indexed home, address indexed owner, bytes32 salt, address receiver);
+    event Withdrawn(address indexed to, uint256 amount);
+
+    error ZeroOwner();
+    /// @dev The caller is not the conduit `(owner, salt)` resolves to.
+    error NotTheConduit(address owner, bytes32 salt, address caller);
+    error NoConduitImplementation();
+    error NoTreasury();
+    /// @dev The counterpart on that chain is not a 20-byte EVM address, so no EVM CREATE2
+    ///      prediction applies there.
+    error CounterpartNotEvm(bytes32 chainKey);
+    error NoChainRegistry();
+    /// @dev The registry holds no deployment record for this provider.
+    error NoProviderDeployment();
+    /// @dev The route resolved to a known chain, but the sender is not its counterpart.
+    error NotCounterpart(bytes32 chainKey);
+    /// @dev The registry has suspended the chain.
+    error ChainSuspended(bytes32 chainKey);
+    /// @dev The chain's grade is below this transceiver's bar.
+    error InsufficientCounterpartProvenance(bytes32 chainKey, Provenance grade);
+    /// @dev Re-pointing a counterpart would redirect the destination; moving one is a redeploy.
+    error CounterpartAlreadySet(bytes32 chainKey);
+    /// @dev A `Predetermined` chain's counterpart is `_parityAddress`, in use before any is
+    ///      recorded, so a recorded one may only restate it.
+    error CounterpartNotParity(bytes32 chainKey);
+    /// @dev The derivation inputs are not the ones this transaction approved. See
+    ///      `resolveCounterpart`.
+    error ParamsCommitmentMismatch(bytes32 chainKey);
+    /// @dev A chain reported an address that says it lives somewhere else.
+    error ReportedChainMismatch(bytes32 authenticated, bytes32 reported);
+    /// @dev A chain whose addresses this contract can recompute tried to report one; the
+    ///      derivation outranks the claim.
+    error ChainDoesNotReport(bytes32 chainKey);
+    /// @dev The registry or provider id is already set to a different value. See `setRouting`.
+    error RoutingAlreadySet();
+    /// @dev This chain is never a destination or an origin: a conduit homed here is its
+    ///      transmitter, and a receiver here would collide with it.
+    error IsLocalChain(bytes32 chainKey);
+    /// @dev The caller sent less than the destination's fee.
+    error InsufficientBootstrapFee(uint256 required, uint256 provided);
+    /// @dev The destination reports its receivers, and its bootstrap fee is unset.
+    error NoBootstrapFee(bytes32 chainKey);
+    /// @dev The registry has not marked the provider's transceiver on that chain live.
+    error DestinationNotLive(bytes32 chainKey);
+    error FeeTransferFailed(address to, uint256 amount);
+    /// @dev An EVM receiver can only answer to an EVM transmitter.
+    error SourceTransmitterNotEvm(bytes32 transmitter);
+    /// @dev The bootstrap carries a transmitter other than the one the home's transceiver derives
+    ///      for this conduit, so the origin's provider id, route, or transceiver address disagree
+    ///      with this chain's. Refused on the first bootstrap rather than leaving every such
+    ///      conduit unreachable.
+    error SourceTransmitterMismatch(address expected, address carried);
+    error NotTreasury(address caller);
+    error NotOwnerOrOperator(address caller);
+    error NotAllowed(address conduit);
+    error WithdrawFailed(uint256 amount);
+
+    constructor() {
+        localChainKey = ChainKey.local();
+    }
+
+    /* ============================== conduit derivation ============================= */
+
+    /// @notice The salt an owner's conduit deploys at, on every chain.
+    /// @dev The owner is the identity every chain names; the salt lets one owner hold several
+    ///      conduits; the home separates the same owner and salt homed on two chains, whose
+    ///      transmitter on one would otherwise sit where the other's receiver lands. The home
+    ///      is its own field: adding or XORing it into `salt` would let one owner make two
+    ///      homes collide. `abi.encode` is fixed-width, so no two triples collide.
+    function _conduitSalt(address owner, bytes32 salt, bytes32 homeChainKey) internal pure returns (bytes32) {
+        return keccak256(abi.encode(owner, salt, homeChainKey));
+    }
+
+    /// @notice Where an owner's conduit lives on this chain, before it exists.
+    /// @dev Ethereum's CREATE2, identical wherever the formula holds since all three inputs
+    ///      are: this address (one per provider on every chain), the salt, and a constant
+    ///      initcode. zkSync and Tron derive differently, so a variant there overrides this,
+    ///      in both its `TransceiverBase` and its extension, and `_deployConduit` with it;
+    ///      `_createConduit` checks the two agree.
+    function _predictConduit(address owner, bytes32 salt, bytes32 homeChainKey)
+        internal
+        view
+        virtual
+        returns (address)
+    {
+        return Create2.computeAddress(_conduitSalt(owner, salt, homeChainKey), PROXY_INIT_CODE_HASH, address(this));
+    }
+
+    /// @notice `(owner, salt)`'s conduit homed on this chain: its transmitter here.
+    /// @dev One expression for the bootstrap caller check, the transmitter a bootstrap and its
+    ///      quote carry, and every lookup of a conduit a report is for, so they cannot drift.
+    function _localConduit(address owner, bytes32 salt) internal view returns (address) {
+        return _predictConduit(owner, salt, localChainKey);
+    }
+
+    /// @notice The exact report bytes for `(owner, salt)` and `receiver`.
+    function _reportPayload(address owner, bytes32 salt, address receiver) internal view returns (bytes memory) {
+        return Envelope.encodeReceiverReport(owner, salt, Erc7930.encodeEvm(block.chainid, receiver));
+    }
+
+    /* ================================= counterparts ================================ */
+
+    /// @inheritdoc OutboundBase
+    ///
+    /// @dev Applies the registry's per-chain grade and suspension, which every provider's
+    ///      transceiver reads alike. Every bootstrap and report sent, and every delivery
+    ///      authenticated, goes through here, so a suspended chain is cut off both ways.
+    ///
+    /// @dev An unset counterpart on a `Predetermined` chain is `_parityAddress(chainKey)`: every
+    ///      transceiver of a provider is a `Proxy` deployed through `ProxyDeployer` at
+    ///      one salt by the deployer the registry records for that chain, which is what
+    ///      `Predetermined` means (#33).
+    function _counterpartOn(bytes32 chainKey) internal view virtual override returns (bytes memory) {
+        if (chainKey == localChainKey) revert IsLocalChain(chainKey);
+        if (address(_chainRegistry) == address(0)) revert NoChainRegistry();
+        if (_chainRegistry.isSuspended(chainKey)) revert ChainSuspended(chainKey);
+
+        Provenance grade = _chainRegistry.provenanceFor(chainKey);
+        if (uint8(grade) < uint8(_minCounterpartProvenance)) {
+            revert InsufficientCounterpartProvenance(chainKey, grade);
+        }
+
+        if (!hasCounterpart(chainKey)) {
+            if (grade != Provenance.Predetermined) revert NoCounterpartFor(chainKey);
+            return abi.encodePacked(_parityAddress(chainKey));
+        }
+        return OutboundBase._counterpartOn(chainKey);
+    }
+
+    /// @notice The counterpart on `chainKey` as an EVM address, refusing any other width.
+    function _evmCounterpartOn(bytes32 chainKey) internal view returns (address) {
+        bytes memory there = _counterpartOn(chainKey);
+        if (there.length != 20) revert CounterpartNotEvm(chainKey);
+        // forge-lint: disable-next-line(unsafe-typecast) length checked above
+        return address(bytes20(there));
+    }
+
+    /// @notice Where this provider's transceiver sits on the `Predetermined` chain `chainKey`: the
+    ///         registry's prediction from the deployer recorded for that chain.
+    /// @dev Not `address(this)`: a chain added after a deployer rotation has a different
+    ///      deployer, hence a different address. Reverts while the provider's deployment, or its
+    ///      entry on `chainKey`, is unrecorded, so nothing authenticates or is sent to a guessed
+    ///      address.
+    function _parityAddress(bytes32 chainKey) internal view virtual returns (address) {
+        return _chainRegistry.predictTransceiver(chainKey, _messageProvider);
+    }
+
+    /* =================================== sending =================================== */
+
+    /// @notice Where a provider returns an overpaid fee: whoever paid it.
+    /// @dev A report's overpayment returns to the float it was paid from. Anything else, a
+    ///      bootstrap above all, refunds the conduit that paid.
+    function _refundTo() internal view virtual override returns (address) {
+        return _reporting ? address(this) : msg.sender;
+    }
+
+    /// @inheritdoc OutboundBase
+    /// @dev By the envelope, not `_reporting`, so `quoteMessage` prices a report as it is sent.
+    ///      A report's gas is fixed here because the float pays for it.
+    function _defaultGas(bytes memory payload) internal pure override returns (uint256) {
+        return Envelope.isReceiverReport(payload) ? DeliveryGas.REPORT : DeliveryGas.BOOTSTRAP;
+    }
+}

package/contracts/messaging/transceiver/TransceiverExtension.sol

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {TransceiverCore, TransceiverConfig} from "./TransceiverCore.sol";
+import {IBootstrapAllowlist} from "./IBootstrapAllowlist.sol";
+import {Erc7930} from "../../addressing/Erc7930.sol";
+import {IChainRegistryRefs} from "../../registry/IChainRegistryRefs.sol";
+import {Provenance} from "../../registry/Provenance.sol";
+
+/// @title TransceiverExtension
+/// @notice A transceiver's initialization, owner configuration, float withdrawal, and the views
+///         no contract calls. Runs only by `DELEGATECALL` from `TransceiverBase`'s `fallback`, so
+///         its storage is the transceiver's and `msg.sender` is the transceiver's caller.
+///
+/// @dev Provider-agnostic: every provider's transceiver on a chain can name the same one. A
+///      chain whose conduit addresses diverge uses the matching variant in
+///      `DivergentTransceiver.sol`, which derives as that chain's `TransceiverBase` does.
+///
+/// @dev Holds no upgrade path and calls no address it reads from storage except the registry the
+///      base already calls. Called directly, it runs against its own empty storage, where every
+///      owner and treasury check fails and initialization is disabled.
+contract TransceiverExtension is TransceiverCore {
+    /// @dev `initializeBase` was not called by the transceiver itself.
+    error NotSelf(address caller);
+    /// @dev Sending is `TransceiverBase`'s; the extension's copy of `quoteMessage` is unreachable
+    ///      through a transceiver, whose own copy answers first.
+    error SendsNothing();
+
+    constructor() {
+        _disableInitializers();
+    }
+
+    /* ================================ initialization ============================== */
+
+    /// @notice Configure and grant the gateways. See `TransceiverBase.__TransceiverBase_init`,
+    ///         the only caller.
+    ///
+    /// @dev Reachable through the transceiver's `fallback` by anyone while it is initializing, so
+    ///      it accepts only the transceiver's self-call, as `Roles.grantRole` does (#68).
+    function initializeBase(TransceiverConfig memory c, bool addressesDiverge_) external onlyInitializing {
+        if (msg.sender != address(this)) revert NotSelf(msg.sender);
+        if (c.transmitterImplementation == address(0)) revert NoConduitImplementation();
+        if (c.receiverImplementation == address(0)) revert NoConduitImplementation();
+        if (c.treasury == address(0)) revert NoTreasury();
+        if (c.governorOwner == address(0)) revert ZeroOwner();
+
+        // The identifier names the owner's home, so it must be the canonical one for its key.
+        bytes32 governorHome = keccak256(c.governorHome);
+        _requireNames(c.governorHome, governorHome);
+
+        _transmitterImplementation = c.transmitterImplementation;
+        emit TransmitterImplementationSet(c.transmitterImplementation);
+        _receiverImplementation = c.receiverImplementation;
+        emit ReceiverImplementationSet(c.receiverImplementation);
+        _addressesDiverge = addressesDiverge_;
+        emit AddressesDivergeSet(addressesDiverge_);
+        _treasury = c.treasury;
+
+        __Ownable_init(_predictConduit(c.governorOwner, c.governorSalt, governorHome));
+
+        // Born accepting the governor's home as an origin: the owner is the governor's
+        // conduit here, which only a bootstrap from that home can create.
+        if (address(c.chainRegistry) != address(0)) {
+            _setRouting(c.chainRegistry, c.messageProvider, c.minCounterpartProvenance);
+            // Only the owner, which that bootstrap creates, could set a counterpart, so the
+            // home's must resolve now or the transceiver is never usable (#32).
+            if (governorHome != localChainKey) _counterpartOn(governorHome);
+        }
+        if (governorHome != localChainKey) _setRoute(governorHome, c.governorHome);
+
+        for (uint256 i; i < c.gateways.length; ++i) {
+            if (c.gateways[i] != address(0)) {
+                _grantInitialRole(GATEWAY_ROLE, c.gateways[i]);
+            }
+        }
+    }
+
+    /* ================================ configuration ================================ */
+
+    /// @notice Teach this transceiver how a chain is named. Write-once, and the owner's.
+    /// @dev A binding wraps this only where it keeps a provider-native id.
+    function setRoute(bytes32 chainKey, bytes memory route) public onlyOwner {
+        _setRoute(chainKey, route);
+    }
+
+    /// @notice Point this transceiver at the registry, name its provider id, and set its
+    ///         provenance bar.
+    ///
+    /// @dev The registry and provider id are write-once, like routes and counterparts:
+    ///      repointing either would redirect every future lookup. The same pair again is a
+    ///      no-op; a different one reverts `RoutingAlreadySet`.
+    ///
+    /// @dev `minCounterpartProvenance` stays rebindable and is written on every call: it is
+    ///      how the owner reacts to a bridge's standing changing without a redeploy.
+    function setRouting(
+        IChainRegistryRefs chainRegistry_,
+        bytes32 messageProvider_,
+        Provenance minCounterpartProvenance_
+    ) external onlyOwner {
+        _setRouting(chainRegistry_, messageProvider_, minCounterpartProvenance_);
+    }
+
+    function _setRouting(
+        IChainRegistryRefs chainRegistry_,
+        bytes32 messageProvider_,
+        Provenance minCounterpartProvenance_
+    ) private {
+        if (address(_chainRegistry) != address(0)) {
+            if (_chainRegistry != chainRegistry_ || _messageProvider != messageProvider_) {
+                revert RoutingAlreadySet();
+            }
+        } else {
+            _chainRegistry = chainRegistry_;
+            _messageProvider = messageProvider_;
+        }
+
+        _minCounterpartProvenance = minCounterpartProvenance_;
+        emit RoutingSet(address(chainRegistry_), messageProvider_, minCounterpartProvenance_);
+    }
+
+    /// @notice Record where this provider's transceiver sits on another chain.
+    ///
+    /// @dev Held here, not in the registry, because a location is per (chain, provider) and
+    ///      this transceiver is that pair. The registry holds what is common to every provider:
+    ///      `provenanceFor(chainKey)`. Write-once: re-pointing a counterpart redirects it.
+    /// @param interop Canonical ERC-7930 bytes, so the registry can check it is well-formed
+    ///        and on `chainKey`. The address half is stored, since inbound senders are
+    ///        compared to it.
+    function setCounterpart(bytes32 chainKey, bytes calldata interop) external onlyOwner {
+        if (address(_chainRegistry) == address(0)) revert NoChainRegistry();
+        if (hasCounterpart(chainKey)) revert CounterpartAlreadySet(chainKey);
+
+        _recordCounterpart(chainKey, interop);
+    }
+
+    /// @notice Record the counterpart by recomputing it from the registry's deriver and inputs
+    ///         for that chain, rather than by being told.
+    /// @dev The inputs were written in an earlier transaction, so `paramsCommitment` puts
+    ///      their hash in this one's signed calldata: the signers approve the inputs, not a
+    ///      pointer to them.
+    /// @param paramsCommitment `keccak256(chainRegistry.deriveParams(chainKey))`.
+    function resolveCounterpart(bytes32 chainKey, bytes32 paramsCommitment) external onlyOwner {
+        if (address(_chainRegistry) == address(0)) revert NoChainRegistry();
+        if (hasCounterpart(chainKey)) revert CounterpartAlreadySet(chainKey);
+        if (keccak256(_chainRegistry.deriveParams(chainKey)) != paramsCommitment) {
+            revert ParamsCommitmentMismatch(chainKey);
+        }
+
+        _recordCounterpart(chainKey, _chainRegistry.expectedTransceiver(chainKey));
+    }
+
+    /// @dev The default `_counterpartOn` answers on a `Predetermined` chain is live from the
+    ///      moment the chain is graded, so a counterpart recorded later must equal it: otherwise
+    ///      `hasCounterpart` being false would let the owner repoint a lane in use.
+    function _recordCounterpart(bytes32 chainKey, bytes memory interop) private {
+        _chainRegistry.validateLocation(chainKey, interop);
+        bytes memory addr = Erc7930.parseStrict(interop).addr;
+        if (
+            _chainRegistry.provenanceFor(chainKey) == Provenance.Predetermined
+                && keccak256(addr) != keccak256(abi.encodePacked(_parityAddress(chainKey)))
+        ) revert CounterpartNotParity(chainKey);
+        _setCounterpart(chainKey, addr);
+    }
+
+    /// @notice Name the contract that decides which conduits may bootstrap. Zero lets every
+    ///         conduit.
+    function setBootstrapAllowlist(IBootstrapAllowlist allowlist) external onlyOwner {
+        _bootstrapAllowlist = allowlist;
+        emit BootstrapAllowlistSet(address(allowlist));
+    }
+
+    /// @notice Name who may set bootstrap fees besides the owner. Zero names no one.
+    // forge-lint: disable-next-line(missing-zero-check) zero removes the operator
+    function setOperator(address operator_) external onlyOwner {
+        _operator = operator_;
+        emit OperatorSet(operator_);
+    }
+
+    /// @notice Set what standing a conduit up on `chainKey` costs. The owner's or the operator's.
+    /// @dev Rebindable: a price redirects nothing. Zero halts bootstraps to a reporting chain.
+    function setBootstrapFee(bytes32 chainKey, uint256 fee) external {
+        if (msg.sender != _operator && msg.sender != owner()) revert NotOwnerOrOperator(msg.sender);
+        _bootstrapFee[chainKey] = fee;
+        emit BootstrapFeeSet(chainKey, fee);
+    }
+
+    /* =================================== the float ================================= */
+
+    /// @notice Send `amount` of the float to the treasury, at the treasury's call.
+    /// @dev Gated, not a permissionless sweep: anyone able to empty the float could make every
+    ///      bootstrap here that reports revert.
+    function withdraw(uint256 amount) external {
+        address to = _treasury;
+        if (msg.sender != to) revert NotTreasury(msg.sender);
+
+        emit Withdrawn(to, amount);
+        (bool ok,) = to.call{value: amount}("");
+        if (!ok) revert WithdrawFailed(amount);
+    }
+
+    /* ==================================== views ==================================== */
+
+    /// @notice The salt an owner's conduit deploys at, on every chain. See `_conduitSalt`.
+    function conduitSalt(address owner, bytes32 salt, bytes32 homeChainKey) external pure returns (bytes32) {
+        return _conduitSalt(owner, salt, homeChainKey);
+    }
+
+    /// @notice Where an owner's conduit lives on this chain, before it exists.
+    function predictConduit(address owner, bytes32 salt, bytes32 homeChainKey) external view returns (address) {
+        return _predictConduit(owner, salt, homeChainKey);
+    }
+
+    /// @notice Where `(owner, salt)`'s transmitter lives, before it exists.
+    function predictTransmitter(address owner, bytes32 salt) external view returns (address) {
+        return _localConduit(owner, salt);
+    }
+
+    /// @notice The exact report bytes for `(owner, salt)` and `receiver`, so its cost can be
+    ///         quoted with `quoteMessage` before it is owed.
+    function reportPayload(address owner, bytes32 salt, address receiver) external view returns (bytes memory) {
+        return _reportPayload(owner, salt, receiver);
+    }
+
+    function transmitterImplementation() external view returns (address) {
+        return _transmitterImplementation;
+    }
+
+    function receiverImplementation() external view returns (address) {
+        return _receiverImplementation;
+    }
+
+    function addressesDiverge() external view returns (bool) {
+        return _addressesDiverge;
+    }
+
+    function chainRegistry() external view returns (IChainRegistryRefs) {
+        return _chainRegistry;
+    }
+
+    function messageProvider() external view returns (bytes32) {
+        return _messageProvider;
+    }
+
+    function minCounterpartProvenance() external view returns (Provenance) {
+        return _minCounterpartProvenance;
+    }
+
+    function bootstrapFee(bytes32 chainKey) external view returns (uint256) {
+        return _bootstrapFee[chainKey];
+    }
+
+    function operator() external view returns (address) {
+        return _operator;
+    }
+
+    function bootstrapAllowlist() external view returns (IBootstrapAllowlist) {
+        return _bootstrapAllowlist;
+    }
+
+    function treasury() external view returns (address) {
+        return _treasury;
+    }
+
+    /* =================================== sending =================================== */
+
+    function _sendMessage(bytes memory, bytes memory, bytes[] memory, uint256)
+        internal
+        pure
+        override
+        returns (bytes32)
+    {
+        revert SendsNothing();
+    }
+
+    function _quoteMessage(bytes memory, bytes memory, bytes[] memory) internal pure override returns (uint256) {
+        revert SendsNothing();
+    }
+}

package/contracts/protocols/ProviderAddress.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Erc7930} from "../addressing/Erc7930.sol";
+
+/// @notice Narrowing a provider's address forms to an EVM address, refusing rather than
+///         truncating or padding anything that is not one (R4.3).
+library ProviderAddress {
+    error UnsupportedRecipient(bytes addr);
+    error UnsupportedSender(bytes32 sender);
+    /// @notice A provider endpoint passed to a constructor was zero; it is immutable.
+    error ZeroEndpoint();
+
+    /// @notice The receiving address, for a provider that delivers to it as an EVM address
+    ///         (CCIP, Hyperlane, Wormhole, OP Stack).
+    /// @dev A recipient is only checked against the recorded counterpart, which may be a
+    ///      non-EVM address. LayerZero is exempt: it delivers to its recorded peer instead.
+    function evmRecipient(bytes memory recipient) internal pure returns (address) {
+        bytes memory addr = Erc7930.parseStrict(recipient).addr;
+        if (addr.length != 20) revert UnsupportedRecipient(addr);
+        // forge-lint: disable-next-line(unsafe-typecast) length checked above
+        return address(bytes20(addr));
+    }
+
+    /// @notice A provider-reported 32-byte sender, left-padded when it is an EVM address.
+    /// @dev Nonzero high bytes are a non-EVM sender; truncating would let its low 20 bytes
+    ///      pass as an unrelated EVM account.
+    function evmSender(bytes32 sender) internal pure returns (address) {
+        if (uint256(sender) > type(uint160).max) revert UnsupportedSender(sender);
+        return address(uint160(uint256(sender)));
+    }
+}