@crossecute/protocol 0.0.0 → 0.1.0

package/contracts/derivation/Blake2b256.sol

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @title Blake2b256
+/// @notice Full BLAKE2b-256 built on the EIP-152 `blake2f` compression precompile (0x09).
+///
+/// @dev The precompile provides only the F compression function, not a hash. This library
+///      supplies the parameter block, the message padding, the byte-offset counters, and
+///      the final-block flag around it.
+///
+///      Endianness. EIP-152 takes and returns the state `h` and message `m` as
+///      little-endian 64-bit words. Because we carry `h` as opaque 64 raw bytes and pass
+///      message blocks through verbatim, no word swapping is ever needed: only the
+///      parameter-block XOR and the `t` counter are written in explicit little-endian.
+///      This is the single most common source of wrong BLAKE2b ports; it is avoided here
+///      rather than handled.
+///
+///      Mutability. Functions here are `view`, not `pure`. Solidity forbids `staticcall`
+///      inside `pure`, and there is no `blake2b` builtin the way there is for `sha256`
+///      and `ripemd160`. Callers that need `pure` cannot use this; pass the digest in.
+///
+///      Gas. The precompile costs 1 gas per round, 12 rounds per 128-byte block, so the
+///      compression itself is free in practice. Cost is dominated by memory and the
+///      staticcall overhead: measured at roughly 3k gas for a single-block input.
+library Blake2b256 {
+    /// @dev BLAKE2b IV, little-endian bytes, with h[0] already XORed by the parameter
+    ///      block 0x01010020 (fanout=1, depth=1, key length=0, digest length=32).
+    ///      0x6a09e667f3bcc908 ^ 0x01010020 == 0x6a09e667f2bdc928.
+    bytes private constant IV_PARAM = hex"28c9bdf267e6096a" hex"3ba7ca8485ae67bb" hex"2bf894fe72f36e3c"
+        hex"f1361d5f3af54fa5" hex"d182e6ad7f520e51" hex"1f6c3e2b8c68059b" hex"6bbd41fbabd9831f" hex"79217e1319cde05b";
+
+    uint32 private constant ROUNDS = 12;
+    uint256 private constant BLOCK_SIZE = 128;
+
+    error PrecompileFailed();
+
+    /// @notice BLAKE2b-256 over an arbitrary-length input, unkeyed.
+    /// @dev Handles the empty input, exact-multiple-of-128 inputs, and multi-block
+    ///      inputs. All three are separately covered by the test vectors.
+    function hash(bytes memory input) internal view returns (bytes32) {
+        bytes memory h = IV_PARAM; // 64 bytes, mutated in place across blocks
+
+        uint256 len = input.length;
+        if (len == 0) {
+            // Single all-zero final block with counter 0.
+            h = _compress(h, new bytes(BLOCK_SIZE), 0, true);
+        } else {
+            uint256 nBlocks = (len + BLOCK_SIZE - 1) / BLOCK_SIZE;
+            for (uint256 i; i < nBlocks; ++i) {
+                bool last = (i == nBlocks - 1);
+                uint256 offset = i * BLOCK_SIZE;
+                // Counter is bytes compressed so far including this block. For the
+                // final block that is the true message length, not a padded length.
+                // forge-lint: disable-next-line(unsafe-typecast) a memory length fits in 64 bits
+                uint64 t = uint64(last ? len : offset + BLOCK_SIZE);
+                h = _compress(h, _blockAt(input, offset, len), t, last);
+            }
+        }
+
+        // Digest is the first 32 bytes of the state, already in output byte order.
+        bytes32 out;
+        assembly {
+            out := mload(add(h, 32))
+        }
+        return out;
+    }
+
+    /// @dev Extracts a 128-byte block starting at `offset`, zero-padded if the message
+    ///      ends early. Zero padding is part of the BLAKE2b spec, not an artifact.
+    function _blockAt(bytes memory input, uint256 offset, uint256 len) private pure returns (bytes memory blk) {
+        // forge-lint: disable-next-line(calls-loop) allocation, not a call
+        blk = new bytes(BLOCK_SIZE);
+        uint256 n = len - offset;
+        if (n > BLOCK_SIZE) n = BLOCK_SIZE;
+        for (uint256 i; i < n; ++i) {
+            blk[i] = input[offset + i];
+        }
+    }
+
+    /// @dev One call to the EIP-152 F compression function.
+    ///      Input layout is exactly 213 bytes:
+    ///        rounds  4  bytes, big-endian uint32
+    ///        h      64  bytes, 8 little-endian uint64
+    ///        m     128  bytes, 16 little-endian uint64
+    ///        t      16  bytes, t0 then t1, each little-endian uint64
+    ///        f       1  byte,  0x01 on the final block
+    function _compress(bytes memory h, bytes memory blk, uint64 t0, bool last) private view returns (bytes memory out) {
+        // Every field is fixed-width.
+        // forge-lint: disable-start(encode-packed-collision)
+        bytes memory input = abi.encodePacked(
+            ROUNDS, // 4, big-endian by abi.encodePacked
+            h, // 64
+            blk, // 128
+            _le64(t0), // 8   (t0)
+            bytes8(0), // 8   (t1: messages beyond 2^64 bytes are not representable)
+            last ? bytes1(0x01) : bytes1(0x00) // 1
+        );
+        // forge-lint: disable-end(encode-packed-collision)
+
+        // forge-lint: disable-next-line(calls-loop) allocation, not a call
+        out = new bytes(64);
+        bool ok;
+        assembly {
+            // Without EIP-152, 0x09 may be empty (success, no data), revert (zkSync Era), or
+            // hold another precompile (Tron's BatchValidateSign returns 32 bytes), so the size
+            // is checked too, or a digest could be zeros or foreign output.
+            ok := staticcall(gas(), 0x09, add(input, 32), 213, add(out, 32), 64)
+            ok := and(ok, eq(returndatasize(), 64))
+        }
+        if (!ok) revert PrecompileFailed();
+    }
+
+    /// @dev uint64 -> 8 little-endian bytes.
+    function _le64(uint64 x) private pure returns (bytes8 r) {
+        uint64 v;
+        for (uint256 i; i < 8; ++i) {
+            v = (v << 8) | (x & 0xff);
+            x >>= 8;
+        }
+        r = bytes8(v);
+    }
+}

