@crossecute/protocol 0.0.0-stage → 0.1.0

package/contracts/messaging/Call.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice One call in a payload.
+/// @dev The ERC-7579 `Execution` tuple, also used by ERC-7821, so existing payload builders
+///      work unchanged. Target and value are in the approved array, so a payload cannot be
+///      redirected or re-priced at execution.
+struct Call {
+    address target;
+    uint256 value;
+    bytes data;
+}
+
+/// @title Calls
+/// @notice Conversion between the typed `Call` and the canonical opaque element.
+/// @dev The two forms must hash identically, so an approval made in one form can be
+///      discharged in the other.
+library Calls {
+    /// @notice The canonical opaque element for a typed call.
+    /// @dev Encodes the fields, not the struct: `abi.encode(c)` prepends an offset word for the
+    ///      dynamic tuple and would hash differently.
+    function encode(Call memory c) internal pure returns (bytes memory) {
+        return abi.encode(c.target, c.value, c.data);
+    }
+
+    /// @notice The element hash. Equals `keccak256(encode(c))`.
+    function hash(Call memory c) internal pure returns (bytes32) {
+        return keccak256(abi.encode(c.target, c.value, c.data));
+    }
+
+    /// @notice Split a canonical opaque element back into a typed call. Reverts if it is not
+    ///         `abi.encode(address, uint256, bytes)`.
+    function decode(bytes memory element) internal pure returns (Call memory c) {
+        (c.target, c.value, c.data) = abi.decode(element, (address, uint256, bytes));
+    }
+
+    function encodeAll(Call[] memory calls) internal pure returns (bytes[] memory out) {
+        out = new bytes[](calls.length);
+        for (uint256 i; i < calls.length; ++i) {
+            out[i] = encode(calls[i]);
+        }
+    }
+}

