@crossecute/protocol 0.0.0 → 0.1.0

package/contracts/registry/IChainRegistryRefs.sol

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Provenance} from "./Provenance.sol";
+
+/// @notice The CREATE2 inputs a message provider's contracts share on every chain.
+///
+/// @dev The caller that deploys a transceiver is per (provider, chain), held by the registry: one
+///      salt and caller put a transceiver at one address, and a rotated deployer moves only the
+///      chains added after it. The salt can be mined for leading zero bytes, which are cheaper in
+///      the calldata that names the address.
+struct ProviderDeployment {
+    /// The mined salt every deployer passes to `ProxyDeployer.deploy`.
+    bytes32 salt;
+    /// keccak256 of `Proxy`'s initcode as solc builds it: transceivers and conduits are
+    /// both `Proxy`. Recorded rather than computed, since a zkSync or Tron registry's
+    /// own compiler builds a different one.
+    bytes32 proxyInitCodeHash;
+}
+
+/// @notice Whether sends may reach a provider's transceiver on a chain.
+/// @dev `Pending` is recorded and predicted but not sent to; `Live` is set by the registry's owner
+///      once the deployment there was checked independently of the deployer.
+enum Status {
+    None,
+    Pending,
+    Live
+}
+
+/// @notice The slice of `ChainRegistry` a transceiver needs: where remote things live, and how
+///         much each claim about them is worth.
+///
+/// @dev Routes live on the transceiver. What it reads here is provenance, suspension, derived
+///      counterpart addresses, location validation, and which chains must report their
+///      receivers.
+interface IChainRegistryRefs {
+    /// @notice What an address claim about `chainKey` is worth. Chain-scoped, so every
+    ///         provider's transceiver reads the same answer.
+    function provenanceFor(bytes32 chainKey) external view returns (Provenance);
+
+    /// @notice Whether every transceiver on this chain refuses `chainKey`.
+    function isSuspended(bytes32 chainKey) external view returns (bool);
+
+    /// @notice The transceiver address this registry recomputes for `chainKey`, from the
+    ///         deriver and inputs recorded for that chain. A transceiver stores the result.
+    function expectedTransceiver(bytes32 chainKey) external view returns (bytes memory);
+
+    /// @notice The CREATE2 inputs `messageProvider`'s contracts share; a zero salt means none is
+    ///         recorded.
+    function providerDeployment(bytes32 messageProvider) external view returns (ProviderDeployment memory);
+
+    /// @notice Where a provider's transceiver lands on `chainKey`, recomputed from the recorded
+    ///         factory, that chain's deployer, salt, and initcode hash. Reverts for a chain not
+    ///         graded `Predetermined`, and for one the provider was never added on.
+    function predictTransceiver(bytes32 chainKey, bytes32 messageProvider) external view returns (address);
+
+    /// @notice Whether sends to `messageProvider`'s transceiver on `chainKey` are allowed.
+    function isLive(bytes32 chainKey, bytes32 messageProvider) external view returns (bool);
+
+    /// @notice Who deployed, or will deploy, `messageProvider`'s transceiver on `chainKey`; zero
+    ///         where it was never added.
+    function deployedBy(bytes32 chainKey, bytes32 messageProvider) external view returns (address);
+
+    /// @notice The deployer a provider added on a chain from now on is recorded under.
+    function currentDeployer() external view returns (address);
+
+    /// @notice The canonical ERC-7930 chain identifier `chainKey` hashes from.
+    function chainIdentifier(bytes32 chainKey) external view returns (bytes memory);
+
+    /// @notice Reverts unless `interop` is a well-formed address on `chainKey`.
+    function validateLocation(bytes32 chainKey, bytes calldata interop) external view;
+
+    /// @notice The derivation inputs recorded for `chainKey`. Hash this to build the
+    ///         `paramsCommitment` a `resolveCounterpart` transaction must carry.
+    function deriveParams(bytes32 chainKey) external view returns (bytes memory);
+
+    /// @notice Whether conduits on `chainKey` must report their own address home, which is
+    ///         the only thing this directory says about receivers. Where one actually landed
+    ///         is held by the transmitter that sends to it.
+    function requiresReceiverCallback(bytes32 chainKey) external view returns (bool);
+}

