@crossecute/protocol 0.0.0 → 0.1.1

package/contracts/conduit/Proxy.sol

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice The one call a `Proxy` accepts from its deployer. Declared separately so
+///         callers have a selector without the proxy shadowing the implementation's ABI.
+interface IProxy {
+    function upgradeInitializeAndLock(address implementation, bytes calldata data) external;
+}
+
+/// @title Proxy
+/// @notice The proxy every crossecute conduit is deployed as, transmitter and receiver alike,
+///         and every transceiver, through `ProxyDeployer`. Its implementation is locked
+///         once armed; its owner's authority is unchanged.
+///
+/// @dev No constructor arguments, so its initcode is one constant and a transmitter (from its
+///      home's transceiver) and a receiver (from another chain's) at the same deployer address
+///      and salt land on one address. An EIP-1167 clone embeds its implementation in the initcode and could not.
+///
+/// @dev The deployer can arm the proxy only while no implementation is set. The single admin
+///      operation installs the implementation, runs its initializer, and by installing it ends
+///      the deployer's ability to arm, so no conduit or transceiver ever has a live upgrade key
+///      and real logic at once. An implementation must not write the ERC-1967 implementation
+///      slot: clearing it would let the deployer arm again.
+///
+/// @dev The deployer is an immutable, so it sits in the runtime code and not the initcode: the
+///      address is unchanged, but the code hash differs per deployer, and a proxy is verified by
+///      its CREATE2 address. A call on an armed proxy reads the implementation slot and nothing else.
+///
+/// @dev The admin operation is routed in `fallback`, not declared, so it shadows no selector.
+///      Once armed every call delegates, as in a plain ERC-1967 proxy.
+contract Proxy {
+    // forge-lint: disable-next-line(unused-error) reverted in assembly; declared for the ABI
+    error UnknownAdminCall(bytes4 selector);
+
+    event Locked(address implementation);
+
+    // ERC1967Utils.IMPLEMENTATION_SLOT and the errors and events the arming call reports, as
+    // literals so assembly can read them; `ProxyDifferential` compares every one against
+    // the library-built reference.
+    //
+    // bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)
+    bytes32 private constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+    // keccak256("Upgraded(address)"), IERC1967
+    bytes32 private constant UPGRADED = 0xbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b;
+    // keccak256("Locked(address)")
+    bytes32 private constant LOCKED = 0x44427e3003a08f22cf803894075ac0297524e09e521fc1c15bc91741ce3dc159;
+    // bytes4(keccak256("upgradeInitializeAndLock(address,bytes)"))
+    uint256 private constant ARM = 0x885088b2;
+    // bytes4(keccak256("UnknownAdminCall(bytes4)")), declared above
+    uint256 private constant UNKNOWN_ADMIN_CALL = 0xf3e81dfa;
+    // bytes4(keccak256("ERC1967InvalidImplementation(address)")), as in ERC1967Utils
+    uint256 private constant INVALID_IMPLEMENTATION = 0x4c9c8ce3;
+    // bytes4(keccak256("ERC1967NonPayable()")), as in ERC1967Utils
+    uint256 private constant NON_PAYABLE = 0xb398979f;
+    // bytes4(keccak256("FailedCall()")), as in OpenZeppelin's Errors
+    uint256 private constant FAILED_CALL = 0xd6bda275;
+
+    address private immutable ADMIN;
+
+    constructor() {
+        ADMIN = msg.sender;
+    }
+
+    fallback() external payable {
+        address current;
+        assembly {
+            current := sload(IMPLEMENTATION_SLOT) // implementation; zero while the proxy is blank
+        }
+
+        // Armed, or not the deployer: an ordinary call. A blank proxy delegates to no code and
+        // succeeds. `ADMIN` is read only while blank.
+        if (current != address(0) || msg.sender != ADMIN) {
+            assembly {
+                calldatacopy(0, 0, calldatasize()) // copy the whole call to memory at 0
+                let ok := delegatecall(gas(), current, 0, calldatasize(), 0, 0) // run it as this proxy
+                returndatacopy(0, 0, returndatasize()) // copy its output, or its revert data, to memory at 0
+                if iszero(ok) { revert(0, returndatasize()) } // pass a revert through unchanged
+                return(0, returndatasize()) // return its output
+            }
+        }
+
+        assembly {
+            let size := calldatasize() // total bytes of calldata
+            let sig := and(calldataload(0), shl(224, 0xffffffff)) // selector, left-aligned; zero-padded if short
+            if iszero(eq(sig, shl(224, ARM))) {
+                // anything but the arming selector is refused
+                mstore(0, shl(224, UNKNOWN_ADMIN_CALL)) // UnknownAdminCall(bytes4), selector left-aligned at 0
+                mstore(4, sig) // its argument, the selector received, at 4
+                revert(0, 36) // selector and one 32-byte argument
+            }
+
+            // abi.decode(msg.data[4:], (address, bytes)), refusing what it refuses. A length over
+            // 2^64 reverts with no data here and with Panic(0x41) there.
+            if lt(size, 68) { revert(0, 0) } // needs the selector and both head words: 4 + 64
+            let implementation := calldataload(4) // first argument
+            if shr(160, implementation) { revert(0, 0) } // an address with high bits set is malformed
+            let offset := calldataload(36) // second argument: where the bytes sit, counted after the selector
+            if gt(offset, 0xffffffffffffffff) { revert(0, 0) } // keeps the additions below from wrapping
+            let start := add(offset, 4) // position of the length word in calldata
+            let length := calldataload(start) // number of initializer bytes; zero if read past the end
+            if gt(length, 0xffffffffffffffff) { revert(0, 0) } // keeps `data + length` from wrapping
+            let data := add(start, 32) // where the initializer bytes begin
+            if gt(add(data, length), size) { revert(0, 0) } // must end in the calldata; refuses a far start
+
+            if iszero(extcodesize(implementation)) {
+                // an implementation with no code, or the zero address, is refused
+                mstore(0, shl(224, INVALID_IMPLEMENTATION)) // ERC1967InvalidImplementation(address)
+                mstore(4, implementation) // its argument at 4
+                revert(0, 36) // selector and one 32-byte argument
+            }
+            sstore(IMPLEMENTATION_SLOT, implementation) // install it; the slot is now non-zero, which closes arming
+            log2(0, 0, UPGRADED, implementation) // Upgraded(address indexed implementation), as ERC-1967
+
+            switch length // with or without an initializer
+            case 0 {
+                // no initializer
+                if callvalue() {
+                    // ether would have nowhere to go: refused, as ERC1967Utils does
+                    mstore(0, shl(224, NON_PAYABLE)) // ERC1967NonPayable()
+                    revert(0, 4) // selector only
+                }
+            }
+            default {
+                // run the initializer
+                let ptr := mload(0x40) // free memory, so the copy touches nothing in use
+                calldatacopy(ptr, data, length) // copy the initializer bytes
+                if iszero(delegatecall(gas(), implementation, ptr, length, 0, 0)) {
+                    // run it as this proxy; a failure reverts the whole arming
+                    if iszero(returndatasize()) {
+                        // it reverted with no data
+                        mstore(0, shl(224, FAILED_CALL)) // FailedCall(), so the revert is not silent
+                        revert(0, 4) // selector only
+                    }
+                    returndatacopy(ptr, 0, returndatasize()) // copy its revert data
+                    revert(ptr, returndatasize()) // pass it through unchanged
+                }
+            }
+
+            mstore(0, implementation) // the one data word of Locked
+            log1(0, 32, LOCKED) // Locked(address implementation)
+            return(0, 0) // the arming call returns nothing
+        }
+    }
+}

