@crossecute/protocol 0.0.0 → 0.1.1

package/contracts/addressing/ChainKey.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Erc7930} from "./Erc7930.sol";
+
+/// @title ChainKey
+/// @notice The protocol's single name for a destination: keccak256 of the canonical
+///         ERC-7930 chain identifier.
+///
+/// @dev For eip155 nobody stores one: the source derives the destination's key from its
+///      `uint256` chain id and the destination derives its own from `block.chainid`.
+///
+/// @dev It is both the commitment domain, folded into `Commitment.hashCalls` and recomputed
+///      by the receiver with no configuration, and the key every routing table is indexed by
+///      (routes and counterparts on a transceiver, chain data in the registry). A raw chain
+///      id would serve the first only on EVM destinations.
+library ChainKey {
+    /// @notice The key for an eip155 chain. Pure: no storage, no registry, no round trip.
+    function forEvm(uint256 chainId) internal pure returns (bytes32) {
+        return keccak256(Erc7930.encodeEvmChain(chainId));
+    }
+
+    /// @notice This chain's own key, as the destination-side receiver computes it.
+    /// @dev The counterpart to `forEvm`, and the reason the commitment domain needs no
+    ///      configuration on the destination. A non-EVM receiver overrides its equivalent
+    ///      with a literal for its own chain identifier: a property of the deployment
+    ///      target, not something an operator sets.
+    function local() internal view returns (bytes32) {
+        return forEvm(block.chainid);
+    }
+
+    /// @notice The key for any chain, from an ERC-7930 envelope.
+    /// @dev Accepts a conduit envelope as well as a bare chain identifier;
+    ///      `toChainIdentifier` reduces it, so every address on a chain yields one key.
+    ///      `parseStrict` runs inside, so a non-canonical framing reverts here rather
+    ///      than becoming a key nothing else can reproduce.
+    function fromIdentifier(bytes memory identifier) internal pure returns (bytes32) {
+        return fromParsed(Erc7930.parseStrict(identifier));
+    }
+
+    /// @notice `fromIdentifier`, for an envelope `parseStrict` has already read.
+    function fromParsed(Erc7930.Interop memory io) internal pure returns (bytes32) {
+        return keccak256(Erc7930.encodeChainId(io.chainType, io.chainRef));
+    }
+}

package/contracts/addressing/ChainType.sol

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @title ChainType
+/// @notice The single allocation table for ERC-7930 ChainType values.
+///
+/// @dev Why this is one file. A ChainType is baked into every envelope and registry keys are
+///      `keccak256(envelope)`, so two files each picking a provisional value is how you get a
+///      silent collision that only surfaces as two chains sharing a key.
+///
+/// @dev Onboarding a chain type is two steps, and allocating here is only the first.
+///      `Erc7930.parseStrict` reads the field as an opaque `uint16` and validates nothing
+///      against this table, so a value's presence here buys collision avoidance and nothing
+///      else. The profile's canonicity rule must be written into `parseStrict` alongside it,
+///      or two encodings of one address hash to two registry keys with no error anywhere.
+///      See "Adding a chain type" in the README.
+///
+/// @dev Assigned values come from the casa namespace registry's CAIP-350 profiles.
+///      Provisional values are local, live at or above `PROVISIONAL_FLOOR`, and face a
+///      re-keying migration if casa later publishes a different value for them. Casa
+///      allocates upward from 0x0000, so 0xFF00..0xFFFF makes a collision implausible.
+library ChainType {
+    /* ================================ assigned ================================= */
+
+    uint16 internal constant EIP155 = 0x0000; // eip155/caip350.md
+    uint16 internal constant BIP122 = 0x0001; // bip122/caip350.md
+    uint16 internal constant SOLANA = 0x0002; // solana/caip350.md
+    uint16 internal constant STARKNET = 0x0003; // starknet/caip350.md
+
+    /* =============================== provisional =============================== */
+
+    /// @dev Anything at or above this is locally assigned and subject to re-keying.
+    uint16 internal constant PROVISIONAL_FLOOR = 0xFF00;
+
+    /// @dev Aptos-Move: 32-byte AccountAddress, SHA3-256 derivation. Movement shares
+    ///      this profile and is distinguished by ChainReference, not ChainType.
+    uint16 internal constant APTOS = 0xFF01;
+    /// @dev Sui-Move: 32-byte address/ObjectID, BLAKE2b-256 derivation.
+    uint16 internal constant SUI = 0xFF02;
+    /// @dev Cosmos/CosmWasm: 32-byte canonical address (20 on forked wasmd chains).
+    ///      `cosmos/` has a CAIP-2 profile only.
+    uint16 internal constant COSMOS = 0xFF03;
+    /// @dev NEAR: named accounts are variable-length UTF-8, implicit accounts are 32
+    ///      bytes, eth-implicit are 20. `near/` has a CAIP-2 profile only.
+    uint16 internal constant NEAR = 0xFF04;
+
+    function isProvisional(uint16 chainType) internal pure returns (bool) {
+        return chainType >= PROVISIONAL_FLOOR;
+    }
+}