package/contracts/derivation/IVmDeriver.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice Uniform address derivation across every VM the protocol targets.
+///
+/// @dev The normalization problem. Every VM's derivation takes different inputs: CREATE2
+///      wants (deployer, salt, initCodeHash), a Solana PDA wants (seeds[], bump,
+///      programId), CosmWasm wants (checksum, creator, salt, initMsg). There is no
+///      argument list that fits all of them, so the parameters stay opaque: the caller
+///      passes an ABI-encoded blob and the deriver decodes the shape its scheme requires.
+///
+///      What is uniform is the two ends. Every implementation takes a canonical ERC-7930
+///      chain identifier plus a params blob, and returns a canonical ERC-7930 conduit
+///      envelope for the same chain. The registry can therefore store the result without
+///      knowing which VM produced it.
+///
+/// @dev Kept apart from `VmDeriver` so that `ChainRegistry`, which every chain deploys, does
+///      not import `BitcoinDerive`: zksolc rejects any unit containing `ripemd160`.
+///
+/// @dev Must be `view`, not `pure`. Sui's BLAKE2b-256 goes through precompile 0x09, which
+///      is a `staticcall`. One non-pure member forces the whole interface to `view`.
+interface IVmDeriver {
+    /// @param chainIdentifier Canonical ERC-7930 chain identifier (zero-length address).
+    /// @param params          `abi.encode(Scheme, bytes)`: see `VmDeriver.Scheme`.
+    /// @return interop        Canonical ERC-7930 conduit envelope on that same chain.
+    function deriveAddress(bytes calldata chainIdentifier, bytes calldata params)
+        external
+        view
+        returns (bytes memory interop);
+
+    /// @notice Whether this deriver can serve `scheme` on `chainType`.
+    /// @dev Lets the registry reject a misconfiguration at wiring time rather than at
+    ///      the first resolve.
+    function supportsScheme(uint16 chainType, uint8 scheme) external pure returns (bool);
+}

