@rootzero/contracts 0.2.0 → 0.4.0

package/blocks/Keys.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @title Keys
+/// @notice Block type selectors for the rootzero block stream protocol.
+/// Each key is the first 4 bytes of the keccak256 hash of its schema string,
+/// matching the ABI-selector convention used in `Schemas`.
+library Keys {
+    /// @dev Input amount — (bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Amount = bytes4(keccak256("amount(bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Ledger balance — (bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Balance = bytes4(keccak256("balance(bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Cross-host custody position — (uint host, bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Custody = bytes4(keccak256("custody(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Minimum acceptable output — (bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Minimum = bytes4(keccak256("minimum(bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Maximum allowable spend — (bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Maximum = bytes4(keccak256("maximum(bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Hard stop / iteration sentinel — ()
+    bytes4 constant Break = bytes4(keccak256("break()"));
+    /// @dev Bundle wrapper — (bytes data); payload is an embedded block stream
+    bytes4 constant Bundle = bytes4(keccak256("bundle(bytes data)"));
+    /// @dev Extensible routing field — (bytes data); layout is command-defined
+    bytes4 constant Route = bytes4(keccak256("route(bytes data)"));
+    /// @dev Plain scalar amount — (uint amount)
+    bytes4 constant Quantity = bytes4(keccak256("quantity(uint amount)"));
+    /// @dev Ratio or rate value — (uint value)
+    bytes4 constant Rate = bytes4(keccak256("rate(uint value)"));
+    /// @dev Counter-party account — (bytes32 account)
+    bytes4 constant Party = bytes4(keccak256("party(bytes32 account)"));
+    /// @dev Destination account — (bytes32 account)
+    bytes4 constant Recipient = bytes4(keccak256("recipient(bytes32 account)"));
+    /// @dev Settled transfer record — (bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Transaction = bytes4(keccak256("tx(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Sub-command invocation — (uint target, uint value, bytes request)
+    bytes4 constant Step = bytes4(keccak256("step(uint target, uint value, bytes request)"));
+    /// @dev Authentication proof — (uint cid, uint deadline, bytes proof); must appear last in its segment
+    bytes4 constant Auth = bytes4(keccak256("auth(uint cid, uint deadline, bytes proof)"));
+    /// @dev Asset descriptor without amount — (bytes32 asset, bytes32 meta)
+    bytes4 constant Asset = bytes4(keccak256("asset(bytes32 asset, bytes32 meta)"));
+    /// @dev Node identifier — (uint id)
+    bytes4 constant Node = bytes4(keccak256("node(uint id)"));
+    /// @dev Cross-host asset listing — (uint host, bytes32 asset, bytes32 meta)
+    bytes4 constant Listing = bytes4(keccak256("listing(uint host, bytes32 asset, bytes32 meta)"));
+    /// @dev Liquidity funding entry — (uint host, uint amount)
+    bytes4 constant Funding = bytes4(keccak256("funding(uint host, uint amount)"));
+    /// @dev Cross-host allocation — (uint host, bytes32 asset, bytes32 meta, uint amount)
+    bytes4 constant Allocation = bytes4(keccak256("allocation(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    /// @dev Relayer bounty — (uint amount, bytes32 relayer)
+    bytes4 constant Bounty = bytes4(keccak256("bounty(uint amount, bytes32 relayer)"));
+}

package/blocks/Mem.sol

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { HostAmount, Tx, Keys } from "./Schema.sol";
+import { Cursors } from "./Cursors.sol";
+
+/// @notice Reference to a single block inside a `bytes memory` buffer.
+/// Positions are byte offsets within the buffer (not absolute memory addresses).
+struct MemRef {
+    /// @dev Block type identifier read from the 4-byte header key.
+    bytes4 key;
+    /// @dev Payload start offset (byte immediately after the 8-byte header).
+    uint i;
+    /// @dev Payload end offset (equals `i + payloadLen`).
+    uint end;
+}
+
+/// @title Mem
+/// @notice Memory block stream parser for the rootzero protocol.
+/// Mirrors the calldata-oriented `Cursors` API but operates on `bytes memory`
+/// buffers, using `mcopy`/`mload` assembly instead of `msg.data` slices.
+library Mem {
+    /// @notice Parse a block header at offset `i` within `source`.
+    /// Returns an empty sentinel `MemRef` (all zeros) when `i` is at end-of-data.
+    /// @param source In-memory block stream buffer.
+    /// @param i Byte offset of the block header within `source`.
+    /// @return ref Parsed block reference with key, payload start, and payload end.
+    function from(bytes memory source, uint i) internal pure returns (MemRef memory ref) {
+        uint eod = source.length;
+        if (i == eod) return MemRef(bytes4(0), i, i);
+        if (i > eod) revert Cursors.MalformedBlocks();
+
+        unchecked {
+            ref.i = i + 8;
+        }
+        if (ref.i > eod) revert Cursors.MalformedBlocks();
+
+        // Read the 8-byte block header (key + payloadLen) in one mload.
+        bytes32 w;
+        assembly ("memory-safe") {
+            w := mload(add(add(source, 0x20), i))
+        }
+
+        ref.key = bytes4(w);
+        ref.end = ref.i + uint32(bytes4(w << 32));
+        if (ref.end > eod) revert Cursors.MalformedBlocks();
+    }
+
+    /// @notice Extract a byte range `[start, end)` from `source` into a new buffer.
+    /// @param source Source buffer.
+    /// @param start Inclusive start offset.
+    /// @param end Exclusive end offset.
+    /// @return out Copied slice as a new `bytes` value.
+    function slice(bytes memory source, uint start, uint end) internal pure returns (bytes memory out) {
+        if (end < start || end > source.length) revert Cursors.MalformedBlocks();
+        uint len = end - start;
+        out = new bytes(len);
+        if (len == 0) return out;
+
+        assembly ("memory-safe") {
+            mcopy(add(out, 0x20), add(add(source, 0x20), start), len)
+        }
+    }
+
+    /// @notice Count consecutive blocks of `key` starting at offset `i`.
+    /// @param source Source buffer.
+    /// @param i Starting byte offset.
+    /// @param key Block type to count.
+    /// @return total Number of consecutive matching blocks.
+    /// @return cursor Byte offset immediately after the last counted block.
+    function count(bytes memory source, uint i, bytes4 key) internal pure returns (uint total, uint cursor) {
+        cursor = i;
+        while (cursor < source.length) {
+            MemRef memory ref = from(source, cursor);
+            if (ref.key != key) break;
+            unchecked {
+                ++total;
+            }
+            cursor = ref.end;
+        }
+    }
+
+    /// @notice Scan forward from `i` up to `limit` for the first block matching `key`.
+    /// Returns an empty sentinel `MemRef` (key == 0, i == end == limit) if not found.
+    /// @param source Source buffer.
+    /// @param i Starting byte offset.
+    /// @param limit Exclusive upper bound for the search (must be ≤ `source.length`).
+    /// @param key Block type to find.
+    /// @return ref Reference to the first matching block, or the sentinel if absent.
+    function find(bytes memory source, uint i, uint limit, bytes4 key) internal pure returns (MemRef memory ref) {
+        if (limit > source.length) revert Cursors.MalformedBlocks();
+        while (i < limit) {
+            ref = from(source, i);
+            if (ref.end > limit) revert Cursors.MalformedBlocks();
+            if (ref.key == key) return ref;
+            i = ref.end;
+        }
+
+        return MemRef(bytes4(0), limit, limit);
+    }
+
+    /// @notice Assert that `ref` points to a block of the expected type.
+    /// @param ref Block reference to validate.
+    /// @param key Expected block type key.
+    function ensure(MemRef memory ref, bytes4 key) internal pure {
+        if (key == 0 || key != ref.key) revert Cursors.InvalidBlock();
+    }
+
+    /// @notice Assert that `ref` points to a block of the expected type with exact payload length.
+    /// @param ref Block reference to validate.
+    /// @param key Expected block type key.
+    /// @param len Expected payload byte length.
+    function ensure(MemRef memory ref, bytes4 key, uint len) internal pure {
+        if (key == 0 || key != ref.key || len != (ref.end - ref.i)) revert Cursors.InvalidBlock();
+    }
+
+    /// @notice Assert that `ref` points to a block of the expected type within a length range.
+    /// @param ref Block reference to validate.
+    /// @param key Expected block type key.
+    /// @param min Minimum payload length (inclusive).
+    /// @param max Maximum payload length (inclusive); 0 means unbounded.
+    function ensure(MemRef memory ref, bytes4 key, uint min, uint max) internal pure {
+        uint len = ref.end - ref.i;
+        if (key == 0 || key != ref.key || len < min || (max != 0 && len > max)) revert Cursors.InvalidBlock();
+    }
+
+    /// @notice Decode a BALANCE block payload from `source` using the given reference.
+    /// @param ref Block reference; must point to a BALANCE block with exactly 96 payload bytes.
+    /// @param source Buffer containing the block.
+    /// @return asset Asset identifier.
+    /// @return meta Asset metadata slot.
+    /// @return amount Token amount.
+    function unpackBalance(
+        MemRef memory ref,
+        bytes memory source
+    ) internal pure returns (bytes32 asset, bytes32 meta, uint amount) {
+        ensure(ref, Keys.Balance, 96);
+        uint i = ref.i;
+
+        // Read three contiguous 32-byte words from the payload.
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            asset := mload(p)
+            meta := mload(add(p, 0x20))
+            amount := mload(add(p, 0x40))
+        }
+    }
+
+    /// @notice Decode a CUSTODY block payload from `source` into a `HostAmount` struct.
+    /// @param ref Block reference; must point to a CUSTODY block with exactly 128 payload bytes.
+    /// @param source Buffer containing the block.
+    /// @return value Decoded host, asset, meta, and amount.
+    function toCustodyValue(
+        MemRef memory ref,
+        bytes memory source
+    ) internal pure returns (HostAmount memory value) {
+        ensure(ref, Keys.Custody, 128);
+        uint i = ref.i;
+
+        // Copy four 32-byte payload words directly into the struct memory slots.
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            mstore(value, mload(p))
+            mstore(add(value, 0x20), mload(add(p, 0x20)))
+            mstore(add(value, 0x40), mload(add(p, 0x40)))
+            mstore(add(value, 0x60), mload(add(p, 0x60)))
+        }
+    }
+
+    /// @notice Decode a TRANSACTION block payload from `source` into a `Tx` struct.
+    /// @param ref Block reference; must point to a TRANSACTION block with exactly 160 payload bytes.
+    /// @param source Buffer containing the block.
+    /// @return value Decoded from, to, asset, meta, and amount.
+    function toTxValue(MemRef memory ref, bytes memory source) internal pure returns (Tx memory value) {
+        ensure(ref, Keys.Transaction, 160);
+        uint i = ref.i;
+
+        // Copy five 32-byte payload words directly into the struct memory slots.
+        assembly ("memory-safe") {
+            let p := add(add(source, 0x20), i)
+            mstore(value, mload(p))
+            mstore(add(value, 0x20), mload(add(p, 0x20)))
+            mstore(add(value, 0x40), mload(add(p, 0x40)))
+            mstore(add(value, 0x60), mload(add(p, 0x60)))
+            mstore(add(value, 0x80), mload(add(p, 0x80)))
+        }
+    }
+}