package/contracts/conduit/ProxyDeployer.sol

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Create2} from "@openzeppelin/contracts/utils/Create2.sol";
+import {Proxy, IProxy} from "./Proxy.sol";
+
+// Where `ProxyDeployer` sits: Arachnid's factory at salt zero, so the same address on every
+// standard EVM chain. A `Predetermined` chain is one whose transceivers were deployed through it
+// (#33). A literal, since a zkSync or Tron registry's compiler would derive another;
+// `ProxyDeployer.t.sol` pins it to solc's build.
+address constant PROXY_DEPLOYER = 0x415DaAF39EB13593a0Fe5E140bc97C4C9a63e116;
+
+/// @notice The CREATE2 salt `ProxyDeployer` deploys under for `deployedBy`'s `salt`, where
+///         `deployedBy` is the account that calls `deploy`.
+/// @dev The caller is hashed in so that nobody else can deploy at a caller's address first
+///      with their own implementation. `ChainRegistry.predictTransceiver` derives with it.
+function proxySalt(address deployedBy, bytes32 salt) pure returns (bytes32) {
+    return keccak256(abi.encode(deployedBy, salt));
+}
+
+/// @title ProxyDeployer
+/// @notice Deploys a `Proxy` and arms it in one call, so a transceiver has no window in
+///         which another caller could install its logic.
+///
+/// @dev Deployed through Arachnid's factory with no constructor arguments, so it has one address
+///      on every standard EVM chain, and every transceiver it deploys for one caller and salt
+///      shares one address too. A `Proxy` makes its deployer its admin, which is why the
+///      proxy cannot be deployed through Arachnid's factory directly: that factory makes no
+///      calls and could never arm it.
+contract ProxyDeployer {
+    event Deployed(address indexed deployedBy, bytes32 salt, address proxy, address implementation);
+
+    function deploy(bytes32 salt, address implementation, bytes calldata data) external returns (address proxy) {
+        proxy = Create2.deploy(0, proxySalt(msg.sender, salt), type(Proxy).creationCode);
+        IProxy(proxy).upgradeInitializeAndLock(implementation, data);
+        emit Deployed(msg.sender, salt, proxy, implementation);
+    }
+
+    function predict(address deployedBy, bytes32 salt) external view returns (address) {
+        return Create2.computeAddress(proxySalt(deployedBy, salt), keccak256(type(Proxy).creationCode));
+    }
+}