package/contracts/derivation/StarknetDerive.sol

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @title StarknetDerive
+/// @notice What can and cannot be computed about Starknet from the EVM.
+///
+/// @dev Constants are sourced, not recalled. All values below come from
+///      starkware-libs/cairo-lang:
+///        - starknet/definitions/constants.py :: L2_ADDRESS_UPPER_BOUND
+///        - starknet/public/abi.py            :: ADDR_BOUND, MASK_250, starknet_keccak
+///        - starknet/core/os/contract_address/contract_address.py
+///
+/// @dev What is derivable here
+///        - `starknetKeccak` / `selector`: masked keccak256. Native opcode, ~free.
+///          This is how Starknet entry-point selectors are computed, so a payload
+///          targeting a Starknet function can commit to its selector on-chain.
+///        - Range validation of addresses, class hashes, and felts.
+///
+/// @dev What is not
+///        Contract addresses. The derivation is a Pedersen hash chain:
+///            raw = H(H(H(H(H(0, prefix), deployer), salt), classHash), ctorHash), 5)
+///            address = raw mod L2_ADDRESS_UPPER_BOUND
+///        where prefix is the felt encoding of the ASCII "STARKNET_CONTRACT_ADDRESS"
+///        and H is Pedersen over the STARK curve.
+///
+///        Pedersen is not merely expensive here, it is structurally awkward: it needs
+///        roughly 500 precomputed curve points (~32kb), which exceeds EIP-170 outright,
+///        so a real implementation means SSTORE2-chunked tables plus projective EC
+///        arithmetic over a 252-bit prime, at 1e5-1e6 gas with a silent-failure mode.
+///
+///        Recommendation: do not build it. The payoff is upgrading Starknet from
+///        `Unique` to `Predetermined`, and the address can be recorded from a signed payload
+///        instead, where the grade states the weaker guarantee rather than hiding it.
+library StarknetDerive {
+    /// @dev FIELD_PRIME = 2^251 + 17 * 2^192 + 1
+    uint256 internal constant FIELD_PRIME = 0x0800000000000011000000000000000000000000000000000000000000000001;
+
+    /// @dev L2_ADDRESS_UPPER_BOUND = 2^251 - 256. Note the "- 256": a naive `< 2^251`
+    ///      check admits 256 values that can never be a Starknet contract address,
+    ///      because `calculate_contract_address_from_hash` reduces mod this bound.
+    uint256 internal constant L2_ADDRESS_UPPER_BOUND = (1 << 251) - 256;
+
+    /// @dev MASK_250 = 2^250 - 1
+    uint256 internal constant MASK_250 = (1 << 250) - 1;
+
+    /// @dev CONTRACT_ADDRESS_PREFIX = felt encoding of ASCII "STARKNET_CONTRACT_ADDRESS"
+    ///      (25 bytes, big-endian). Present so an off-chain derivation can be checked
+    ///      against the same constant the contract enforces.
+    uint256 internal constant CONTRACT_ADDRESS_PREFIX = 0x535441524b4e45545f434f4e54524143545f41444452455353;
+
+    error AddressOutOfRange();
+    error FeltOutOfRange();
+    error ClassHashOutOfRange();
+    error BadAddressWidth();
+
+    /// @notice Starknet's keccak variant: keccak256 truncated to 250 bits so the
+    ///         result fits a field element.
+    /// @dev cairo-lang: `from_bytes(keccak(data)) & MASK_250`.
+    function starknetKeccak(bytes memory data) internal pure returns (uint256) {
+        return uint256(keccak256(data)) & MASK_250;
+    }
+
+    /// @notice Entry-point selector for a function name.
+    /// @dev Selectors for `__default__` / `__l1_default__` are 0 by special case;
+    ///      that is a caller concern, not encoded here.
+    function selector(string memory functionName) internal pure returns (uint256) {
+        return starknetKeccak(bytes(functionName));
+    }
+
+    /// @notice A contract address must be strictly below L2_ADDRESS_UPPER_BOUND.
+    function validateAddress(uint256 addr) internal pure {
+        if (addr >= L2_ADDRESS_UPPER_BOUND) revert AddressOutOfRange();
+    }
+
+    /// @notice A generic field element must be below FIELD_PRIME. Class hashes use
+    ///         this wider bound (CLASS_HASH_UPPER_BOUND == FIELD_SIZE), not the
+    ///         address bound.
+    function validateFelt(uint256 v) internal pure {
+        if (v >= FIELD_PRIME) revert FeltOutOfRange();
+    }
+
+    function validateClassHash(uint256 v) internal pure {
+        if (v >= FIELD_PRIME) revert ClassHashOutOfRange();
+    }
+
+    /// @notice Read a 32-byte Starknet address out of ERC-7930 address bytes.
+    function toFelt(bytes memory addr) internal pure returns (uint256 v) {
+        if (addr.length != 32) revert BadAddressWidth();
+        assembly {
+            v := mload(add(addr, 32))
+        }
+    }
+}