package/contracts/messaging/Commitment.sol

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {ChainKey} from "../addressing/ChainKey.sol";
+import {Call, Calls} from "./Call.sol";
+import {Blake2b256} from "../derivation/Blake2b256.sol";
+
+/// @notice The hash a destination computes its commitments with.
+///
+/// @dev The fold is fixed and only the primitive varies, so the home can reproduce any
+///      destination's commitment for a signer. The cost is that a non-EVM receiver implements
+///      a byte fold rather than its native digest (TON's cell hash, Starknet's
+///      `poseidon_hash_span`).
+///
+/// @dev An EVM receiver only ever uses keccak256; the others are for the home building a
+///      commitment another VM will recompute.
+enum Scheme {
+    /// EVM. The opcode.
+    Keccak256,
+    /// Ton. `sha256` is an EVM builtin, so this stays computable on both sides.
+    Sha256,
+    /// Cardano. EIP-152 precompile 0x09: see `Blake2b256`. The reason dispatching
+    /// functions are `view` rather than `pure`.
+    Blake2b256Scheme,
+    /// Starknet. Declared, not implemented: Poseidon needs the exact round constants and MDS
+    /// matrix, checked against vectors (`docs/todo.md` §4). Until then a Starknet commitment
+    /// is computed off-chain and carried in an element calling that receiver's `commit`.
+    Poseidon
+}
+
+/// @title Commitment
+/// @notice The commitment over a call array, bound to exactly one destination.
+///
+/// @dev Seeded with the destination's chainKey, since conduits share addresses across chains
+///      and a commitment must not replay between them. A chainKey rather than a chain id
+///      because non-EVM chains have none; on the EVM it still derives from `block.chainid`.
+///
+/// @dev Defined over opaque elements, which it never looks inside, so no VM's call format is
+///      parsed in Solidity. The typed overloads produce the same hash, since `Calls.encode`
+///      yields exactly the opaque element.
+library Commitment {
+    /// @dev The scheme has no implementation on this chain, so a commitment for it must be
+    ///      computed off-chain and approved as a digest.
+    error SchemeNotComputable(Scheme scheme);
+    /// @dev An empty array would hash to the seed alone, an approval that runs nothing.
+    error EmptyCommitment();
+
+    /// @notice The hash a receiver on this chain will require, for typed calls.
+    function hashCalls(Call[] memory calls) internal view returns (bytes32) {
+        return hashCalls(ChainKey.local(), calls);
+    }
+
+    /// @notice The same value, from typed calls.
+    /// @dev Equal to the opaque overload over `Calls.encodeAll(calls)`, asserted in
+    ///      `test/PayloadEncoding.t.sol`. Array parameters are `memory` throughout because
+    ///      Solidity will not overload on data location.
+    function hashCalls(bytes32 destinationChainKey, Call[] memory calls) internal pure returns (bytes32 hashed) {
+        uint256 len = calls.length;
+        if (len == 0) revert EmptyCommitment();
+        hashed = _seed(destinationChainKey);
+        for (uint256 i = 0; i < len; i++) {
+            hashed = _fold(hashed, Calls.hash(calls[i]));
+        }
+    }
+
+    /// @notice Canonical: the hash a receiver on `destinationChainKey` requires, over the
+    ///         portable opaque elements.
+    /// @dev The source passes the destination's key; the local one yields a commitment the
+    ///      far side never matches.
+    function hashCalls(bytes32 destinationChainKey, bytes[] memory elements) internal pure returns (bytes32 hashed) {
+        uint256 len = elements.length;
+        if (len == 0) revert EmptyCommitment();
+        hashed = _seed(destinationChainKey);
+        for (uint256 i = 0; i < len; i++) {
+            hashed = _fold(hashed, keccak256(elements[i]));
+        }
+    }
+
+    /* ============================ non-EVM destinations =========================== */
+
+    /// @notice The commitment a destination using `scheme` will require.
+    /// @dev Source side only; EVM receivers use the keccak overloads above. `view` for
+    ///      `Blake2b256`'s precompile `staticcall`, read through `eth_call` by a signer.
+    function hashCalls(Scheme scheme, bytes32 destinationChainKey, bytes[] memory elements)
+        internal
+        view
+        returns (bytes32 hashed)
+    {
+        uint256 len = elements.length;
+        if (len == 0) revert EmptyCommitment();
+        hashed = _hash(scheme, abi.encode(destinationChainKey));
+        for (uint256 i = 0; i < len; i++) {
+            hashed = _hash(scheme, abi.encodePacked(hashed, _hash(scheme, elements[i])));
+        }
+    }
+
+    /// @notice The same value, from typed calls.
+    /// @dev Delegates to the opaque overload over `Calls.encodeAll`, so both spellings share
+    ///      one fold.
+    function hashCalls(Scheme scheme, bytes32 destinationChainKey, Call[] memory calls)
+        internal
+        view
+        returns (bytes32)
+    {
+        return hashCalls(scheme, destinationChainKey, Calls.encodeAll(calls));
+    }
+
+    /// @notice Whether this chain can compute `scheme` at all. False only for `Poseidon`.
+    function isComputable(Scheme scheme) internal pure returns (bool) {
+        return scheme != Scheme.Poseidon;
+    }
+
+    /* ================================== internals =============================== */
+
+    function _seed(bytes32 destinationChainKey) private pure returns (bytes32) {
+        return keccak256(abi.encode(destinationChainKey));
+    }
+
+    function _fold(bytes32 acc, bytes32 elementHash) private pure returns (bytes32) {
+        return keccak256(abi.encodePacked(acc, elementHash));
+    }
+
+    /// @dev Reverts for a scheme with no implementation here rather than falling back to a
+    ///      keccak256 digest the destination could never match.
+    function _hash(Scheme scheme, bytes memory data) private view returns (bytes32) {
+        if (scheme == Scheme.Keccak256) return keccak256(data);
+        if (scheme == Scheme.Sha256) return sha256(data);
+        if (scheme == Scheme.Blake2b256Scheme) return Blake2b256.hash(data);
+        revert SchemeNotComputable(scheme);
+    }
+}

