@crossecute/sdk 0.0.0 → 0.1.1

package/contracts/PlanJson.sol

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {Vm} from "forge-std/Vm.sol";
+import {Call} from "@crossecute/protocol/messaging/Call.sol";
+import {HomeCall, Batch, Plan, SafeTx} from "./Types.sol";
+
+/// @title PlanJson
+/// @notice The two files a plan is written as. Integers are decimal strings so no reader
+///         rounds a wei amount through a float.
+library PlanJson {
+    Vm private constant vm = Vm(address(uint160(uint256(keccak256("hevm cheat code")))));
+
+    string internal constant PLAN_VERSION = "crossecute-plan/1";
+
+    /// @notice The Safe Transaction Builder format, bound to the owner Safe by
+    ///         `meta.createdFromSafeAddress`.
+    function safeBatch(Plan memory plan) internal pure returns (string memory json) {
+        json = string.concat(
+            '{"version":"1.0","chainId":"',
+            vm.toString(plan.homeChainId),
+            '","createdAt":0,"meta":{"name":"crossecute","description":"","createdFromSafeAddress":"',
+            vm.toString(plan.owner),
+            '"},"transactions":',
+            _homeCalls(plan.calls, true),
+            "}"
+        );
+    }
+
+    function planFile(Plan memory p) internal pure returns (string memory json) {
+        json = string.concat(
+            '{"version":"',
+            PLAN_VERSION,
+            '","homeChainId":"',
+            vm.toString(p.homeChainId),
+            '","owner":"',
+            vm.toString(p.owner),
+            '","transmitter":"',
+            vm.toString(p.transmitter),
+            '","fee":"',
+            vm.toString(p.fee),
+            '","calls":',
+            _homeCalls(p.calls, false),
+            ',"batches":['
+        );
+        for (uint256 i; i < p.batches.length; ++i) {
+            json = string.concat(json, i == 0 ? "" : ",", _batch(p.batches[i]));
+        }
+        json = string.concat(json, "]}");
+    }
+
+    /// @notice Safe EIP-712 typed data in the field order Forge Attest's `safe-eip712` reader
+    ///         requires for its default profile.
+    function safeTxTypedData(uint256 chainId, address safe, SafeTx memory t) internal pure returns (string memory) {
+        return string.concat(
+            '{"types":{"EIP712Domain":[{"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}],',
+            '"SafeTx":[{"name":"to","type":"address"},{"name":"value","type":"uint256"},{"name":"data","type":"bytes"},',
+            '{"name":"operation","type":"uint8"},{"name":"safeTxGas","type":"uint256"},{"name":"baseGas","type":"uint256"},',
+            '{"name":"gasPrice","type":"uint256"},{"name":"gasToken","type":"address"},{"name":"refundReceiver","type":"address"},',
+            '{"name":"nonce","type":"uint256"}]},"primaryType":"SafeTx","domain":{"chainId":"',
+            vm.toString(chainId),
+            '","verifyingContract":"',
+            vm.toString(safe),
+            '"},"message":',
+            _safeTxMessage(t),
+            "}"
+        );
+    }
+
+    function _safeTxMessage(SafeTx memory t) private pure returns (string memory) {
+        return string.concat(
+            string.concat(
+                '{"to":"',
+                vm.toString(t.to),
+                '","value":"',
+                vm.toString(t.value),
+                '","data":"',
+                vm.toString(t.data),
+                '","operation":"',
+                vm.toString(t.operation),
+                '","safeTxGas":"',
+                vm.toString(t.safeTxGas)
+            ),
+            string.concat(
+                '","baseGas":"',
+                vm.toString(t.baseGas),
+                '","gasPrice":"',
+                vm.toString(t.gasPrice),
+                '","gasToken":"',
+                vm.toString(t.gasToken),
+                '","refundReceiver":"',
+                vm.toString(t.refundReceiver),
+                '","nonce":"',
+                vm.toString(t.nonce),
+                '"}'
+            )
+        );
+    }
+
+    /// @param builder Adds the Transaction Builder's `operation` field.
+    function _homeCalls(HomeCall[] memory calls, bool builder) private pure returns (string memory json) {
+        json = "[";
+        for (uint256 i; i < calls.length; ++i) {
+            json = string.concat(
+                json,
+                i == 0 ? "" : ",",
+                '{"to":"',
+                vm.toString(calls[i].to),
+                '","value":"',
+                vm.toString(calls[i].value),
+                '","data":"',
+                vm.toString(calls[i].data),
+                builder ? '","operation":"0"}' : '"}'
+            );
+        }
+        json = string.concat(json, "]");
+    }
+
+    function _batch(Batch memory b) private pure returns (string memory json) {
+        json = string.concat(
+            '{"chainId":"',
+            vm.toString(b.chainId),
+            '","receiver":"',
+            vm.toString(b.receiver),
+            '","bootstrap":',
+            b.bootstrap ? "true" : "false",
+            ',"gasUsed":"',
+            vm.toString(b.gasUsed),
+            '","attributes":['
+        );
+        for (uint256 i; i < b.attributes.length; ++i) {
+            json = string.concat(json, i == 0 ? '"' : ',"', vm.toString(b.attributes[i]), '"');
+        }
+        json = string.concat(json, '],"calls":', _calls(b.calls), "}");
+    }
+
+    function _calls(Call[] memory calls) private pure returns (string memory json) {
+        json = "[";
+        for (uint256 i; i < calls.length; ++i) {
+            json = string.concat(
+                json,
+                i == 0 ? "" : ",",
+                '{"target":"',
+                vm.toString(calls[i].target),
+                '","value":"',
+                vm.toString(calls[i].value),
+                '","data":"',
+                vm.toString(calls[i].data),
+                '"}'
+            );
+        }
+        json = string.concat(json, "]");
+    }
+}