package/contracts/derivation/SuiDerive.sol

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Blake2b256} from "./Blake2b256.sol";
+
+/// @title SuiDerive
+/// @notice Sui address and object-ID derivation, executable on Ethereum.
+/// @dev Every constant below was read from MystenLabs/sui rather than recalled.
+library SuiDerive {
+    using Blake2b256 for bytes;
+
+    /* ------------------------------- flags -------------------------------- */
+    // crates/sui-types/src/crypto.rs :: SignatureScheme::flag()
+    uint8 internal constant FLAG_ED25519 = 0x00;
+    uint8 internal constant FLAG_SECP256K1 = 0x01;
+    uint8 internal constant FLAG_SECP256R1 = 0x02;
+    uint8 internal constant FLAG_MULTISIG = 0x03;
+    uint8 internal constant FLAG_BLS12381 = 0x04; // not valid for a user address
+    uint8 internal constant FLAG_ZKLOGIN = 0x05;
+    uint8 internal constant FLAG_PASSKEY = 0x06;
+
+    /* --------------------------- intent scopes ---------------------------- */
+    // crates/shared-crypto/src/intent.rs :: HashingIntentScope
+    // Note: these are 0xf0/0xf1, not 0/1. Assuming a zero-based enum here silently
+    // produces well-formed but wrong object IDs.
+    uint8 internal constant SCOPE_CHILD_OBJECT_ID = 0xf0;
+    uint8 internal constant SCOPE_REGULAR_OBJECT_ID = 0xf1;
+
+    error InvalidFlag();
+    error LengthMismatch();
+
+    /// @notice Sui address = blake2b256(flag ‖ pubkey).
+    /// @dev crates/sui-types/src/base_types.rs :: impl From<&PublicKey> for SuiAddress
+    /// @param flag One of the FLAG_* constants.
+    /// @param pubkey Raw public key bytes. Ed25519 is 32; secp256k1/r1 are 33
+    ///        (SEC1 compressed). Length is checked where it is fixed.
+    function addressFromPubkey(uint8 flag, bytes memory pubkey) internal view returns (bytes32) {
+        if (flag == FLAG_ED25519) {
+            if (pubkey.length != 32) revert LengthMismatch();
+        } else if (flag == FLAG_SECP256K1 || flag == FLAG_SECP256R1 || flag == FLAG_PASSKEY) {
+            if (pubkey.length != 33) revert LengthMismatch();
+        } else if (flag != FLAG_ZKLOGIN) {
+            // MultiSig has its own constructor; BLS is not a valid user address.
+            revert InvalidFlag();
+        }
+        return Blake2b256.hash(abi.encodePacked(flag, pubkey));
+    }
+
+    /// @notice MultiSig address.
+    /// @dev blake2b256( 0x03 ‖ le16(threshold) ‖ (flag_i ‖ pk_i ‖ weight_i)* )
+    ///      Threshold is u16 little-endian; each weight is u8. Order of the member
+    ///      list is significant: it must match the on-chain MultiSigPublicKey.
+    /// @param flags Per-member scheme flags.
+    /// @param pubkeys Per-member raw public keys, same order as `flags`.
+    /// @param weights Per-member weights, same order.
+    function addressFromMultisig(uint16 threshold, uint8[] memory flags, bytes[] memory pubkeys, uint8[] memory weights)
+        internal
+        view
+        returns (bytes32)
+    {
+        uint256 n = flags.length;
+        if (pubkeys.length != n || weights.length != n) revert LengthMismatch();
+
+        bytes memory pre = abi.encodePacked(FLAG_MULTISIG, _le16(threshold));
+        for (uint256 i; i < n; ++i) {
+            // forge-lint: disable-next-line(encode-packed-collision) Sui's multisig preimage; each key's length is fixed by its flag
+            pre = abi.encodePacked(pre, flags[i], pubkeys[i], weights[i]);
+        }
+        return Blake2b256.hash(pre);
+    }
+
+    /// @notice Object ID created by a transaction.
+    /// @dev crates/sui-types/src/base_types.rs :: ObjectID::derive_id
+    ///      blake2b256( 0xf1 ‖ txDigest ‖ le64(creationNum) ), truncated to 32 bytes
+    ///      (already 32, so the truncation is a no-op).
+    ///
+    ///      This is derivable but not counterfactual: `txDigest` does not exist until
+    ///      the transaction is built and signed, and `creationNum` depends on how many
+    ///      IDs that transaction already created. Use it to verify an object ID
+    ///      reported back by the destination, not to predict one in advance.
+    function deriveObjectId(bytes32 txDigest, uint64 creationNum) internal view returns (bytes32) {
+        return Blake2b256.hash(abi.encodePacked(SCOPE_REGULAR_OBJECT_ID, txDigest, _le64(creationNum)));
+    }
+
+    /// @notice Dynamic-field / child object ID variant.
+    function deriveChildObjectId(bytes32 txDigest, uint64 creationNum) internal view returns (bytes32) {
+        return Blake2b256.hash(abi.encodePacked(SCOPE_CHILD_OBJECT_ID, txDigest, _le64(creationNum)));
+    }
+
+    function _le16(uint16 x) private pure returns (bytes2) {
+        return bytes2(uint16((uint16(x & 0xff) << 8) | (x >> 8)));
+    }
+
+    function _le64(uint64 x) private pure returns (bytes8 r) {
+        uint64 v;
+        for (uint256 i; i < 8; ++i) {
+            v = (v << 8) | (x & 0xff);
+            x >>= 8;
+        }
+        r = bytes8(v);
+    }
+}