package/contracts/messaging/DeliveryGas.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice The destination gas a message is sent with when its attributes name none, by what
+///         it does on arrival.
+/// @dev Measured cold on Forge's EVM with every binding's fixture (deploy/CHECKS.md §4), and
+///      held at least 10% above that by `ProviderDeliveryGasSpec`: a bootstrap that creates a
+///      conduit with no calls 442k to 497k, a report arriving home up to 123k on the bindings
+///      that carry one (2026-11-08).
+///      A bootstrap on a reporting chain also pays for the report's send. On EraVM a
+///      bootstrap's execution is about 385k to 389k; its pubdata is not measured. A gas
+///      attribute replaces these with no floor: a delivery short of gas reverts and is retried
+///      with more (provider-spec R1.5).
+library DeliveryGas {
+    uint256 internal constant BOOTSTRAP = 1_000_000;
+    uint256 internal constant REPORT = 250_000;
+    uint256 internal constant PAYLOAD = 200_000;
+}

package/contracts/messaging/Envelope.sol

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Call} from "./Call.sol";
+
+/// @title Envelope
+/// @notice The message bodies that cross between transceivers, each led by its kind.
+///
+/// @dev Tagged: once every transceiver both sends and receives bootstraps and reports, the
+///      direction no longer decides the shape, and decoding the wrong shape can misread
+///      silently. A decoder checks the tag before it reads anything else.
+///
+/// @dev Kinds start at 1, so a zero word, or the leading owner word of an untagged v1 body,
+///      is refused rather than read as a kind.
+///
+/// @dev `abi.encode`, not `encodePacked`, so no two messages share a byte string.
+library Envelope {
+    uint8 internal constant BOOTSTRAP = 1;
+    uint8 internal constant BOOTSTRAP_ELEMENTS = 2;
+    uint8 internal constant RECEIVER_REPORT = 3;
+
+    /// @dev Shorter than the one word that holds the kind.
+    error EnvelopeTooShort();
+    /// @dev The leading word is not a kind this protocol defines.
+    error UnknownEnvelopeKind(uint256 kind);
+    /// @dev A known kind, but not the one this decoder reads.
+    error UnexpectedEnvelopeKind(uint8 expected, uint8 got);
+
+    /// @notice The kind of `message`, reverting unless it is one this protocol defines.
+    function kindOf(bytes calldata message) internal pure returns (uint8) {
+        if (message.length < 32) revert EnvelopeTooShort();
+        uint256 kind = abi.decode(message[:32], (uint256));
+        if (kind == 0 || kind > RECEIVER_REPORT) revert UnknownEnvelopeKind(kind);
+        // forge-lint: disable-next-line(unsafe-typecast) bounded by the check above
+        return uint8(kind);
+    }
+
+    function _expect(bytes calldata message, uint8 kind) private pure {
+        uint8 got = kindOf(message);
+        if (got != kind) revert UnexpectedEnvelopeKind(kind, got);
+    }
+
+    /* ================================= bootstrap =============================== */
+
+    /// @notice The payload that stands a receiver up, credited to the transmitter it
+    ///         will answer to.
+    ///
+    /// @dev Calls, not a commitment: the transceiver creates and initializes the receiver and
+    ///      is never in the path again. A payload that should wait carries a self-call to
+    ///      `commit`.
+    ///
+    /// @dev Names the owner and salt, from which the destination derives the conduit address.
+    ///      A transceiver is shared, so nothing the bridge reports says who authorized the
+    ///      message.
+    ///
+    /// @dev Carries the transmitter the receiver will answer to. The origin transceiver sends
+    ///      only for the conduit `(owner, salt)` resolves to there, so the value is vouched for
+    ///      by the same authenticated message, and no destination needs another chain's
+    ///      address formula to derive it. A fixed word rather than `bytes`, which would add an
+    ///      offset and a length word to every bootstrap: an EVM address left-padded, or a
+    ///      32-byte key on a VM that has one.
+    function encodeBootstrap(address owner, bytes32 salt, bytes32 transmitter, Call[] memory calls)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        return abi.encode(BOOTSTRAP, owner, salt, transmitter, calls);
+    }
+
+    function decodeBootstrap(bytes calldata message)
+        internal
+        pure
+        returns (address owner, bytes32 salt, bytes32 transmitter, Call[] memory calls)
+    {
+        _expect(message, BOOTSTRAP);
+        (, owner, salt, transmitter, calls) = abi.decode(message, (uint8, address, bytes32, bytes32, Call[]));
+    }
+
+    /// @notice The same message, for a destination whose calls this chain cannot express.
+    /// @dev No Solidity decoder: the EVM transceiver refuses this kind, and a non-EVM
+    ///      transceiver decodes it in its own language.
+    function encodeBootstrapElements(address owner, bytes32 salt, bytes32 transmitter, bytes[] memory elements)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        return abi.encode(BOOTSTRAP_ELEMENTS, owner, salt, transmitter, elements);
+    }
+
+    /* ============================== receiver report ============================= */
+
+    /// @notice Where the destination created a transmitter's receiver.
+    ///
+    /// @dev Only chains whose addresses the home cannot recompute send this: zkSync and Tron,
+    ///      whose CREATE2 formulas differ, and non-EVM chains such as Starknet.
+    ///
+    /// @dev No request id: the chain comes from the authenticated origin and `(owner, salt)`
+    ///      is stated here, which identifies the conduit the home's transceiver forwards the
+    ///      report to. The conduit refuses a second report.
+    /// @param interop Canonical ERC-7930 bytes for the receiver on the reporting chain.
+    function encodeReceiverReport(address owner, bytes32 salt, bytes memory interop)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        return abi.encode(RECEIVER_REPORT, owner, salt, interop);
+    }
+
+    /// @notice Whether `message` is led by the report kind. Reads nothing past the kind.
+    function isReceiverReport(bytes memory message) internal pure returns (bool) {
+        // forge-lint: disable-next-line(unsafe-typecast) the leading word, after the length check
+        return message.length >= 32 && uint256(bytes32(message)) == RECEIVER_REPORT;
+    }
+
+    function decodeReceiverReport(bytes calldata message)
+        internal
+        pure
+        returns (address owner, bytes32 salt, bytes memory interop)
+    {
+        _expect(message, RECEIVER_REPORT);
+        (, owner, salt, interop) = abi.decode(message, (uint8, address, bytes32, bytes));
+    }
+}