package/contracts/conduit/ProxyInitCode.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Proxy} from "./Proxy.sol";
+
+/// @notice `Proxy`'s initcode held by another contract, which returns it to any call, so a
+///         contract that deploys conduits reads it rather than carrying 0.6 KB of it in its own
+///         runtime (#70).
+///
+/// @dev CREATE2 hashes the initcode bytes, not where they were read from, so a conduit deployed
+///      from the loaded copy lands where `PROXY_INIT_CODE_HASH` predicts.
+///
+/// @dev Read by `STATICCALL` rather than `EXTCODECOPY`, which zksolc refuses to compile: every
+///      contract a zkSync variant's imports reach is compiled for EraVM, the plain transceivers
+///      among them.
+library ProxyInitCode {
+    error StoreFailed();
+
+    /// @notice What every CREATE2 prediction of a conduit hashes.
+    function hash() internal pure returns (bytes32) {
+        return keccak256(type(Proxy).creationCode);
+    }
+
+    /// @notice Deploy the code-only contract. `Proxy`'s initcode appears only in the caller's
+    ///         initcode when this runs from a constructor.
+    function store() internal returns (address initCodeStore) {
+        bytes memory initCode = type(Proxy).creationCode;
+        // PUSH2 len, DUP1, PUSH1 12, PUSH1 0, CODECOPY, PUSH1 0, RETURN: on any call, returns what
+        // follows this 12-byte prefix, the initcode.
+        // forge-lint: disable-next-line(unsafe-typecast) a constant 0.6 KB
+        bytes memory runtime = abi.encodePacked(hex"61", uint16(initCode.length), hex"80600c6000396000f3", initCode);
+        // The same prefix shape, 14 bytes with PUSH4: returns `runtime` as the new contract's code.
+        // forge-lint: disable-next-line(unsafe-typecast) a constant 0.6 KB
+        bytes memory creation = abi.encodePacked(hex"63", uint32(runtime.length), hex"80600e6000396000f3", runtime);
+        assembly {
+            initCodeStore := create(0, add(creation, 0x20), mload(creation))
+        }
+        if (initCodeStore == address(0)) revert StoreFailed();
+    }
+
+    /// @notice The initcode `store` kept at `initCodeStore`.
+    function load(address initCodeStore) internal view returns (bytes memory code) {
+        bool ok;
+        (ok, code) = initCodeStore.staticcall("");
+        if (!ok || code.length == 0) revert StoreFailed();
+    }
+}