package/contracts/registry/ICommitmentScheme.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @title ICommitmentScheme
+/// @notice A chain's commitment hash primitive, for previewing a commitment on this chain.
+///
+/// @dev The plugin supplies the primitive and `SchemeFold` performs the fold, so a wrong or
+///      hostile plugin can yield a digest the destination refuses but cannot change a
+///      commitment's shape. Nothing on the execution path reads it: a receiver enforces the
+///      fold compiled into `ReceiverBase`.
+///
+/// @dev `view`, not `pure`: Blake2b-256 calls the EIP-152 precompile through `staticcall`.
+interface ICommitmentScheme {
+    /// @notice The destination's hash of `data`.
+    /// @dev Must be the primitive the destination's receiver applies, checked against a test
+    ///      corpus. A mismatch leaves an approval outstanding until a `cancel` crosses.
+    function hash(bytes calldata data) external view returns (bytes32);
+}
+
+/// @title SchemeFold
+/// @notice The commitment fold over a plugin's primitive.
+/// @dev A second copy of `Commitment.hashCalls`'s fold. They cannot share code: `messaging`
+///      imports `registry`, and the primitive is an enum arm in one and an external call in
+///      the other. `test/CommitmentSchemePlugin.t.sol` pins the two equal for every enum
+///      primitive.
+library SchemeFold {
+    /// @dev Same selector as `Commitment.EmptyCommitment`.
+    error EmptyCommitment();
+
+    /// @notice The commitment `scheme`'s chain will require over `elements`.
+    /// @dev Seeded with the chainKey, so no plugin can bind a commitment to another chain. An
+    ///      empty array reverts, as in `Commitment`, before the plugin is called.
+    function hashCalls(ICommitmentScheme scheme, bytes32 destinationChainKey, bytes[] memory elements)
+        internal
+        view
+        returns (bytes32 hashed)
+    {
+        uint256 len = elements.length;
+        if (len == 0) revert EmptyCommitment();
+        hashed = scheme.hash(abi.encode(destinationChainKey));
+        for (uint256 i = 0; i < len; i++) {
+            // forge-lint: disable-next-line(calls-loop) an owner-registered scheme
+            hashed = scheme.hash(abi.encodePacked(hashed, scheme.hash(elements[i])));
+        }
+    }
+}

package/contracts/registry/IRefValidator.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @title IRefValidator
+/// @notice The registry's per-chain value-range check on an address.
+/// @dev ERC-7930 fixes structure, not ranges: `parseStrict` accepts 32 canonical bytes but
+///      cannot reject a Starknet address above `L2_ADDRESS_UPPER_BOUND`. Set per chainKey by
+///      `ChainRegistry.setValidator`.
+interface IRefValidator {
+    /// @param interop Canonical ERC-7930 bytes, already structurally parsed.
+    /// @dev Reverts to reject. Called by `ChainRegistry.validateLocation`.
+    function validateRef(bytes calldata interop) external view;
+}

package/contracts/registry/Provenance.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice How much this chain can know about an address on another one.
+///
+/// @dev Grades a chain, not a stored value: every provider's transceiver reads the same answer
+///      from `ChainRegistry.provenanceFor`, so two transceivers cannot disagree about one chain.
+///
+/// @dev Ordered by strength. `Predetermined`: this chain can recompute the address from inputs in a
+///      signed transaction, because that chain's transceivers were deployed through
+///      `ProxyDeployer`, which Arachnid's factory puts at one address, and this chain's
+///      transceiver knows where: from the registry's prediction, the provider's salt under the
+///      deployer recorded for that chain. `Unique`: it cannot, so
+///      the value came over a bridge and is worth that bridge's security. A chain without
+///      Arachnid's factory shares no address with any other, so it is `Unique` in every registry
+///      and grades every other chain `Unique` in its own (#33).
+///
+/// @dev Checks are ordinal comparisons against a bar, and the registry's grades and a
+///      transceiver's `minCounterpartProvenance` persist in storage. Inserting a grade
+///      renumbers every stored value above it after deployment: append, or migrate.
+enum Provenance {
+    Unknown,
+    Unique,
+    Predetermined
+}