package/contracts/messaging/Executor.sol

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Call} from "./Call.sol";
+
+/// @title Executor
+/// @notice Running a verified call array, and the policy that gates it.
+/// @dev Shared by every contract that runs payloads: a receiver runs what arrives, and a
+///      transmitter what its owner hands it. A transceiver runs none. No storage.
+abstract contract Executor {
+    error SelectorNotAllowed(address target, bytes4 selector);
+    /// @dev Carries the index of the element that failed.
+    error CallFailed(uint256 index, bytes reason);
+    /// @dev An empty array proves no intent, so it is refused rather than a successful no-op.
+    error EmptyExecution();
+
+    /// @notice Call policy. The default allows everything.
+    ///
+    /// @dev Open by default: conduits are full-power and answer to one owner, as its own account
+    ///      would, and anything that can deliver an authorized payload could forge a commitment
+    ///      as easily as a call. Failing closed would revert every payload, the bootstrap payload
+    ///      included, until overridden.
+    ///
+    /// @dev Merkle-verified calls are not in v1. If added, the model is Veda's
+    ///      `ManagerWithMerkleVerification`:
+    ///      https://github.com/Veda-Labs/boring-vault/blob/main/src/base/Roles/ManagerWithMerkleVerification.sol
+    function isAllowed(address, bytes4) public view virtual returns (bool) {
+        return true;
+    }
+
+    /// @notice Run the verified calls, in order, all or nothing.
+    /// @dev An approval covers the array as a unit, so a prefix must not stand. The failing
+    ///      call's revert reason is carried in `CallFailed`.
+    function _execute(Call[] memory calls) internal virtual {
+        uint256 len = calls.length;
+        for (uint256 i; i < len; ++i) {
+            Call memory c = calls[i];
+
+            // Under four bytes there is no selector (a value transfer or a fallback hit).
+            // `bytes4` of short data right-pads with zeros and would invent one.
+            // forge-lint: disable-next-line(unsafe-typecast) the first 4 bytes; length checked
+            bytes4 selector = c.data.length >= 4 ? bytes4(c.data) : bytes4(0);
+            if (!isAllowed(c.target, selector)) {
+                revert SelectorNotAllowed(c.target, selector);
+            }
+
+            // forge-lint: disable-next-line(arbitrary-send-eth,calls-loop) owner-approved calls, all or nothing
+            (bool ok, bytes memory reason) = c.target.call{value: c.value}(c.data);
+            if (!ok) revert CallFailed(i, reason);
+        }
+    }
+}