package/contracts/SafeTxHash.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {SafeTx} from "./Types.sol";
+
+/// @notice Safe's EIP-712 hashes for Safe 1.3.0 and later, whose domain is the chain id and the
+///         Safe's address.
+library SafeTxHash {
+    bytes32 internal constant DOMAIN_TYPEHASH = keccak256("EIP712Domain(uint256 chainId,address verifyingContract)");
+    bytes32 internal constant SAFE_TX_TYPEHASH = keccak256(
+        "SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce)"
+    );
+
+    function domainSeparator(uint256 chainId, address safe) internal pure returns (bytes32) {
+        return keccak256(abi.encode(DOMAIN_TYPEHASH, chainId, safe));
+    }
+
+    function structHash(SafeTx memory t) internal pure returns (bytes32) {
+        return keccak256(
+            abi.encode(
+                SAFE_TX_TYPEHASH,
+                t.to,
+                t.value,
+                keccak256(t.data),
+                t.operation,
+                t.safeTxGas,
+                t.baseGas,
+                t.gasPrice,
+                t.gasToken,
+                t.refundReceiver,
+                t.nonce
+            )
+        );
+    }
+
+    function hash(uint256 chainId, address safe, SafeTx memory t) internal pure returns (bytes32) {
+        return keccak256(abi.encodePacked(hex"1901", domainSeparator(chainId, safe), structHash(t)));
+    }
+}