package/blocks/Schema.sol

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Keys } from "./Keys.sol";
+
+/// @title Schemas
+/// @notice Human-readable ABI-signature string constants for each block type.
+/// These strings are the canonical source from which `Keys` constants are derived
+/// and are used when emitting schema descriptors in command events.
+library Schemas {
+    string constant Amount = "amount(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Balance = "balance(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Custody = "custody(uint host, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Minimum = "minimum(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Maximum = "maximum(bytes32 asset, bytes32 meta, uint amount)";
+    string constant Break = "break()";
+    string constant Route = "route(bytes data)";
+    string constant RouteEmpty = "route()";
+    string constant Quantity = "quantity(uint amount)";
+    string constant Rate = "rate(uint value)";
+    string constant Party = "party(bytes32 account)";
+    string constant Recipient = "recipient(bytes32 account)";
+    string constant Transaction = "tx(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Step = "step(uint target, uint value, bytes request)";
+    string constant Auth = "auth(uint cid, uint deadline, bytes proof)";
+    string constant Asset = "asset(bytes32 asset, bytes32 meta)";
+    string constant Node = "node(uint id)";
+    string constant Listing = "listing(uint host, bytes32 asset, bytes32 meta)";
+    string constant Funding = "funding(uint host, uint amount)";
+    string constant Allocation = "allocation(uint host, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Bounty = "bounty(uint amount, bytes32 relayer)";
+
+    /// @notice Compose a route schema with one additional field.
+    /// @param maybeRoute Existing route schema string, or empty string to start a fresh `route()`.
+    /// @param a Schema string for the field to append.
+    /// @return Composed schema string: `"route(...) & a"`.
+    function route1(string memory maybeRoute, string memory a) internal pure returns (string memory) {
+        return string.concat(bytes(maybeRoute).length == 0 ? RouteEmpty : maybeRoute, "&", a);
+    }
+
+    /// @notice Compose a route schema with two additional fields.
+    /// @param maybeRoute Existing route schema string, or empty string to start a fresh `route()`.
+    /// @param a Schema string for the first field to append.
+    /// @param b Schema string for the second field to append.
+    /// @return Composed schema string: `"route(...) & a & b"`.
+    function route2(string memory maybeRoute, string memory a, string memory b) internal pure returns (string memory) {
+        return string.concat(bytes(maybeRoute).length == 0 ? RouteEmpty : maybeRoute, "&", a, "&", b);
+    }
+}
+
+// Block stream:
+// - encoding is [bytes4 key][bytes4 payloadLen][payload]
+// - `payloadLen` covers only the block payload
+// - payload layout is block-specific
+//
+// Extensible payloads:
+// - self payload may be [head][dynamic tail]
+// - head layout is implied by the block key
+// - one dynamic field may consume the rest of self payload without its own length prefix
+//
+// Schema DSL:
+// - `;` separates top-level sibling blocks
+// - `&` bundles adjacent blocks into one bundle block
+// - bundled blocks preserve member order, so `a & b` differs from `b & a`
+// - a bundle block's self payload is an embedded normal block stream of its bundled members
+// - bundled members keep their ordinary block encoding, so dynamic blocks are allowed inside bundles
+// - `->` separates request and response shapes, appears at most once, and is omitted when no output is modeled
+// - top-level blocks of the same type should be grouped together
+// - primary / driving blocks should appear before auxiliary blocks
+// - `route(<fields...>)` is a reserved extensible schema form whose key is always `Keys.Route`
+// - `&` compiles to a `Keys.Bundle` block whose self payload is the bundled member block stream
+// - canonical blocks are `amount(...)` for request amounts, `balance(...)` for state balances,
+//   `minimum(...)` for result floors, `maximum(...)` for spend ceilings, and `quantity(...)`
+//   for plain scalar amounts
+// - `auth(uint cid, uint deadline, bytes proof)` is a proof-separator block and must be emitted last
+//
+// Signed blocks:
+// - an authenticated input segment ends with one trailing AUTH block
+// - auth is typically grouped with the signed payload in one bundle, with AUTH as the final member
+// - only the final AUTH is treated specially; earlier AUTH blocks remain ordinary signed bytes
+// - the signed slice runs from the segment start through the AUTH head, excluding only AUTH proof bytes
+// - `cid` binds the signature to one command; `deadline` acts as expiry and nonce
+// - current helpers assume proof layout `[bytes20 signer][bytes65 sig]`
+
+/// @title Sizes
+/// @notice Total byte sizes for fixed-width block types, including the 8-byte header (4-byte key + 4-byte payloadLen).
+library Sizes {
+    /// @dev AUTH proof segment only: 20-byte signer + 65-byte signature = 85 bytes
+    uint constant Proof = 85;
+    /// @dev AUTH block: 8 header + 32 cid + 32 deadline + 85 proof = 157 bytes
+    uint constant Auth = 157;
+    /// @dev BALANCE block: 8 header + 32 asset + 32 meta + 32 amount = 104 bytes
+    uint constant Balance = 104;
+    /// @dev BOUNTY block: 8 header + 32 amount + 32 relayer = 72 bytes
+    uint constant Bounty = 72;
+    /// @dev CUSTODY block: 8 header + 32 host + 32 asset + 32 meta + 32 amount = 136 bytes
+    uint constant Custody = 136;
+    /// @dev TRANSACTION block: 8 header + 32 from + 32 to + 32 asset + 32 meta + 32 amount = 168 bytes
+    uint constant Transaction = 168;
+}
+
+/// @notice Asset and amount pair; used for balance and amount blocks.
+struct AssetAmount {
+    /// @dev Asset identifier (encoding depends on asset type — see `Assets` library).
+    bytes32 asset;
+    /// @dev Asset metadata slot (e.g. token contract address or ERC-721 token ID context).
+    bytes32 meta;
+    /// @dev Token amount in the asset's native units.
+    uint amount;
+}
+
+/// @notice Cross-host custody value; used for custody and allocation blocks.
+struct HostAmount {
+    /// @dev Host node ID that holds the custody position.
+    uint host;
+    /// @dev Asset identifier.
+    bytes32 asset;
+    /// @dev Asset metadata slot.
+    bytes32 meta;
+    /// @dev Token amount in the asset's native units.
+    uint amount;
+}
+
+/// @notice User-scoped amount; associates an account with an asset amount.
+struct UserAmount {
+    /// @dev User account identifier.
+    bytes32 account;
+    /// @dev Asset identifier.
+    bytes32 asset;
+    /// @dev Asset metadata slot.
+    bytes32 meta;
+    /// @dev Token amount in the asset's native units.
+    uint amount;
+}
+
+/// @notice Cross-host asset descriptor without an amount.
+struct HostAsset {
+    /// @dev Host node ID.
+    uint host;
+    /// @dev Asset identifier.
+    bytes32 asset;
+    /// @dev Asset metadata slot.
+    bytes32 meta;
+}
+
+/// @notice Settled transfer record written to transaction state.
+struct Tx {
+    /// @dev Sender account identifier.
+    bytes32 from;
+    /// @dev Recipient account identifier.
+    bytes32 to;
+    /// @dev Asset identifier.
+    bytes32 asset;
+    /// @dev Asset metadata slot.
+    bytes32 meta;
+    /// @dev Transfer amount in the asset's native units.
+    uint amount;
+}