package/contracts/messaging/IErc7786.sol

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.4;
+
+/// @title IErc7786
+/// @notice ERC-7786's two interfaces, vendored: the send surface `TransmitterBase` implements
+///         and the receive surface `ReceiverBase` implements.
+///
+/// @dev Copied from `@openzeppelin/contracts/interfaces/draft-IERC7786.sol` at v5.5.0;
+///      only this header and the file name differ. Vendored because the ERC is a draft and
+///      these selectors and the event topic are this protocol's ABI: an upstream change becomes
+///      a reviewed edit rather than a side effect of a dependency bump.
+///
+/// @dev OpenZeppelin's types and these are distinct to Solidity. Integrators import from
+///      here; a binding whose SDK returns OpenZeppelin's variant casts through the address.
+
+/// @dev Interface for ERC-7786 source gateways.
+interface IERC7786GatewaySource {
+    /// @dev Emitted when a message is created. If `sendId` is zero, no further processing is
+    ///      necessary. If `sendId` is not zero, then further (gateway specific, and
+    ///      non-standardized) action is required.
+    event MessageSent(
+        bytes32 indexed sendId,
+        bytes sender, // Binary Interoperable Address
+        bytes recipient, // Binary Interoperable Address
+        bytes payload,
+        uint256 value,
+        bytes[] attributes
+    );
+
+    /// @dev Thrown when a message creation fails because of an unsupported attribute.
+    error UnsupportedAttribute(bytes4 selector);
+
+    /// @dev Whether an attribute is supported or not.
+    function supportsAttribute(bytes4 selector) external view returns (bool);
+
+    /// @dev Endpoint for creating a new message. If the message requires further (gateway
+    ///      specific) processing before it can be sent to the destination chain, then a
+    ///      non-zero `sendId` must be returned. Otherwise, the message MUST be sent and this
+    ///      function must return 0.
+    ///
+    ///      MUST emit a {MessageSent} event.
+    ///
+    ///      If any of the `attributes` is not supported, this function SHOULD revert with an
+    ///      {UnsupportedAttribute} error. Other errors SHOULD revert with errors not
+    ///      specified in ERC-7786.
+    function sendMessage(
+        bytes calldata recipient, // Binary Interoperable Address
+        bytes calldata payload,
+        bytes[] calldata attributes
+    )
+        external
+        payable
+        returns (bytes32 sendId);
+}
+
+/// @dev Interface for the ERC-7786 client contract (receiver).
+interface IERC7786Recipient {
+    /// @dev Endpoint for receiving a cross-chain message. May be called directly by the
+    ///      gateway.
+    function receiveMessage(
+        bytes32 receiveId,
+        bytes calldata sender, // Binary Interoperable Address
+        bytes calldata payload
+    )
+        external
+        payable
+        returns (bytes4);
+}