package/contracts/derivation/AddressDerive.sol

@@ -0,0 +1,326 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Erc7930} from "../addressing/Erc7930.sol";
+
+/// @title AddressDerive
+/// @notice Deterministic address derivation across EVM and non-EVM chains, computed
+///         on-chain inside an Ethereum transaction. Pure where possible, no chain state.
+///
+/// @dev Formerly ForeignCreate2. EVM derivations are now a real path rather than a
+///      test-only comparison, because on an EVM destination the registry can resolve
+///      locally and skip the round trip entirely.
+///
+/// @dev Scope. Everything here bottoms out in `keccak256` (native) or `sha256` (0x02).
+///      Bitcoin's `ripemd160` lives in BitcoinDerive.sol, because
+///      EraVM does not support that precompile and rejects any unit importing it, which a
+///      zkSync transceiver needs this file for. Sui lives in SuiDerive.sol because BLAKE2b needs the
+///      0x09 precompile, which forces `view` rather than `pure`.
+///      Not derivable on the EVM at any price: Aptos/Movement (SHA3-256, ~1e5 gas for
+///      a hand-rolled Keccak-f), Starknet (Pedersen/Poseidon over the STARK curve),
+///      Bitcoin P2TR (secp256k1 point addition). Route those through the `Unique` path.
+library AddressDerive {
+    /* ====================================================================== */
+    /*                                  EVM                                    */
+    /* ====================================================================== */
+
+    /// @notice EIP-1014 CREATE2. The default resolution path.
+    function create2(address deployer, bytes32 salt, bytes32 initCodeHash) internal pure returns (address) {
+        return address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0xff), deployer, salt, initCodeHash)))));
+    }
+
+    /// @notice Nonce-based CREATE, address = keccak256(rlp([deployer, nonce]))[12:].
+    /// @dev RLP has three cases for the nonce and getting them wrong is a classic bug:
+    ///      0 encodes as 0x80 (empty string, not 0x00), 1..127 encode as themselves,
+    ///      and anything larger takes a 0x80+len prefix over minimal big-endian bytes.
+    ///
+    /// @dev The list prefix is `0xc0 + payload`, and the payload grows with the nonce.
+    ///      The address item is always 21 bytes (0x94 plus twenty), and the nonce item is
+    ///      1 byte in the first two arms but `1 + len` in the third, so the prefix is
+    ///      0xd6 in the first two and `0xd6 + len` in the third. It read `0xd5 + len`
+    ///      until `test/CreateDerivation.t.sol` was written. Every nonce at or above 128
+    ///      produced a well-formed address that was not the one Ethereum would use. Only
+    ///      `create3` called this, always with a hardcoded nonce of 1, so nothing
+    ///      exercised the arm. `VmDeriver.Scheme.EvmCreate` takes the nonce from
+    ///      registry params and could have reached it with any value.
+    function create(address deployer, uint256 nonce) internal pure returns (address) {
+        bytes memory rlp;
+        if (nonce == 0) {
+            rlp = abi.encodePacked(bytes1(0xd6), bytes1(0x94), deployer, bytes1(0x80));
+        } else if (nonce <= 0x7f) {
+            // forge-lint: disable-next-line(unsafe-typecast) nonce <= 0x7f in this branch
+            rlp = abi.encodePacked(bytes1(0xd6), bytes1(0x94), deployer, uint8(nonce));
+        } else {
+            // Minimal big-endian, the same rule the eip155 chain reference uses.
+            // Borrowed from `Erc7930` rather than restated: `derivation` imports
+            // `addressing` and never the reverse, so this is the direction the
+            // dependency graph already runs, and one encoder cannot drift from itself.
+            bytes memory n = Erc7930.minimalBigEndian(nonce);
+            // forge-lint: disable-next-line(unsafe-typecast) n is at most 32 bytes
+            uint8 nLen = uint8(n.length);
+            rlp = abi.encodePacked(bytes1(0xd6 + nLen), bytes1(0x94), deployer, bytes1(0x80 + nLen), n);
+        }
+        return address(uint160(uint256(keccak256(rlp))));
+    }
+
+    /// @notice Creation-code hash of an EIP-1167 minimal proxy for `implementation`.
+    /// @dev For a destination whose contracts are EIP-1167 clones, reached through
+    ///      `VmDeriver`'s clone schemes: the address is CREATE2 over the deployer, the salt, and
+    ///      this hash. This protocol's own conduits are `Proxy`, not clones.
+    ///
+    ///      The 55-byte layout is EIP-1167 verbatim: 10 bytes of creation code, then the
+    ///      45-byte runtime with the implementation address spliced in at byte 20:
+    ///        3d602d80600a3d3981f3  363d3d373d3d3d363d73 <impl> 5af43d82803e903d91602b57fd5bf3
+    ///      Verified against OpenZeppelin's `Clones.predictDeterministicAddress` in tests
+    ///      rather than trusted from memory. If OZ ever changes its proxy bytecode, this
+    ///      constant is wrong and the test fails.
+    function cloneInitCodeHash(address implementation) internal pure returns (bytes32) {
+        return keccak256(
+            abi.encodePacked(
+                hex"3d602d80600a3d3981f3363d3d373d3d3d363d73", implementation, hex"5af43d82803e903d91602b57fd5bf3"
+            )
+        );
+    }
+
+    /// @notice Address of an EIP-1167 clone deployed with CREATE2.
+    function clone2(address deployer, address implementation, bytes32 salt) internal pure returns (address) {
+        return create2(deployer, salt, cloneInitCodeHash(implementation));
+    }
+
+    /// @dev Canonical CREATE3 proxy initcode: PUSH8 363d3d37363d34f0; 3d5260086018f3.
+    ///      Constant across the 0xsequence, Solady, and LI.FI variants. Verified by
+    ///      hashing the literal rather than copied from a header file.
+    bytes32 internal constant CREATE3_PROXY_INITCODE_HASH =
+        0x21c35dbe1b344a2488cf3321d6ce542f8e9f305544ff09e4993a62319a497c1f;
+
+    /// @notice CREATE3: address depends only on (factory, salt), never on bytecode.
+    /// @dev Two stages. A fixed-initcode proxy is CREATE2-deployed, then that proxy
+    ///      does a plain CREATE at nonce 1. The nonce is a hardcoded 1 from a fresh
+    ///      contract, not the deployer's transaction history.
+    ///
+    ///      Does not port to zkSync (both stages use different formulas) or to Tron
+    ///      (CREATE derives from root tx id, so stage 2 is not a function of the proxy
+    ///      address). Use only for chains sharing Ethereum's derivation.
+    function create3(address factory, bytes32 salt) internal pure returns (address) {
+        address proxy = create2(factory, salt, CREATE3_PROXY_INITCODE_HASH);
+        return create(proxy, 1);
+    }
+
+    /* ====================================================================== */
+    /*                        L1 -> L2 sender aliasing                         */
+    /* ====================================================================== */
+
+    /// @dev Shared by three stacks, which is why it is not under any of them. Arbitrum,
+    ///      zkSync Era, and the OP Stack's `OptimismPortal` all rewrite the sender of an
+    ///      L1-originated message by the same constant, and Arbitrum's own
+    ///      `AddressAliasHelper.OFFSET` is this value. Filing it under one of them invites
+    ///      the next binding to write a second copy.
+    uint160 internal constant L1_TO_L2_ALIAS_OFFSET = uint160(0x1111000000000000000000000000000000001111);
+
+    /// @notice The address an L1 contract appears as when its message arrives on L2.
+    ///
+    /// @dev Contracts only. An EOA is not aliased, because the collision this prevents is a
+    ///      contract at some address on L1 impersonating a different contract that happens
+    ///      to sit at the same address on L2.
+    function applyL1ToL2Alias(address l1) internal pure returns (address) {
+        unchecked {
+            return address(uint160(l1) + L1_TO_L2_ALIAS_OFFSET);
+        }
+    }
+
+    /// @notice Recover the L1 address from the sender an L2 actually observed.
+    ///
+    /// @dev This is the direction a binding needs, and the one whose absence is a silent bug
+    ///      rather than a revert. `ReceiverBase` compares an inbound sender against
+    ///      `sourceTransmitter`, which holds the transmitter's address on the home chain; an
+    ///      L2 receiver sees that address plus the offset, so every inbound message is
+    ///      refused until the binding subtracts it back out.
+    ///
+    /// @dev It is L1 -> L2 only, and applying it symmetrically corrupts the other direction.
+    ///      A withdrawal carries the raw L2 sender: Arbitrum's `Outbox` hashes `l2Sender`
+    ///      unaliased into the leaf it proves against. So a binding un-aliases on the
+    ///      inbound-to-L2 path and nowhere else.
+    ///
+    /// @dev It cannot tell whether it was needed. The arithmetic wraps, so undoing an alias
+    ///      that was never applied returns a perfectly well-formed address belonging to
+    ///      nobody rather than failing. There is no "was this aliased" predicate and there
+    ///      cannot be one: the caller decides from the direction of the message, never from
+    ///      the value. That is why this is a binding's job and not `ReceiverBase`'s, which
+    ///      cannot know which transport delivered.
+    ///
+    /// @dev Not every binding needs it. The OP Stack's `CrossDomainMessenger` un-aliases
+    ///      internally and reports the original through `xDomainMessageSender()`, so only a
+    ///      binding built directly on `OptimismPortal` has to. Arbitrum and zkSync have no
+    ///      equivalent.
+    function undoL1ToL2Alias(address l2) internal pure returns (address) {
+        unchecked {
+            return address(uint160(l2) - L1_TO_L2_ALIAS_OFFSET);
+        }
+    }
+
+    /* ====================================================================== */
+    /*                             zkSync Era                                  */
+    /* ====================================================================== */
+
+    bytes32 internal constant ZKSYNC_CREATE2_PREFIX = keccak256("zksyncCreate2");
+    bytes32 internal constant ZKSYNC_CREATE_PREFIX = keccak256("zksyncCreate");
+
+    /// @param sender If an L1 *contract* triggers the deploy via Bridgehub/Mailbox, pass
+    ///        the aliased address. EOAs are not aliased.
+    /// @param bytecodeHash EraVM versioned hash: see `hashL2Bytecode`, not keccak(initcode).
+    function zksyncCreate2(address sender, bytes32 salt, bytes32 bytecodeHash, bytes32 constructorInputHash)
+        internal
+        pure
+        returns (address)
+    {
+        return address(
+            uint160(
+                uint256(
+                    keccak256(
+                        abi.encodePacked(
+                            ZKSYNC_CREATE2_PREFIX,
+                            bytes32(uint256(uint160(sender))),
+                            salt,
+                            bytecodeHash,
+                            constructorInputHash
+                        )
+                    )
+                )
+            )
+        );
+    }
+
+    function zksyncCreate(address sender, uint256 nonce) internal pure returns (address) {
+        return address(
+            uint160(
+                uint256(
+                    keccak256(abi.encodePacked(ZKSYNC_CREATE_PREFIX, bytes32(uint256(uint160(sender))), bytes32(nonce)))
+                )
+            )
+        );
+    }
+
+    /// @dev [0]=0x01 version, [1]=0x00, [2:4]=length in words, [4:32]=trailing 28 bytes
+    ///      of sha256(bytecode). Invariants mirror EraVM. Requires zksolc output.
+    function hashL2Bytecode(bytes memory bytecode) internal pure returns (bytes32 h) {
+        require(bytecode.length % 32 == 0, "C2L: not word-aligned");
+        uint256 words = bytecode.length / 32;
+        require(words < 2 ** 16, "C2L: bytecode too long");
+        require(words % 2 == 1, "C2L: even word count");
+        h = sha256(bytecode);
+        h = h & bytes32(uint256(type(uint224).max));
+        h = h | bytes32(uint256(1) << 248);
+        h = h | bytes32(words << 224);
+    }
+
+    /* ====================================================================== */
+    /*                                 Tron                                    */
+    /* ====================================================================== */
+
+    /// @notice Same 85-byte preimage as EIP-1014; only the domain byte differs (0x41).
+    /// @dev Returns the bare 20-byte in-VM form. Prepend 0x41 + Base58Check off-chain.
+    ///      initCodeHash must come from Tron-solc, not solc.
+    ///      java-tron's CREATE2 hashes the sender in its 21-byte form, `0x41 ‖ deployer`
+    ///      (`WalletUtil.generateContractAddress2`), which is where the 0x41 comes from.
+    function tronCreate2(address deployer, bytes32 salt, bytes32 initCodeHash) internal pure returns (address) {
+        return address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0x41), deployer, salt, initCodeHash)))));
+    }
+
+    /* ====================================================================== */
+    /*                          Cosmos / CosmWasm                              */
+    /* ====================================================================== */
+
+    /// @dev sha256("module"), the ADR-028 domain tag.
+    bytes32 internal constant COSMOS_MODULE_TAG = 0x120970d812836f19888625587a4606a5ad23cef31c8684e601771552548fc6b9;
+
+    /// @notice CosmWasm Instantiate2: the CREATE2 analogue on Cosmos.
+    /// @dev sha256( sha256("module") ++ key ), key = "wasm\0" ++ be64/value pairs.
+    ///      The "wasm\0" prefix exists in cosmwasm-std but is absent from the published
+    ///      spec page. Verified against cosmwasm-std's own test vectors.
+    /// @param creator Canonical decoded address bytes, not the bech32 string.
+    function cosmosInstantiate2(bytes32 checksum, bytes memory creator, bytes memory salt, bytes memory initMsg)
+        internal
+        pure
+        returns (bytes32)
+    {
+        require(salt.length >= 1 && salt.length <= 64, "C2L: bad salt len");
+        // Each variable field is length-prefixed, and a memory length fits in 64 bits.
+        // forge-lint: disable-start(encode-packed-collision,unsafe-typecast)
+        bytes memory key = abi.encodePacked(
+            hex"7761736d00", // "wasm\0"
+            uint64(32),
+            checksum,
+            uint64(creator.length),
+            creator,
+            uint64(salt.length),
+            salt,
+            uint64(initMsg.length),
+            initMsg
+        );
+        // forge-lint: disable-end(encode-packed-collision,unsafe-typecast)
+        return sha256(abi.encodePacked(COSMOS_MODULE_TAG, key));
+    }
+
+    /* ====================================================================== */
+    /*                                Solana                                   */
+    /* ====================================================================== */
+
+    /// @notice PDA for a known bump.
+    /// @dev This is not `find_program_address`. The canonical PDA is the first bump
+    ///      counting down from 255 whose output is off the ed25519 curve; that check
+    ///      needs Edwards decompression over GF(2^255-19) and is not implemented.
+    ///      A too-high bump yields an on-curve point this function will happily return.
+    ///      Bind the bump into committed inputs so signers approve it explicitly.
+    function solanaCreateProgramAddress(bytes[] memory seeds, uint8 bump, bytes32 programId)
+        internal
+        pure
+        returns (bytes32)
+    {
+        require(seeds.length <= 16, "C2L: too many seeds");
+        bytes memory pre;
+        for (uint256 i; i < seeds.length; ++i) {
+            require(seeds[i].length <= 32, "C2L: seed too long");
+            // forge-lint: disable-next-line(encode-packed-collision) Solana's PDA preimage is the bare concatenation
+            pre = abi.encodePacked(pre, seeds[i]);
+        }
+        return sha256(abi.encodePacked(pre, bump, programId, "ProgramDerivedAddress"));
+    }
+
+    /// @notice SPL Associated Token Account.
+    /// @dev Seed order is [owner, tokenProgram, mint]: the token program sits in the
+    ///      middle, which is easy to get backwards. Verified against solders.
+    function solanaAssociatedTokenAccount(
+        bytes32 owner,
+        bytes32 mint,
+        bytes32 tokenProgram,
+        bytes32 ataProgram,
+        uint8 bump
+    ) internal pure returns (bytes32) {
+        return sha256(abi.encodePacked(owner, tokenProgram, mint, bump, ataProgram, "ProgramDerivedAddress"));
+    }
+
+    /// @notice SystemProgram::createWithSeed. No bump, no off-curve requirement.
+    function solanaCreateWithSeed(bytes32 base, bytes memory seed, bytes32 programId) internal pure returns (bytes32) {
+        return sha256(abi.encodePacked(base, seed, programId));
+    }
+
+    /* ====================================================================== */
+    /*                                 NEAR                                    */
+    /* ====================================================================== */
+
+    /// @notice NEAR deterministic account: NEAR's CREATE2, and free here since it
+    ///         uses keccak256. Render as "0s" + lowercase hex, not "0x".
+    /// @param borshStateInit Borsh-serialized DeterministicAccountStateInit. Serialize
+    ///        off-chain; do not build Borsh in Solidity.
+    function nearDeterministicAccount(bytes memory borshStateInit) internal pure returns (bytes20) {
+        // forge-lint: disable-next-line(unsafe-typecast) the address is the hash's low 20 bytes
+        return bytes20(uint160(uint256(keccak256(borshStateInit))));
+    }
+
+    /// @param uncompressedPubkey64 64 bytes, without the 0x04 SEC1 prefix.
+    function nearEthImplicitAccount(bytes memory uncompressedPubkey64) internal pure returns (bytes20) {
+        require(uncompressedPubkey64.length == 64, "C2L: bad pubkey len");
+        // forge-lint: disable-next-line(unsafe-typecast) the address is the hash's low 20 bytes
+        return bytes20(uint160(uint256(keccak256(uncompressedPubkey64))));
+    }
+}