package/contracts/schemes/Blake2bScheme.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Blake2b256} from "../derivation/Blake2b256.sol";
+import {ICommitmentScheme} from "../registry/ICommitmentScheme.sol";
+
+/// @title Blake2bScheme
+/// @notice Cardano's primitive. `Scheme.Blake2b256Scheme` in the enum the frozen
+///         transmitters carry.
+/// @dev The one that costs `pure`. `Blake2b256` reaches the EIP-152 precompile at 0x09
+///      through `staticcall`, which Solidity forbids inside `pure`, so this member is
+///      why `ICommitmentScheme.hash` is `view`, exactly as it is why the library's
+///      scheme-parameterized overloads are.
+contract Blake2bScheme is ICommitmentScheme {
+    function hash(bytes calldata data) external view override returns (bytes32) {
+        return Blake2b256.hash(data);
+    }
+}

package/contracts/schemes/KeccakScheme.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ICommitmentScheme} from "../registry/ICommitmentScheme.sol";
+
+/// @title KeccakScheme
+/// @notice The primitive every EVM destination uses, plus Solana, Aptos, Sui, NEAR, and
+///         Cosmos. `Scheme.Keccak256` in the enum the frozen transmitters carry.
+///
+/// @dev It exists to be the control. An EVM chain never needs the plugin path: its
+///      receiver enforces with the keccak fold compiled into `ReceiverBase`. Registering
+///      this one anyway means `ChainRegistry.commitmentFor` can be checked against
+///      `Commitment.hashCalls` for the same inputs, which is the assertion that the
+///      plugin seam reproduces the frozen path rather than merely resembling it.
+contract KeccakScheme is ICommitmentScheme {
+    function hash(bytes calldata data) external pure override returns (bytes32) {
+        return keccak256(data);
+    }
+}

package/contracts/schemes/Sha256Scheme.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {ICommitmentScheme} from "../registry/ICommitmentScheme.sol";
+
+/// @title Sha256Scheme
+/// @notice TON's primitive. `Scheme.Sha256` in the enum the frozen transmitters carry.
+/// @dev `sha256` is an EVM builtin (precompile 0x02, wrapped by the compiler), so this
+///      stays computable on both sides, which is why TON was expressible from the start
+///      while Starknet was not.
+contract Sha256Scheme is ICommitmentScheme {
+    function hash(bytes calldata data) external pure override returns (bytes32) {
+        return sha256(data);
+    }
+}

package/contracts/treasury/Treasury.sol

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+/// @notice A transceiver's report float, which leaves only at its treasury's call.
+interface IReportFloat {
+    function withdraw(uint256 amount) external;
+}
+
+/// @title Treasury
+/// @notice Where a chain's outbound fees, bootstrap fees and report float land, and the one contract that can
+///         move them out.
+///
+/// @dev A destination, not an authority: it configures nothing and reaches no conduit. Its one
+///      outgoing call pulls a transceiver's float, which can only come here. Its owner decides
+///      where funds go next; each transceiver's write-once `treasury` decides where they arrive,
+///      so a compromised withdrawal path cannot redirect fees at the source.
+///
+/// @dev One per chain, shared by every provider there. Each transceiver names it once, at
+///      initialization, so a replacement would receive no fees or floats from transceivers
+///      already deployed: this one serves them for their whole life.
+contract Treasury is Ownable {
+    using SafeERC20 for IERC20;
+
+    /// @notice Native currency left this treasury.
+    event NativeWithdrawn(address indexed to, uint256 amount);
+
+    /// @notice An ERC-20 balance left this treasury.
+    event TokenWithdrawn(address indexed token, address indexed to, uint256 amount);
+
+    /// @notice A transceiver's report float was pulled in.
+    event FloatCollected(address indexed from, uint256 amount);
+
+    /// @dev A withdrawal to the zero address would burn the balance.
+    error ZeroRecipient();
+
+    /// @dev The native transfer failed; carries the recipient's revert reason.
+    error NativeTransferFailed(address to, uint256 amount, bytes reason);
+
+    constructor(address initialOwner) Ownable(initialOwner) {}
+
+    /// @notice Accept the fees transmitters and transceivers collect with a plain `call`.
+    receive() external payable {}
+
+    /// @notice Pull `amount` of a transceiver's report float into this treasury.
+    /// @dev The transceiver pays only its treasury, so the owner chooses when, not where.
+    function collect(IReportFloat from, uint256 amount) external onlyOwner {
+        emit FloatCollected(address(from), amount);
+        from.withdraw(amount);
+    }
+
+    /// @notice Send `amount` of native currency to `to`.
+    function withdraw(address to, uint256 amount) external onlyOwner {
+        if (to == address(0)) revert ZeroRecipient();
+
+        // `call`, not `transfer`: a msig recipient needs more than the 2300-gas stipend, and
+        // there is no state here for a re-entrant call to confuse.
+        emit NativeWithdrawn(to, amount);
+
+        (bool ok, bytes memory reason) = to.call{value: amount}("");
+        if (!ok) revert NativeTransferFailed(to, amount, reason);
+    }
+
+    /// @notice Send `amount` of `token` to `to`.
+    /// @dev `SafeERC20` for tokens such as USDT whose `transfer` returns nothing.
+    function withdrawERC20(IERC20 token, address to, uint256 amount) external onlyOwner {
+        if (to == address(0)) revert ZeroRecipient();
+
+        token.safeTransfer(to, amount);
+
+        emit TokenWithdrawn(address(token), to, amount);
+    }
+}