package/contracts/messaging/Payload.sol

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Call} from "./Call.sol";
+import {Erc7930} from "../addressing/Erc7930.sol";
+
+/// @title Payload
+/// @notice The wire encoding of a call array, in the one shape its destination speaks.
+///
+/// @dev An EVM destination receives `Call[]`; every other VM receives opaque `bytes[]` in its
+///      own call encoding. The sender picks by destination and the receiver decodes the one
+///      shape its VM implies, so there is no form tag.
+///
+/// @dev That relies on no path sending opaque elements to an EVM receiver, not on
+///      `abi.decode` rejecting the wrong shape. A destination that could accept both needs the
+///      tag back.
+///
+/// @dev Both forms of one payload commit to one hash: `Commitment` folds per-element hashes
+///      and `Calls.encode` produces exactly the opaque element.
+library Payload {
+    /* ============================== EVM destinations ============================ */
+
+    /// @notice Wire bytes for an EVM destination.
+    function encodeCalls(Call[] memory calls) internal pure returns (bytes memory) {
+        return abi.encode(calls);
+    }
+
+    /// @notice Decode a payload that arrived on an EVM chain. Reverts on anything that is not
+    ///         `Call[]`.
+    function decodeCalls(bytes calldata wire) internal pure returns (Call[] memory) {
+        return abi.decode(wire, (Call[]));
+    }
+
+    /// @notice `decodeCalls`, for a wire already in memory.
+    /// @dev Separate because Solidity will not overload on data location, and a receiver's
+    ///      payload stays in calldata rather than paying a copy on every delivery.
+    function decodeCallsFromMemory(bytes memory wire) internal pure returns (Call[] memory) {
+        return abi.decode(wire, (Call[]));
+    }
+
+    /* ============================ non-EVM destinations ========================== */
+
+    /// @notice Wire bytes for a destination whose calls this chain cannot express.
+    /// @dev Each element is that VM's own call encoding (a Solana instruction with its
+    ///      accounts, a Starknet `(to, selector, calldata)`, an Aptos entry function), unparsed
+    ///      here.
+    function encodeElements(bytes[] memory elements) internal pure returns (bytes memory) {
+        return abi.encode(elements);
+    }
+
+    function decodeElements(bytes calldata wire) internal pure returns (bytes[] memory) {
+        return abi.decode(wire, (bytes[]));
+    }
+
+    /// @notice `decodeElements`, for a wire already in memory.
+    function decodeElementsFromMemory(bytes memory wire) internal pure returns (bytes[] memory) {
+        return abi.decode(wire, (bytes[]));
+    }
+
+    /* ================================ bootstrap ================================= */
+
+    /// @notice The plain bootstrap payload: the destination's ERC-7930 chain identifier, and
+    ///         the body the receiver runs on creation, in that destination's one form.
+    /// @dev The destination travels inside the payload because `bootstrap` takes no other
+    ///      argument naming it.
+    function encodeBootstrap(bytes memory destinationChainIdentifier, bytes memory body)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        return abi.encode(destinationChainIdentifier, body);
+    }
+
+    function decodeBootstrap(bytes calldata payload)
+        internal
+        pure
+        returns (bytes memory destinationChainIdentifier, bytes memory body)
+    {
+        return abi.decode(payload, (bytes, bytes));
+    }
+
+    /* ================================ selection ================================= */
+
+    /// @notice Whether a destination takes the typed form.
+    /// @dev Takes the identifier, not the chainKey, which is a hash and cannot be asked its
+    ///      chain type.
+    function isTypedDestination(bytes memory chainIdentifier) internal pure returns (bool) {
+        return Erc7930.parseStrict(chainIdentifier).chainType == Erc7930.CT_EIP155;
+    }
+}