package/contracts/derivation/BitcoinDerive.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @title BitcoinDerive
+/// @notice Bitcoin script and witness-program hashing, for `bip122` references.
+///
+/// @dev Split out of `AddressDerive` to keep `ripemd160` off EraVM, and that is a compile
+///      constraint rather than a taste one. zkSync's compiler rejects the `ripemd160`
+///      precompile outright, and it rejects the whole compilation unit rather than the
+///      unreachable function: a zkSync transceiver needs `AddressDerive.zksyncCreate2` and would
+///      otherwise drag `hash160` in with it and fail to build. Nothing else separated these,
+///      since both halves are "hash bytes with a precompile".
+///
+/// @dev Nothing on a destination calls this. Bitcoin has no executor and no receiver: `bip122`
+///      appears in the registry as a reference that can be validated and addressed, never
+///      as a destination a payload runs on. Its only caller is `VmDeriver`, which nothing
+///      deployed on EraVM imports, so `VmDeriver` cannot be built for EraVM either.
+library BitcoinDerive {
+    /// @notice HASH160 = ripemd160(sha256(x)). P2PKH and P2WPKH witness programs.
+    function hash160(bytes memory data) internal pure returns (bytes20) {
+        return ripemd160(abi.encodePacked(sha256(data)));
+    }
+
+    /// @notice P2WSH witness program = sha256(witnessScript).
+    function p2wshProgram(bytes memory witnessScript) internal pure returns (bytes32) {
+        return sha256(witnessScript);
+    }
+
+    /// @notice P2SH script hash = hash160(redeemScript).
+    function p2shScriptHash(bytes memory redeemScript) internal pure returns (bytes20) {
+        return hash160(redeemScript);
+    }
+}