package/contracts/derivation/VmDeriver.sol

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ChainType} from "../addressing/ChainType.sol";
+import {AddressDerive} from "./AddressDerive.sol";
+import {BitcoinDerive} from "./BitcoinDerive.sol";
+import {SuiDerive} from "./SuiDerive.sol";
+import {Erc7930} from "../addressing/Erc7930.sol";
+import {IVmDeriver} from "./IVmDeriver.sol";
+
+/// @title VmDeriver
+/// @notice One standalone, stateless contract implementing every derivation the protocol
+///         can perform on-chain, dispatched by (ChainType, Scheme).
+///
+/// @dev Why one contract and not one per VM. These are pure functions over calldata with
+///      no storage and no privileges, so there is nothing to isolate between them. A
+///      single deployment means one address to audit and one address to register for
+///      every chain, and the registry's `deriverOf` mapping still allows a per-chain
+///      override later if a VM ever needs its own.
+///
+/// @dev Dispatch is two-dimensional, and it has to be. ChainType alone is not enough:
+///      Ethereum, zkSync Era, and Tron are all `eip155`, with three different CREATE2
+///      formulas. Scheme alone is not enough either, since the same scheme must produce
+///      envelopes on different chains. Every scheme is therefore checked against the
+///      chain type it is legal for, in `supportsScheme`.
+///
+/// @dev Not derivable here, by construction:
+///        - Aptos / Movement: SHA3-256 is not keccak256 (padding domain 0x06 vs 0x01).
+///          A hand-rolled Keccak-f[1600] is ~1e5 gas.
+///        - Starknet: Pedersen/Poseidon over the STARK curve. No precompile, and the
+///          point tables exceed EIP-170 outright.
+///        - Bitcoin P2TR: taproot output keys need secp256k1 point addition; ecrecover
+///          is not a general curve operation.
+///      These revert with `UnsupportedScheme`. Route them through the registry's
+///      committed or `Unique` path: that is exactly what the provenance grades are for.
+contract VmDeriver is IVmDeriver {
+    /// @notice Which derivation to run. The chain type says which VM; this says which
+    ///         formula within it.
+    enum Scheme {
+        Unset,
+        /// EIP-1014. (address deployer, bytes32 salt, bytes32 initCodeHash)
+        EvmCreate2,
+        /// (address factory, bytes32 salt): bytecode-independent.
+        EvmCreate3,
+        /// Nonce-based. (address deployer, uint256 nonce)
+        EvmCreate,
+        /// (address sender, bytes32 salt, bytes32 bytecodeHash, bytes32 ctorInputHash)
+        ZkSyncCreate2,
+        /// (address sender, uint256 nonce)
+        ZkSyncCreate,
+        /// (address deployer, bytes32 salt, bytes32 initCodeHash)
+        TronCreate2,
+        /// (bytes32 checksum, bytes creator, bytes salt, bytes initMsg, uint8 addrLen)
+        CosmosInstantiate2,
+        /// (bytes[] seeds, uint8 bump, bytes32 programId)
+        SolanaPda,
+        /// (bytes32 owner, bytes32 mint, bytes32 tokenProgram, bytes32 ataProgram, uint8 bump)
+        SolanaAta,
+        /// (bytes32 base, bytes seed, bytes32 programId)
+        SolanaCreateWithSeed,
+        /// (bytes borshStateInit) -> 20 bytes, rendered "0s"+hex off-chain
+        NearDeterministic,
+        /// (bytes uncompressedPubkey64) -> 20 bytes
+        NearEthImplicit,
+        /// (bytes32 ed25519Pubkey) -> 32 bytes
+        NearImplicit,
+        /// (bytes pubkey) -> 20-byte HASH160 witness program
+        BitcoinP2wpkh,
+        /// (bytes witnessScript) -> 32-byte SHA256 witness program
+        BitcoinP2wsh,
+        /// (bytes redeemScript) -> 20-byte HASH160
+        BitcoinP2sh,
+        /// (uint8 flag, bytes pubkey)
+        SuiAddress,
+        /// (uint16 threshold, uint8[] flags, bytes[] pubkeys, uint8[] weights)
+        SuiMultisig,
+        /// (bytes32 txDigest, uint64 creationNum): verification only, see note.
+        SuiObjectId,
+        /// EIP-1167 clone. (address deployer, address implementation, bytes32 salt)
+        /// This is how a receiver address is predicted: deployer is the destination
+        /// transceiver, salt is `keccak256(abi.encode(transmitter))`.
+        EvmClone,
+        /// EIP-1167 clone under Tron's 0x41 domain byte. Same params as EvmClone.
+        TronClone
+    }
+
+    error UnsupportedScheme(uint16 chainType, uint8 scheme);
+
+    error NotChainIdentifier();
+    error BadCosmosAddressLength();
+
+    /// @notice Creation-code hash of an EIP-1167 clone. Exposed so the same value can be
+    ///         computed off-chain and pinned in a signed payload.
+    function cloneInitCodeHash(address implementation) external pure returns (bytes32) {
+        return AddressDerive.cloneInitCodeHash(implementation);
+    }
+
+    /* ================================ dispatch ================================= */
+
+    /// @inheritdoc IVmDeriver
+    function deriveAddress(bytes calldata chainIdentifier, bytes calldata params)
+        external
+        view
+        override
+        returns (bytes memory interop)
+    {
+        Erc7930.Interop memory io = Erc7930.parseStrict(chainIdentifier);
+        // A chain identifier carries no conduit. Being handed a populated envelope means
+        // the caller is confused about which end of the derivation it is on.
+        if (io.addr.length != 0) revert NotChainIdentifier();
+
+        (Scheme scheme, bytes memory inner) = abi.decode(params, (Scheme, bytes));
+        if (!supportsScheme(io.chainType, uint8(scheme))) {
+            revert UnsupportedScheme(io.chainType, uint8(scheme));
+        }
+
+        return Erc7930.encode(io.chainType, io.chainRef, _derive(scheme, inner));
+    }
+
+    /// @inheritdoc IVmDeriver
+    /// @dev The legality table. Ethereum/zkSync/Tron all being `eip155` is why this is
+    ///      keyed on the pair and not on either half alone: the registry pins the exact
+    ///      scheme per chainKey, so a zkSync chainKey cannot be resolved with Ethereum's
+    ///      formula just because both are eip155.
+    function supportsScheme(uint16 chainType, uint8 scheme) public pure override returns (bool) {
+        Scheme s = Scheme(scheme);
+
+        if (chainType == ChainType.EIP155) {
+            return s == Scheme.EvmCreate2 || s == Scheme.EvmCreate3 || s == Scheme.EvmCreate
+                || s == Scheme.ZkSyncCreate2 || s == Scheme.ZkSyncCreate || s == Scheme.TronCreate2
+                || s == Scheme.EvmClone || s == Scheme.TronClone;
+        }
+        if (chainType == ChainType.SOLANA) {
+            return s == Scheme.SolanaPda || s == Scheme.SolanaAta || s == Scheme.SolanaCreateWithSeed;
+        }
+        if (chainType == ChainType.BIP122) {
+            return s == Scheme.BitcoinP2wpkh || s == Scheme.BitcoinP2wsh || s == Scheme.BitcoinP2sh;
+        }
+        if (chainType == ChainType.COSMOS) {
+            return s == Scheme.CosmosInstantiate2;
+        }
+        if (chainType == ChainType.NEAR) {
+            return s == Scheme.NearDeterministic || s == Scheme.NearEthImplicit || s == Scheme.NearImplicit;
+        }
+        if (chainType == ChainType.SUI) {
+            return s == Scheme.SuiAddress || s == Scheme.SuiMultisig || s == Scheme.SuiObjectId;
+        }
+        // ChainType.Aptos and ChainType.Starknet are deliberately absent.
+        return false;
+    }
+
+    /* =============================== derivations =============================== */
+
+    /// @dev Returns the raw address bytes for the scheme, at the width that chain's
+    ///      ERC-7930 profile expects. The caller wraps them in the envelope.
+    function _derive(Scheme s, bytes memory p) private view returns (bytes memory) {
+        /* ---------------------------------- EVM --------------------------------- */
+        if (s == Scheme.EvmCreate2) {
+            (address deployer, bytes32 salt, bytes32 initCodeHash) = abi.decode(p, (address, bytes32, bytes32));
+            return abi.encodePacked(AddressDerive.create2(deployer, salt, initCodeHash));
+        }
+        if (s == Scheme.EvmCreate3) {
+            (address factory, bytes32 salt) = abi.decode(p, (address, bytes32));
+            return abi.encodePacked(AddressDerive.create3(factory, salt));
+        }
+        if (s == Scheme.EvmCreate) {
+            (address deployer, uint256 nonce) = abi.decode(p, (address, uint256));
+            return abi.encodePacked(AddressDerive.create(deployer, nonce));
+        }
+
+        /* -------------------------------- clones -------------------------------- */
+        // Note on zkSYNC: EIP-1167 has no zkSync equivalent. EraVM will only deploy
+        // bytecode whose hash has been published, and a 55-byte EVM proxy is not valid
+        // EraVM bytecode at all. A zkSync "clone" is a real proxy contract compiled with
+        // zksolc, so it is derived with `ZkSyncCreate2` using that proxy's versioned
+        // bytecode hash: no separate scheme, because it is not a clone in this sense.
+        if (s == Scheme.EvmClone) {
+            (address deployer, address implementation, bytes32 salt) = abi.decode(p, (address, address, bytes32));
+            return abi.encodePacked(AddressDerive.clone2(deployer, implementation, salt));
+        }
+        if (s == Scheme.TronClone) {
+            (address deployer, address implementation, bytes32 salt) = abi.decode(p, (address, address, bytes32));
+            return abi.encodePacked(
+                AddressDerive.tronCreate2(deployer, salt, AddressDerive.cloneInitCodeHash(implementation))
+            );
+        }
+
+        /* -------------------------------- zkSync -------------------------------- */
+        if (s == Scheme.ZkSyncCreate2) {
+            (address sender, bytes32 salt, bytes32 bytecodeHash, bytes32 ctorInputHash) =
+                abi.decode(p, (address, bytes32, bytes32, bytes32));
+            return abi.encodePacked(AddressDerive.zksyncCreate2(sender, salt, bytecodeHash, ctorInputHash));
+        }
+        if (s == Scheme.ZkSyncCreate) {
+            (address sender, uint256 nonce) = abi.decode(p, (address, uint256));
+            return abi.encodePacked(AddressDerive.zksyncCreate(sender, nonce));
+        }
+
+        /* --------------------------------- Tron --------------------------------- */
+        if (s == Scheme.TronCreate2) {
+            (address deployer, bytes32 salt, bytes32 initCodeHash) = abi.decode(p, (address, bytes32, bytes32));
+            return abi.encodePacked(AddressDerive.tronCreate2(deployer, salt, initCodeHash));
+        }
+
+        /* -------------------------------- Cosmos -------------------------------- */
+        if (s == Scheme.CosmosInstantiate2) {
+            (bytes32 checksum, bytes memory creator, bytes memory salt, bytes memory initMsg, uint8 addrLen) =
+                abi.decode(p, (bytes32, bytes, bytes, bytes, uint8));
+            bytes32 full = AddressDerive.cosmosInstantiate2(checksum, creator, salt, initMsg);
+            // Canonical ADR-028 is 32 bytes. Forked wasmd chains that use 20 for
+            // Ethereum-ecosystem compatibility (Injective) truncate. Only set addrLen
+            // below 32 if you have confirmed the target forked ContractAddrLen:
+            // getting it wrong yields a well-formed address nothing will ever occupy.
+            if (addrLen == 0 || addrLen > 32) revert BadCosmosAddressLength();
+            if (addrLen == 32) return abi.encodePacked(full);
+            bytes memory out = new bytes(addrLen);
+            for (uint256 i; i < addrLen; ++i) {
+                out[i] = full[i];
+            }
+            return out;
+        }
+
+        /* -------------------------------- Solana -------------------------------- */
+        if (s == Scheme.SolanaPda) {
+            (bytes[] memory seeds, uint8 bump, bytes32 programId) = abi.decode(p, (bytes[], uint8, bytes32));
+            return abi.encodePacked(AddressDerive.solanaCreateProgramAddress(seeds, bump, programId));
+        }
+        if (s == Scheme.SolanaAta) {
+            (bytes32 owner, bytes32 mint, bytes32 tokenProgram, bytes32 ataProgram, uint8 bump) =
+                abi.decode(p, (bytes32, bytes32, bytes32, bytes32, uint8));
+            return
+                abi.encodePacked(
+                    AddressDerive.solanaAssociatedTokenAccount(owner, mint, tokenProgram, ataProgram, bump)
+                );
+        }
+        if (s == Scheme.SolanaCreateWithSeed) {
+            (bytes32 base, bytes memory seed, bytes32 programId) = abi.decode(p, (bytes32, bytes, bytes32));
+            return abi.encodePacked(AddressDerive.solanaCreateWithSeed(base, seed, programId));
+        }
+
+        /* --------------------------------- NEAR --------------------------------- */
+        if (s == Scheme.NearDeterministic) {
+            bytes memory borshStateInit = abi.decode(p, (bytes));
+            return abi.encodePacked(AddressDerive.nearDeterministicAccount(borshStateInit));
+        }
+        if (s == Scheme.NearEthImplicit) {
+            bytes memory pubkey64 = abi.decode(p, (bytes));
+            return abi.encodePacked(AddressDerive.nearEthImplicitAccount(pubkey64));
+        }
+        if (s == Scheme.NearImplicit) {
+            // The ed25519 pubkey is the conduit id. Identity, kept explicit so the
+            // envelope width is unambiguous.
+            bytes32 pubkey = abi.decode(p, (bytes32));
+            return abi.encodePacked(pubkey);
+        }
+
+        /* -------------------------------- Bitcoin ------------------------------- */
+        if (s == Scheme.BitcoinP2wpkh) {
+            bytes memory pubkey = abi.decode(p, (bytes));
+            return abi.encodePacked(BitcoinDerive.hash160(pubkey));
+        }
+        if (s == Scheme.BitcoinP2wsh) {
+            bytes memory witnessScript = abi.decode(p, (bytes));
+            return abi.encodePacked(BitcoinDerive.p2wshProgram(witnessScript));
+        }
+        if (s == Scheme.BitcoinP2sh) {
+            bytes memory redeemScript = abi.decode(p, (bytes));
+            return abi.encodePacked(BitcoinDerive.p2shScriptHash(redeemScript));
+        }
+
+        /* ---------------------------------- Sui --------------------------------- */
+        if (s == Scheme.SuiAddress) {
+            (uint8 flag, bytes memory pubkey) = abi.decode(p, (uint8, bytes));
+            return abi.encodePacked(SuiDerive.addressFromPubkey(flag, pubkey));
+        }
+        if (s == Scheme.SuiMultisig) {
+            (uint16 threshold, uint8[] memory flags, bytes[] memory pubkeys, uint8[] memory weights) =
+                abi.decode(p, (uint16, uint8[], bytes[], uint8[]));
+            return abi.encodePacked(SuiDerive.addressFromMultisig(threshold, flags, pubkeys, weights));
+        }
+        if (s == Scheme.SuiObjectId) {
+            // Derivable but not counterfactual: txDigest does not exist until the
+            // transaction is built and signed. Use this to verify an object id the
+            // destination reported, never to predict one in advance.
+            (bytes32 txDigest, uint64 creationNum) = abi.decode(p, (bytes32, uint64));
+            return abi.encodePacked(SuiDerive.deriveObjectId(txDigest, creationNum));
+        }
+
+        revert UnsupportedScheme(0, uint8(s));
+    }
+}