package/contracts/messaging/Roles.sol

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {
+    AccessControlEnumerableUpgradeable
+} from "@openzeppelin/contracts-upgradeable/access/extensions/AccessControlEnumerableUpgradeable.sol";
+import {AccessControlUpgradeable} from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
+import {IAccessControl} from "@openzeppelin/contracts/access/IAccessControl.sol";
+
+/// @title Roles
+/// @notice Which transports may carry this contract's messages, in either direction.
+///
+/// @dev `GATEWAY_ROLE` names addresses, not powers: a gateway can neither configure a contract
+///      nor grant anything. Configuration is `Ownable` on the transceiver, except bootstrap fees,
+///      which an operator the owner names may also set. Sending and receiving check
+///      the same role, so a contract cannot accept deliveries from one transport while sending
+///      through another. `ReceiverBase` inherits this directly: it never sends, but the role
+///      guards its external `receiveMessage`.
+///
+/// @dev Not enumerable here: a transceiver's members are fixed at initialization, each grant
+///      emits `RoleGranted`, and enumeration would cost every transceiver a kilobyte it does
+///      not have under EIP-170 (#29). Conduits, whose receivers can revoke, add it through
+///      `RolesEnumerable`.
+abstract contract Roles is AccessControlUpgradeable {
+    /// @notice May deliver a message to this contract and carry one out of it. The only role.
+    /// @dev Namespaced so a provider SDK's own role of the same name cannot share its members.
+    bytes32 public constant GATEWAY_ROLE = keccak256("crossecute.role.GATEWAY");
+
+    /// @dev The caller of `grantRole` was not this contract.
+    error GrantNotFromSelf(address caller);
+
+    /// @notice Grant a role from this contract's own bootstrap payload, so an owner's first
+    ///         payload can name its conduit's gateway. Closes when initialization does.
+    ///
+    /// @dev `onlyInitializing` replaces OZ's admin gate. No role has an admin, so after arming
+    ///      no caller can add a member: not the owner, the governor, the creating transceiver, or a
+    ///      member. The flag stays set while `__ReceiverBase_init` runs the payload, so every
+    ///      contract the payload reaches would be inside the window too; only a self-call from
+    ///      `_execute` is accepted (#68).
+    ///
+    /// @dev `public` because it overrides OZ's `grantRole`; a separate entry point would leave
+    ///      the inherited one reachable.
+    function grantRole(bytes32 role, address conduit) public virtual override onlyInitializing {
+        if (msg.sender != address(this)) revert GrantNotFromSelf(msg.sender);
+        _grantRole(role, conduit);
+    }
+
+    /// @notice An initializer's own grant, such as the provider endpoint it names as a gateway.
+    function _grantInitialRole(bytes32 role, address conduit) internal onlyInitializing {
+        _grantRole(role, conduit);
+    }
+
+    /// @notice Whether `conduit` holds `role`.
+    /// @dev Re-declared so an override below names one base.
+    function hasRole(bytes32 role, address conduit) public view virtual override returns (bool) {
+        return super.hasRole(role, conduit);
+    }
+}
+
+/// @title RolesEnumerable
+/// @notice `Roles`, with the member set readable on-chain, for conduits: a receiver can drop a
+///         gateway through `revokeGateway`, so what remains is worth reading directly.
+/// @dev `AccessControlEnumerableUpgradeable` compiles at `paris` only through OZ 5.4, since
+///      5.5's `Arrays` uses `mcopy`; a bump past 5.4 breaks this inheritance first (README,
+///      Assumptions).
+abstract contract RolesEnumerable is Roles, AccessControlEnumerableUpgradeable {
+    function grantRole(bytes32 role, address conduit)
+        public
+        virtual
+        override(Roles, AccessControlUpgradeable, IAccessControl)
+        onlyInitializing
+    {
+        super.grantRole(role, conduit);
+    }
+
+    function hasRole(bytes32 role, address conduit)
+        public
+        view
+        virtual
+        override(Roles, AccessControlUpgradeable, IAccessControl)
+        returns (bool)
+    {
+        return super.hasRole(role, conduit);
+    }
+
+    function _grantRole(bytes32 role, address conduit)
+        internal
+        virtual
+        override(AccessControlUpgradeable, AccessControlEnumerableUpgradeable)
+        returns (bool)
+    {
+        return super._grantRole(role, conduit);
+    }
+
+    function _revokeRole(bytes32 role, address conduit)
+        internal
+        virtual
+        override(AccessControlUpgradeable, AccessControlEnumerableUpgradeable)
+        returns (bool)
+    {
+        return super._revokeRole(role, conduit);
+    }
+
+    function supportsInterface(bytes4 interfaceId)
+        public
+        view
+        virtual
+        override(AccessControlUpgradeable, AccessControlEnumerableUpgradeable)
+        returns (bool)
+    {
+        return super.supportsInterface(interfaceId);
+    }
+}