package/contracts/addressing/Erc7930.sol

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ChainType} from "./ChainType.sol";
+
+/// @title Erc7930
+/// @notice Encoding, strict parsing, and key derivation for ERC-7930 Interoperable
+///         Addresses: the binary envelope that binds a chain identity to an address.
+///
+/// @dev Layout (all lengths in bytes):
+///        ┌─────────┬───────────┬──────────────────────┬────────────────┬───────────────┬─────────┐
+///        │ Version │ ChainType │ ChainReferenceLength │ ChainReference │ AddressLength │ Address │
+///        │    2    │     2     │          1           │    variable    │       1       │variable │
+///        └─────────┴───────────┴──────────────────────┴────────────────┴───────────────┴─────────┘
+///
+///      This solves the arbitrary-length problem structurally: a NEAR named account,
+///      a 57-byte Cardano address, a TON workchain+account_id, and a 20-byte EVM
+///      address are all the same shape. The envelope carries the length, so no bespoke
+///      Form/kind discriminant is needed.
+///
+/// @dev Canonicity is the whole game here. ERC-7930's own Security Considerations warn
+///      implementers using these as mapping keys to check each CAIP-350 profile for
+///      non-canonical encodings. Two byte strings that mean the same address but differ
+///      by one byte hash to different keys: a silent split-brain in any registry.
+///      This library therefore rejects non-minimal chain references (`0x0001` for
+///      chain 1 is invalid; `0x01` is the only valid form) and rejects trailing bytes.
+///      Never accept a raw interop blob from a remote caller without `parseStrict`.
+///
+/// @dev The rules are per profile, and a chain type with no rule is accepted. `chainType`
+///      is read as an opaque `uint16` and never checked against `ChainType.sol`, so an
+///      unallocated value parses and registers. It simply arrives with no canonicity
+///      condition attached: both `0x00cafe` and `0xcafe` would pass as chain references
+///      for the same chain and hash to two different keys.
+///
+///      **Adding a `ChainType` constant does not close that.** The rule has to be written
+///      into `parseStrict` below, beside the eip155 and starknet cases. It is the one step of
+///      onboarding a chain that nothing here will remind you about: see "Adding a chain type"
+///      in the README. `test/UnknownChainType.t.sol` pins the current behaviour.
+library Erc7930 {
+    uint16 internal constant VERSION_1 = 0x0001;
+
+    /* --------------------------- CAIP-350 chain types --------------------------- */
+    // Aliases into `ChainType`, which is the one allocation table for the repo.
+    uint16 internal constant CT_EIP155 = ChainType.EIP155;
+    uint16 internal constant CT_STARKNET = ChainType.STARKNET;
+
+    /// @dev Starknet addresses are 32-byte field elements, zero-padded. Unlike eip155,
+    ///      leading zeros are required, so minimality must not be enforced on them.
+    uint256 internal constant STARKNET_ADDRESS_BYTES = 32;
+
+    error BadVersion();
+    error BadLength();
+    error NonMinimalChainRef();
+    error TrailingBytes();
+    error EmptyEnvelope();
+    error NotEvm();
+    error BadStarknetAddressLength();
+
+    struct Interop {
+        uint16 version;
+        uint16 chainType;
+        bytes chainRef;
+        bytes addr;
+    }
+
+    /* ================================ encoding ================================ */
+
+    /// @notice Build an interoperable address from parts.
+    /// @dev `chainRef` must already be minimally encoded per its CAIP-350 profile.
+    ///      Use `encodeEvm` for eip155 rather than encoding the chain id by hand.
+    function encode(uint16 chainType, bytes memory chainRef, bytes memory addr) internal pure returns (bytes memory) {
+        if (chainRef.length > 255 || addr.length > 255) revert BadLength();
+        if (chainRef.length == 0 && addr.length == 0) revert EmptyEnvelope();
+        // forge-lint: disable-next-line(encode-packed-collision,unsafe-typecast) lengths checked <= 255 above, and each is prefixed
+        return abi.encodePacked(VERSION_1, chainType, uint8(chainRef.length), chainRef, uint8(addr.length), addr);
+    }
+
+    /// @notice eip155 interoperable address. ChainReference is the chain id as a
+    ///         Minimal big-endian integer: chain 1 -> 0x01, Base (8453) -> 0x2105.
+    function encodeEvm(uint256 chainId, address a) internal pure returns (bytes memory) {
+        return encode(CT_EIP155, minimalBigEndian(chainId), abi.encodePacked(a));
+    }
+
+    /// @notice A Chain Identifier: an interop address with a zero-length Address.
+    ///         Identifies a chain rather than an account on it.
+    function encodeChainId(uint16 chainType, bytes memory chainRef) internal pure returns (bytes memory) {
+        return encode(chainType, chainRef, "");
+    }
+
+    function encodeEvmChain(uint256 chainId) internal pure returns (bytes memory) {
+        return encodeChainId(CT_EIP155, minimalBigEndian(chainId));
+    }
+
+    /* ================================ parsing ================================= */
+
+    /// @notice Parse and fully validate. Reverts on anything non-canonical.
+    /// @dev Checks: version, declared lengths against actual, no trailing bytes,
+    ///      not both-empty, and minimal chain-reference encoding for eip155.
+    function parseStrict(bytes memory raw) internal pure returns (Interop memory io) {
+        if (raw.length < 6) revert BadLength();
+
+        io.version = (uint16(uint8(raw[0])) << 8) | uint16(uint8(raw[1]));
+        if (io.version != VERSION_1) revert BadVersion();
+        io.chainType = (uint16(uint8(raw[2])) << 8) | uint16(uint8(raw[3]));
+
+        uint256 crLen = uint8(raw[4]);
+        if (raw.length < 5 + crLen + 1) revert BadLength();
+        io.chainRef = _slice(raw, 5, crLen);
+
+        uint256 alPos = 5 + crLen;
+        uint256 aLen = uint8(raw[alPos]);
+        if (raw.length != alPos + 1 + aLen) revert TrailingBytes();
+        io.addr = _slice(raw, alPos + 1, aLen);
+
+        if (crLen == 0 && aLen == 0) revert EmptyEnvelope();
+
+        // eip155: chain reference is a minimal big-endian integer. A leading zero byte
+        // means two distinct encodings of the same chain, and therefore two keys.
+        if (io.chainType == CT_EIP155 && crLen > 0) {
+            if (io.chainRef[0] == 0x00) revert NonMinimalChainRef();
+            if (crLen > 32) revert BadLength();
+        }
+
+        // starknet: the opposite rule. Addresses are fixed-width 32-byte field
+        // elements with leading zeros, so width is the canonicity condition here. Chain
+        // references are the UTF-8 chain ID string ("SN_MAIN"), not an integer, so the
+        // eip155 minimality rule would reject every valid one.
+        // The value-range check (< ADDR_BOUND) is not a structural property and lives
+        // in StarknetDerive, wired in as a per-chain validator.
+        if (io.chainType == CT_STARKNET && aLen != 0) {
+            if (aLen != STARKNET_ADDRESS_BYTES) revert BadStarknetAddressLength();
+        }
+    }
+
+    /// @notice The EVM chain id an `eip155` address names; `encodeEvmChain`'s inverse.
+    /// @dev `parseStrict` has already bounded the reference to a minimal 1 to 32 bytes.
+    function evmChainId(Interop memory io) internal pure returns (uint256 id) {
+        if (io.chainType != CT_EIP155 || io.chainRef.length == 0) revert NotEvm();
+        for (uint256 i; i < io.chainRef.length; ++i) {
+            id = (id << 8) | uint8(io.chainRef[i]);
+        }
+    }
+
+    /// @notice The Chain Identifier form of an interop address: same chain, no account.
+    /// @dev This is what makes `chainKey` stable across every address on a chain.
+    function toChainIdentifier(bytes memory raw) internal pure returns (bytes memory) {
+        Interop memory io = parseStrict(raw);
+        return encodeChainId(io.chainType, io.chainRef);
+    }
+
+    /* ================================== keys =================================== */
+
+    /// @notice Grouping key for "which chain is this on", independent of the account.
+    function chainKey(bytes memory raw) internal pure returns (bytes32) {
+        return keccak256(toChainIdentifier(raw));
+    }
+
+    /* ================================ helpers ================================== */
+
+    /// @notice True if this envelope names an EVM chain with a 20-byte address, i.e.
+    ///         the registry can resolve it locally with CREATE2 instead of a round trip.
+    function isEvmAccount(Interop memory io) internal pure returns (bool) {
+        return io.chainType == CT_EIP155 && io.addr.length == 20 && io.chainRef.length > 0;
+    }
+
+    function toAddress(Interop memory io) internal pure returns (address a) {
+        if (!isEvmAccount(io)) revert NotEvm();
+        bytes memory b = io.addr;
+        assembly {
+            a := shr(96, mload(add(b, 32)))
+        }
+    }
+
+    /// @notice Minimal big-endian encoding of an integer: the eip155 chain-reference
+    ///         rule: chain 1 is `0x01`, Base (8453) is `0x2105`, and a leading zero byte
+    ///         is invalid.
+    ///
+    /// @dev It lives here because it is an encoding rule, not a derivation. Putting it in
+    ///      the address-derivation library would make `addressing` import `derivation`
+    ///      while every deriver imports `addressing` back: a cycle between the two
+    ///      folders over one integer helper. Canonicity is this library's
+    ///      responsibility, so the rule that decides it belongs next to `parseStrict`,
+    ///      which is what rejects violations of it.
+    ///
+    /// @dev `AddressDerive` uses it too, for the RLP nonce in a CREATE derivation. That
+    ///      is a different rule reached by the same encoding, and it had its own private
+    ///      copy of this body until the two were merged here. `derivation` imports
+    ///      `addressing`, which is the direction this comment always said was open.
+    function minimalBigEndian(uint256 x) internal pure returns (bytes memory out) {
+        uint256 len;
+        uint256 t = x;
+        while (t != 0) {
+            ++len;
+            t >>= 8;
+        }
+        out = new bytes(len);
+        for (uint256 i; i < len; ++i) {
+            // forge-lint: disable-next-line(unsafe-typecast) one byte of x
+            out[len - 1 - i] = bytes1(uint8(x >> (8 * i)));
+        }
+    }
+
+    function _slice(bytes memory src, uint256 start, uint256 len) private pure returns (bytes memory out) {
+        out = new bytes(len);
+        for (uint256 i; i < len; ++i) {
+            out[i] = src[start + i];
+        }
+    }
+}