package/contracts/Types.sol

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {Call} from "@crossecute/protocol/messaging/Call.sol";
+
+/// @notice A call the conduit's owner makes on the home chain.
+struct HomeCall {
+    address to;
+    uint256 value;
+    bytes data;
+}
+
+/// @notice One ordered batch for the conduit's receiver on one EVM destination, as simulated.
+struct Batch {
+    uint256 chainId;
+    address receiver;
+    Call[] calls;
+    bytes[] attributes;
+    /// Gas the calls used in simulation, excluding the receiver's own delivery overhead.
+    uint256 gasUsed;
+    /// Whether the batch is sent as the destination's bootstrap rather than a message.
+    bool bootstrap;
+}
+
+/// @notice What the owner signs or sends on the home chain, and the batches it carries.
+struct Plan {
+    uint256 homeChainId;
+    address owner;
+    address transmitter;
+    /// The quoted total of every call's fee. `calls[0].value` tops the transmitter up to cover
+    /// it with the script's buffer.
+    uint256 fee;
+    HomeCall[] calls;
+    Batch[] batches;
+}
+
+/// @notice Safe's EIP-712 `SafeTx`, in its field order. `operation` is 0 for CALL, 1 for
+///         DELEGATECALL.
+struct SafeTx {
+    address to;
+    uint256 value;
+    bytes data;
+    uint8 operation;
+    uint256 safeTxGas;
+    uint256 baseGas;
+    uint256 gasPrice;
+    address gasToken;
+    address refundReceiver;
+    uint256 nonce;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { formatEther } from "viem";
+import { checkPlan, parsePlan } from "./plan.js";
+import { checkSafeTx, parseSafeTxTypedData, safeTxHashes } from "./safeTx.js";
+const usage = `usage: crossecute check <plan.json> [safe-tx.json]
+
+Checks the plan's calls against its batches and, given the Safe transaction's typed data,
+that it carries exactly those calls. Prints the hashes a signer's device shows.
+
+The SDK holds no keys and sends nothing. Sign and propose with Forge Attest
+(./attest.sh --attest -- --ledger) or cast wallet sign --data --from-file <safe-tx.json>.`;
+function main([command, planPath, safeTxPath]) {
+    if (command !== "check" || !planPath)
+        throw new Error(usage);
+    const plan = parsePlan(readFileSync(planPath, "utf8"));
+    checkPlan(plan);
+    console.log(`plan for Safe ${plan.owner} on chain ${plan.homeChainId}: ${plan.calls.length} call(s), ` +
+        `fee ${formatEther(plan.fee)}, top-up ${formatEther(plan.calls[0].value)}`);
+    for (const b of plan.batches) {
+        console.log(`  chain ${b.chainId}: ${b.bootstrap ? "bootstrap" : "message"} with ${b.calls.length} call(s) to ${b.receiver}`);
+    }
+    if (!safeTxPath)
+        return;
+    const envelope = parseSafeTxTypedData(readFileSync(safeTxPath, "utf8"));
+    checkSafeTx(plan, envelope);
+    const { domainHash, messageHash, safeTxHash } = safeTxHashes(envelope);
+    console.log(`Safe transaction at nonce ${envelope.tx.nonce}${envelope.tx.operation === 1 ? " through MultiSendCallOnly" : ""}`);
+    console.log(`  domain hash:  ${domainHash}`);
+    console.log(`  message hash: ${messageHash}`);
+    console.log(`  safeTxHash:   ${safeTxHash}`);
+}
+try {
+    main(process.argv.slice(2));
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}

package/dist/encoding.d.ts

@@ -0,0 +1,17 @@
+import { type Address, type Hex } from "viem";
+/** One call in a payload: the ERC-7579 `Execution` tuple the protocol's `Call` uses. */
+export type Call = {
+    target: Address;
+    value: bigint;
+    data: Hex;
+};
+/** `Erc7930.encodeEvmChain`: an eip155 chain identifier with no address. */
+export declare function encodeEvmChain(chainId: bigint): Hex;
+/** `Erc7930.encodeEvm`: an account on an eip155 chain. */
+export declare function encodeEvm(chainId: bigint, account: Address): Hex;
+/** `ChainKey.forEvm`. */
+export declare function chainKey(chainId: bigint): Hex;
+/** `Payload.encodeCalls`: the wire bytes an EVM receiver decodes. */
+export declare function encodeCalls(calls: readonly Call[]): Hex;
+/** `Payload.encodeBootstrap`. */
+export declare function encodeBootstrap(destinationChainIdentifier: Hex, body: Hex): Hex;

package/dist/encoding.js

@@ -0,0 +1,48 @@
+import { concat, encodeAbiParameters, keccak256, numberToHex } from "viem";
+const VERSION_1 = "0x0001";
+const CT_EIP155 = "0x0000";
+/** The chain id as a minimal big-endian integer, as ERC-7930's eip155 profile requires. */
+function chainRef(chainId) {
+    if (chainId <= 0n)
+        throw new Error(`chain id must be positive: ${chainId}`);
+    const hex = chainId.toString(16);
+    return `0x${hex.length % 2 ? "0" : ""}${hex}`;
+}
+function lengthByte(bytes) {
+    const length = (bytes.length - 2) / 2;
+    if (length > 255)
+        throw new Error("ERC-7930 field longer than 255 bytes");
+    return numberToHex(length, { size: 1 });
+}
+/** `Erc7930.encodeEvmChain`: an eip155 chain identifier with no address. */
+export function encodeEvmChain(chainId) {
+    const ref = chainRef(chainId);
+    return concat([VERSION_1, CT_EIP155, lengthByte(ref), ref, "0x00"]);
+}
+/** `Erc7930.encodeEvm`: an account on an eip155 chain. */
+export function encodeEvm(chainId, account) {
+    const ref = chainRef(chainId);
+    return concat([VERSION_1, CT_EIP155, lengthByte(ref), ref, "0x14", account.toLowerCase()]);
+}
+/** `ChainKey.forEvm`. */
+export function chainKey(chainId) {
+    return keccak256(encodeEvmChain(chainId));
+}
+const callsType = [
+    {
+        type: "tuple[]",
+        components: [
+            { name: "target", type: "address" },
+            { name: "value", type: "uint256" },
+            { name: "data", type: "bytes" },
+        ],
+    },
+];
+/** `Payload.encodeCalls`: the wire bytes an EVM receiver decodes. */
+export function encodeCalls(calls) {
+    return encodeAbiParameters(callsType, [calls]);
+}
+/** `Payload.encodeBootstrap`. */
+export function encodeBootstrap(destinationChainIdentifier, body) {
+    return encodeAbiParameters([{ type: "bytes" }, { type: "bytes" }], [destinationChainIdentifier, body]);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./encoding.js";
+export * from "./plan.js";
+export * from "./safeTx.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./encoding.js";
+export * from "./plan.js";
+export * from "./safeTx.js";

package/dist/plan.d.ts

@@ -0,0 +1,37 @@
+import { type Address, type Hex } from "viem";
+import { type Call } from "./encoding.js";
+export declare const PLAN_VERSION = "crossecute-plan/1";
+/** A call the conduit's owner makes on the home chain. */
+export type HomeCall = {
+    to: Address;
+    value: bigint;
+    data: Hex;
+};
+/** One batch for the conduit's receiver on an EVM destination, as the Foundry script simulated it. */
+export type Batch = {
+    chainId: bigint;
+    receiver: Address;
+    bootstrap: boolean;
+    gasUsed: bigint;
+    attributes: Hex[];
+    calls: Call[];
+};
+/** What `CrossecuteScript._writePlan` writes. */
+export type Plan = {
+    homeChainId: bigint;
+    owner: Address;
+    transmitter: Address;
+    fee: bigint;
+    calls: HomeCall[];
+    batches: Batch[];
+};
+/** Parses and type-checks a plan file. Does not check that its calls match its batches; see `checkPlan`. */
+export declare function parsePlan(json: string): Plan;
+/** The transmitter calldata that carries `batch`, as `CrossecuteScript._homeCallFor` builds it. */
+export declare function homeCallData(batch: Batch): Hex;
+/**
+ * Throws unless every home call is the transmitter call its batch implies, so a plan edited
+ * after simulation cannot carry calldata other than what was simulated. Only the first call
+ * may carry value: the transmitter top-up.
+ */
+export declare function checkPlan(plan: Plan): void;

package/dist/plan.js

@@ -0,0 +1,92 @@
+import { TransmitterBaseAbi } from "@crossecute/protocol/abi";
+import { encodeFunctionData, getAddress, isAddress, isHex } from "viem";
+import { encodeBootstrap, encodeCalls, encodeEvm, encodeEvmChain } from "./encoding.js";
+export const PLAN_VERSION = "crossecute-plan/1";
+function address(value, at) {
+    if (typeof value !== "string" || !isAddress(value, { strict: false }))
+        throw new Error(`${at}: not an address`);
+    return getAddress(value);
+}
+function hex(value, at) {
+    if (typeof value !== "string" || !isHex(value))
+        throw new Error(`${at}: not hex`);
+    return value;
+}
+function uint(value, at) {
+    if (typeof value !== "string" || !/^[0-9]+$/.test(value))
+        throw new Error(`${at}: not a decimal string`);
+    return BigInt(value);
+}
+function array(value, at) {
+    if (!Array.isArray(value))
+        throw new Error(`${at}: not an array`);
+    return value;
+}
+/** Parses and type-checks a plan file. Does not check that its calls match its batches; see `checkPlan`. */
+export function parsePlan(json) {
+    const raw = JSON.parse(json);
+    if (raw.version !== PLAN_VERSION)
+        throw new Error(`unsupported plan version ${raw.version}`);
+    return {
+        homeChainId: uint(raw.homeChainId, "homeChainId"),
+        owner: address(raw.owner, "owner"),
+        transmitter: address(raw.transmitter, "transmitter"),
+        fee: uint(raw.fee, "fee"),
+        calls: array(raw.calls, "calls").map((c, i) => ({
+            to: address(c.to, `calls[${i}].to`),
+            value: uint(c.value, `calls[${i}].value`),
+            data: hex(c.data, `calls[${i}].data`),
+        })),
+        batches: array(raw.batches, "batches").map((b, i) => {
+            if (typeof b.bootstrap !== "boolean")
+                throw new Error(`batches[${i}].bootstrap: not a boolean`);
+            return {
+                chainId: uint(b.chainId, `batches[${i}].chainId`),
+                receiver: address(b.receiver, `batches[${i}].receiver`),
+                bootstrap: b.bootstrap,
+                gasUsed: uint(b.gasUsed, `batches[${i}].gasUsed`),
+                attributes: array(b.attributes, `batches[${i}].attributes`).map((a, j) => hex(a, `batches[${i}].attributes[${j}]`)),
+                calls: array(b.calls, `batches[${i}].calls`).map((c, j) => ({
+                    target: address(c.target, `batches[${i}].calls[${j}].target`),
+                    value: uint(c.value, `batches[${i}].calls[${j}].value`),
+                    data: hex(c.data, `batches[${i}].calls[${j}].data`),
+                })),
+            };
+        }),
+    };
+}
+/** The transmitter calldata that carries `batch`, as `CrossecuteScript._homeCallFor` builds it. */
+export function homeCallData(batch) {
+    const body = encodeCalls(batch.calls);
+    if (batch.bootstrap) {
+        return encodeFunctionData({
+            abi: TransmitterBaseAbi,
+            functionName: "bootstrap",
+            args: [encodeBootstrap(encodeEvmChain(batch.chainId), body), batch.attributes],
+        });
+    }
+    return encodeFunctionData({
+        abi: TransmitterBaseAbi,
+        functionName: "sendMessage",
+        args: [encodeEvm(batch.chainId, batch.receiver), body, batch.attributes],
+    });
+}
+/**
+ * Throws unless every home call is the transmitter call its batch implies, so a plan edited
+ * after simulation cannot carry calldata other than what was simulated. Only the first call
+ * may carry value: the transmitter top-up.
+ */
+export function checkPlan(plan) {
+    if (plan.calls.length === 0)
+        throw new Error("plan has no calls");
+    if (plan.calls.length !== plan.batches.length)
+        throw new Error("plan has a different number of calls and batches");
+    plan.calls.forEach((call, i) => {
+        if (call.to !== plan.transmitter)
+            throw new Error(`calls[${i}] is not to the transmitter`);
+        if (i > 0 && call.value !== 0n)
+            throw new Error(`calls[${i}] carries value`);
+        if (call.data.toLowerCase() !== homeCallData(plan.batches[i]))
+            throw new Error(`calls[${i}] does not carry batches[${i}]`);
+    });
+}

package/dist/safeTx.d.ts

@@ -0,0 +1,86 @@
+import { type Address, type Hex } from "viem";
+import { type Plan } from "./plan.js";
+/** Safe's EIP-712 `SafeTx`. */
+export type SafeTx = {
+    to: Address;
+    value: bigint;
+    data: Hex;
+    operation: 0 | 1;
+    safeTxGas: bigint;
+    baseGas: bigint;
+    gasPrice: bigint;
+    gasToken: Address;
+    refundReceiver: Address;
+    nonce: bigint;
+};
+/** A Safe transaction with the domain it is signed under. */
+export type SafeTxEnvelope = {
+    chainId: bigint;
+    safe: Address;
+    tx: SafeTx;
+};
+export declare const safeTxTypes: {
+    readonly EIP712Domain: readonly [{
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }];
+    readonly SafeTx: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }, {
+        readonly name: "operation";
+        readonly type: "uint8";
+    }, {
+        readonly name: "safeTxGas";
+        readonly type: "uint256";
+    }, {
+        readonly name: "baseGas";
+        readonly type: "uint256";
+    }, {
+        readonly name: "gasPrice";
+        readonly type: "uint256";
+    }, {
+        readonly name: "gasToken";
+        readonly type: "address";
+    }, {
+        readonly name: "refundReceiver";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * MultiSendCallOnly deployments by Safe version, from @safe-global/safe-deployments 1.37.67.
+ * `CrossecuteScript._knownMultiSendCallOnly` holds the same table; test/Vectors.t.sol writes
+ * it to vectors/ so the two are compared.
+ */
+export declare const multiSendCallOnly: Record<string, {
+    addresses: Address[];
+    codeHash: Hex;
+}>;
+/** Parses typed data written by `CrossecuteScript._writeSafeTx`, refusing any other shape. */
+export declare function parseSafeTxTypedData(json: string): SafeTxEnvelope;
+/** The domain hash, message hash and `safeTxHash` a signer's device shows. */
+export declare function safeTxHashes({ chainId, safe, tx }: SafeTxEnvelope): {
+    domainHash: Hex;
+    messageHash: Hex;
+    safeTxHash: Hex;
+};
+/** `CrossecuteScript._multiSendPacked` followed by the `multiSend` call. */
+export declare function multiSendData(calls: Plan["calls"]): Hex;
+/**
+ * Throws unless `envelope` is the one Safe transaction that carries `plan`: under the owner
+ * Safe's domain on the home chain, with no gas refund, and either the plan's one call directly
+ * or all of them through a known MultiSendCallOnly.
+ */
+export declare function checkSafeTx(plan: Plan, envelope: SafeTxEnvelope): void;