package/contracts/validators/MoveValidator.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Move} from "../addressing/Move.sol";
+import {Erc7930} from "../addressing/Erc7930.sol";
+import {IRefValidator} from "../registry/IRefValidator.sol";
+
+/// @title MoveValidator
+/// @notice Per-chain validator for Move references.
+/// @dev Enforces the fixed 32-byte address width. Move addresses have a short display
+///      form (`0x1` and the zero-padded 32-byte form are the same address, AIP-40),
+///      which has caused real production bugs. Accepting a short form here would give
+///      one address two distinct registry keys, so anything but 32 bytes is rejected.
+contract MoveValidator is IRefValidator {
+    function validateRef(bytes calldata interop) external pure override {
+        Erc7930.Interop memory io = Erc7930.parseStrict(interop);
+        if (!Move.isMoveChain(io.chainType)) revert Move.NotMoveChain();
+        // Zero-length address is a Chain Identifier, which has no address to check.
+        if (io.addr.length == 0) return;
+        if (io.addr.length != Move.MOVE_ADDRESS_BYTES) {
+            revert Move.BadMoveAddressLength();
+        }
+    }
+}

package/contracts/validators/StarknetValidator.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {StarknetDerive} from "../derivation/StarknetDerive.sol";
+import {Erc7930} from "../addressing/Erc7930.sol";
+import {IRefValidator} from "../registry/IRefValidator.sol";
+
+/// @title StarknetValidator
+/// @notice Rejects Starknet references whose address is a well-formed 32-byte value
+///         that no Starknet contract can ever occupy.
+/// @dev This is the constraint the 7930 envelope structurally cannot catch: length is
+///      correct, framing is canonical, and the value is still impossible.
+contract StarknetValidator is IRefValidator {
+    function validateRef(bytes calldata interop) external pure override {
+        Erc7930.Interop memory io = Erc7930.parseStrict(interop);
+        // A zero-length address is a Chain Identifier, which has no felt to bound.
+        if (io.addr.length == 0) return;
+        StarknetDerive.validateAddress(StarknetDerive.toFelt(io.addr));
+    }
+}

package/package.json

@@ -1,7 +1,38 @@
 {
   "name": "@crossecute/protocol",
-  "version": "0.0.0",
-  "description": "Placeholder that reserves the name. Releases are published from CI with provenance.",
+  "version": "0.1.0",
+  "description": "Crossecute protocol interfaces, libraries and ABIs for integrators",
   "license": "MIT",
-  "files": ["README.md"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crossecute/protocol.git",
+    "directory": "contracts/evm/npm"
+  },
+  "type": "module",
+  "exports": {
+    "./abi": {
+      "types": "./abi/index.d.ts",
+      "default": "./abi/index.js"
+    },
+    "./abi/*.json": "./abi/*.json",
+    "./contracts/*": "./contracts/*"
+  },
+  "files": [
+    "abi",
+    "contracts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "cd .. && forge build && node npm/pack.mjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@openzeppelin/contracts": "5.4.0",
+    "@openzeppelin/contracts-upgradeable": "5.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@openzeppelin/contracts-upgradeable": {
+      "optional": true
+    }
+  }
 }