package/contracts/addressing/Move.sol

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ChainType} from "./ChainType.sol";
+import {Erc7930} from "./Erc7930.sol";
+
+/// @title Move
+/// @notice Reference extension for Move chains (Aptos, Movement, Sui).
+///
+/// @dev Why this exists. Two gaps the ERC-7930 envelope cannot close on its own:
+///
+///      1. No assigned chain type. As of writing, the casa namespace registry defines
+///         CAIP-350 profiles for exactly four namespaces: eip155 (0x0000), bip122
+///         (0x0001), solana (0x0002), starknet (0x0003). `aptos/` and `sui/` have
+///         CAIP-2 profiles only: no CAIP-10, no CAIP-350. There is therefore no
+///         standard ChainType and no standard address serialization for Move chains.
+///         The values below are provisional. See the migration note.
+///
+///      2. A Move module has no address. A transceiver on Aptos is
+///         `account_address::module_name`; on Sui it is a function in a package.
+///         The 32-byte account or package ID fits the envelope's Address field, but
+///         the qualified name does not, and no amount of length-prefixing changes
+///         that: it is a different kind of thing, not a longer address.
+///
+/// @dev Design: separation of address and qualification.
+///      The 7930 Address field carries only the 32-byte account/package ID, which is
+///      almost certainly what a future CAIP-350 profile will specify. Everything else
+/// (module name, function name, type arguments, Sui package lineage) lives in
+///      a MoveQualifier attached alongside. When casa assigns real chain types, only
+///      the ChainType constants change; the qualifier structure is untouched.
+///
+/// @dev Migration. Registry keys are `keccak256(envelope)`, and the envelope contains
+///      the ChainType. If casa assigns Aptos or Sui a value different from the
+///      provisional ones here, every id for those chains changes. That is a
+///      re-keying migration across the registry, not a config edit. Provisional types
+///      are deliberately confined to the 0xFF00..0xFFFF range so `isProvisional` can
+///      flag affected refs, and so a collision with a casa assignment (which allocates
+///      upward from 0x0000) is implausible rather than merely unlikely.
+library Move {
+    /* ========================= provisional chain types ======================== */
+
+    /// @dev All values below are allocated in `ChainType`, which is the one table for
+    ///      the whole repo. These are aliases kept for readability at the call sites.
+    uint16 internal constant PROVISIONAL_FLOOR = ChainType.PROVISIONAL_FLOOR;
+
+    /// @dev Aptos-Move address semantics: 32-byte AccountAddress, SHA3-256 derivation.
+    ///      Movement shares this profile and is distinguished by ChainReference, not
+    ///      by ChainType: the address format is identical, which is the same basis
+    ///      Casa uses to group networks under one namespace.
+    uint16 internal constant CT_PROV_APTOS = ChainType.APTOS;
+
+    /// @dev Sui-Move: 32-byte address/ObjectID, BLAKE2b-256 derivation.
+    uint16 internal constant CT_PROV_SUI = ChainType.SUI;
+
+    /// @dev Chain references (UTF-8, following the Starknet profile's convention of
+    ///      using the CAIP-2 reference string directly rather than an integer).
+    bytes internal constant REF_APTOS_MAINNET = "mainnet";
+    bytes internal constant REF_MOVEMENT_MAINNET = "movement-mainnet";
+    bytes internal constant REF_SUI_MAINNET = "mainnet";
+
+    uint256 internal constant MOVE_ADDRESS_BYTES = 32;
+
+    function isProvisional(uint16 chainType) internal pure returns (bool) {
+        return chainType >= PROVISIONAL_FLOOR;
+    }
+
+    function isMoveChain(uint16 chainType) internal pure returns (bool) {
+        return chainType == CT_PROV_APTOS || chainType == CT_PROV_SUI;
+    }
+
+    /* ============================== qualification ============================= */
+
+    enum MoveKind {
+        Unset,
+        /// A plain account address. No module, no function.
+        Account,
+        /// An object (Aptos Object<T>, Sui ObjectID). No module, no function.
+        Object,
+        /// A published package (Sui) or the publishing account (Aptos).
+        Package,
+        /// `address::module_name`.
+        Module,
+        /// `address::module_name::function_name`, optionally with type arguments.
+        /// This is what a transceiver call target actually is.
+        Entry
+    }
+
+    /// @notice Everything about a Move reference that is not the 32-byte address.
+    struct MoveQualifier {
+        MoveKind kind;
+        /// Move Identifier. Empty unless kind is Module or Entry.
+        string moduleName;
+        /// Move Identifier. Empty unless kind is Entry.
+        string functionName;
+        /// BCS-serialized `Vec<TypeTag>`. Empty if the entry takes no type arguments.
+        /// Opaque here: serialize off-chain; do not build BCS in Solidity.
+        bytes typeArgs;
+        /// Sui only. A package upgrade mints a new package ID, but types retain the
+        /// Original package ID in their StructTag while calls target the latest. A
+        /// single id would silently mean the wrong thing after the first upgrade, so
+        /// the envelope address holds the call target (latest) and this holds type
+        /// identity (original). Zero when not applicable.
+        bytes32 originalPackageId;
+        /// Sui only. A shared-object reference is `(ObjectID, initial_shared_version)`;
+        /// the ID alone is not enough to construct a call. Zero if not shared.
+        uint64 initialSharedVersion;
+    }
+
+    error BadKind();
+    error ModuleNameRequired();
+    error ModuleNameForbidden();
+    error FunctionNameRequired();
+    error FunctionNameForbidden();
+    error TypeArgsForbidden();
+    error BadIdentifier();
+    error SuiOnlyField();
+    error BadMoveAddressLength();
+    error NotMoveChain();
+
+    /// @notice Commitment over a qualifier, for inclusion in a signed payload.
+    /// @dev abi.encode (not encodePacked): fixed field framing, so no two distinct
+    ///      qualifiers can produce the same preimage by shifting bytes between the
+    ///      variable-length fields.
+    function hash(MoveQualifier memory q) internal pure returns (bytes32) {
+        return keccak256(
+            abi.encode(
+                uint8(q.kind), q.moduleName, q.functionName, q.typeArgs, q.originalPackageId, q.initialSharedVersion
+            )
+        );
+    }
+
+    /// @notice Structural validation of a qualifier against its chain.
+    function validate(MoveQualifier memory q, uint16 chainType) internal pure {
+        if (!isMoveChain(chainType)) revert NotMoveChain();
+        if (q.kind == MoveKind.Unset) revert BadKind();
+
+        bool wantsModule = (q.kind == MoveKind.Module || q.kind == MoveKind.Entry);
+        bool wantsFunction = (q.kind == MoveKind.Entry);
+
+        if (wantsModule) {
+            if (bytes(q.moduleName).length == 0) revert ModuleNameRequired();
+            requireIdentifier(q.moduleName);
+        } else if (bytes(q.moduleName).length != 0) {
+            revert ModuleNameForbidden();
+        }
+
+        if (wantsFunction) {
+            if (bytes(q.functionName).length == 0) revert FunctionNameRequired();
+            requireIdentifier(q.functionName);
+        } else if (bytes(q.functionName).length != 0) {
+            revert FunctionNameForbidden();
+        }
+
+        // Type arguments attach to a call, not to a bare address or module.
+        if (!wantsFunction && q.typeArgs.length != 0) revert TypeArgsForbidden();
+
+        // Sui-only fields must be zero on Aptos, or the same logical reference could
+        // be expressed two ways and hash to two different commitments.
+        if (chainType != CT_PROV_SUI) {
+            if (q.originalPackageId != bytes32(0)) revert SuiOnlyField();
+            if (q.initialSharedVersion != 0) revert SuiOnlyField();
+        }
+    }
+
+    /// @notice Move Identifier charset: ASCII, first character a letter or underscore,
+    ///         remainder alphanumeric or underscore.
+    /// @dev This is a canonicity guard, not decoration. Without it a module name could
+    ///      carry whitespace, a homoglyph, or a trailing NUL and still produce a
+    ///      well-formed commitment that no Move VM will ever resolve.
+    function requireIdentifier(string memory s) internal pure {
+        bytes memory b = bytes(s);
+        uint256 n = b.length;
+        if (n == 0 || n > 255) revert BadIdentifier();
+
+        bytes1 c0 = b[0];
+        bool okFirst = (c0 >= 0x41 && c0 <= 0x5a) // A-Z
+            || (c0 >= 0x61 && c0 <= 0x7a) // a-z
+            || c0 == 0x5f; // _
+        if (!okFirst) revert BadIdentifier();
+
+        for (uint256 i = 1; i < n; ++i) {
+            bytes1 c = b[i];
+            bool okRest = (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || (c >= 0x30 && c <= 0x39) // 0-9
+                || c == 0x5f;
+            if (!okRest) revert BadIdentifier();
+        }
+    }
+
+    /* ================================ encoding ================================ */
+
+    /// @notice Build the 7930 envelope for a Move address. The address field holds the
+    ///         32-byte account/package ID and nothing else.
+    function encodeMove(uint16 chainType, bytes memory chainRef, bytes32 addr) internal pure returns (bytes memory) {
+        if (!isMoveChain(chainType)) revert NotMoveChain();
+        return Erc7930.encode(chainType, chainRef, abi.encodePacked(addr));
+    }
+
+    function encodeAptos(bytes memory chainRef, bytes32 addr) internal pure returns (bytes memory) {
+        return encodeMove(CT_PROV_APTOS, chainRef, addr);
+    }
+
+    function encodeSui(bytes memory chainRef, bytes32 addr) internal pure returns (bytes memory) {
+        return encodeMove(CT_PROV_SUI, chainRef, addr);
+    }
+
+    function toAddress(bytes memory addrField) internal pure returns (bytes32 v) {
+        if (addrField.length != MOVE_ADDRESS_BYTES) revert BadMoveAddressLength();
+        assembly {
+            v := mload(add(addrField, 32))
+        }
+    }
+}

package/contracts/conduit/Conduits.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Create2} from "@openzeppelin/contracts/utils/Create2.sol";
+import {IProxy} from "./Proxy.sol";
+import {ProxyInitCode} from "./ProxyInitCode.sol";
+
+/// @title Conduits
+/// @notice The steps every contract that creates conduits takes, in this order: refuse an
+///         occupied address, deploy `Proxy` by CREATE2, check it landed at the predicted
+///         address, then arm and lock it.
+///
+/// @dev Separate functions rather than one, so a creator on a chain that deploys differently
+///      (zkSync) replaces only `deploy`, and so a creator builds its initializer only after the
+///      address check, which then reports a mismatch before anything the initializer reads.
+library Conduits {
+    error ConduitExists(address owner, bytes32 salt, address conduit);
+    /// @dev The prediction and the deployment disagree: a variant on a diverging chain changed
+    ///      one and not the other.
+    error ConduitAddressMismatch(address predicted, address deployed);
+
+    function requireVacant(address conduit, address owner, bytes32 salt) internal view {
+        if (conduit.code.length != 0) revert ConduitExists(owner, salt, conduit);
+    }
+
+    /// @notice CREATE2 of `Proxy`'s initcode, read from the contract `ProxyInitCode`
+    ///         stored it in.
+    function deploy(bytes32 salt, address initCodeStore) internal returns (address) {
+        return Create2.deploy(0, salt, ProxyInitCode.load(initCodeStore));
+    }
+
+    /// @dev Every address the protocol publishes comes from the prediction, so a deployment
+    ///      elsewhere reverts here with a reason rather than failing later without one.
+    function requireLanded(address predicted, address deployed) internal pure {
+        if (deployed != predicted) revert ConduitAddressMismatch(predicted, deployed);
+    }
+
+    /// @notice Arm and lock the proxy in one call, so it never has logic and a live upgrade key
+    ///         at once.
+    function arm(address conduit, address implementation, bytes memory initializer) internal {
+        IProxy(conduit).upgradeInitializeAndLock(implementation, initializer);
+    }
+}