@rootzero/contracts 0.4.0 → 0.5.1

package/Cursors.sol

@@ -1,14 +1,13 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all block stream primitives (Cursors, Writers, Mem, Schema, Keys).
+// Aggregator: re-exports all block stream primitives (Cursors, Writers, Schema, Keys).
 // Import this file to get access to the full block encoding/decoding surface in one import.
 
 import { HostAmount, UserAmount, HostAsset, Tx, AssetAmount } from "./blocks/Schema.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Schemas } from "./blocks/Schema.sol";
 import { Cursors, Cur } from "./blocks/Cursors.sol";
-import { Mem, MemRef } from "./blocks/Mem.sol";
 import { Writer, Writers } from "./blocks/Writers.sol";
 
 

package/blocks/Cursors.sol

@@ -778,6 +778,15 @@ library Cursors {
         cur.i += 104;
     }
 
+    /// @notice Consume a MINIMUM block, assert it matches the expected asset and meta, and require `amount` to satisfy it.
+    /// @param cur Cursor; advanced past the block.
+    /// @param asset Expected asset identifier.
+    /// @param meta Expected metadata slot.
+    /// @param amount Actual amount that must be at least the minimum from the block.
+    function requireMinimum(Cur memory cur, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        if (requireMinimum(cur, asset, meta) > amount) revert UnexpectedValue();
+    }
+
     /// @notice Consume a MAXIMUM block and assert it matches the expected asset and meta.
     /// @param cur Cursor; advanced past the block.
     /// @param asset Expected asset identifier.
@@ -788,6 +797,15 @@ library Cursors {
         cur.i += 104;
     }
 
+    /// @notice Consume a MAXIMUM block, assert it matches the expected asset and meta, and require `amount` to satisfy it.
+    /// @param cur Cursor; advanced past the block.
+    /// @param asset Expected asset identifier.
+    /// @param meta Expected metadata slot.
+    /// @param amount Actual amount that must be at most the maximum from the block.
+    function requireMaximum(Cur memory cur, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        if (requireMaximum(cur, asset, meta) < amount) revert UnexpectedValue();
+    }
+
     /// @notice Consume a CUSTODY block and assert it belongs to the expected host.
     /// @param cur Cursor; advanced past the block.
     /// @param host Expected host node ID.

package/blocks/Keys.sol

@@ -30,7 +30,7 @@ library Keys {
     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)
+    /// @dev Transfer record passed through the pipeline — (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)"));

package/blocks/Schema.sol

@@ -143,7 +143,7 @@ struct HostAsset {
     bytes32 meta;
 }
 
-/// @notice Settled transfer record written to transaction state.
+/// @notice Transfer payload used across the pipeline and later consumed by settlement.
 struct Tx {
     /// @dev Sender account identifier.
     bytes32 from;

package/blocks/Writers.sol

@@ -259,7 +259,7 @@ library Writers {
     /// @notice Write a TRANSACTION block directly into `dst` at byte offset `i`.
     /// @param dst Destination buffer; must have at least `i + Sizes.Transaction` bytes.
     /// @param i Write offset within `dst`.
-    /// @param value Transaction fields to encode.
+    /// @param value Transfer record fields to encode.
     /// @return next Byte offset immediately after the written block.
     function writeTxBlock(bytes memory dst, uint i, Tx memory value) internal pure returns (uint next) {
         next = i + Sizes.Transaction;
@@ -279,7 +279,7 @@ library Writers {
 
     /// @notice Append a TRANSACTION block from a struct.
     /// @param writer Destination writer; `i` is advanced by `Sizes.Transaction`.
-    /// @param value Transaction fields to encode.
+    /// @param value Transfer record fields to encode.
     function appendTx(Writer memory writer, Tx memory value) internal pure {
         writer.i = writeTxBlock(writer.dst, writer.i, value);
     }

package/commands/Provision.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {CommandContext, CommandBase, State} from "./Base.sol";
-import {Cursors, Cur, Keys, Schemas, Writer, Writers} from "../Cursors.sol";
+import {Cursors, Cur, Schemas, Writer, Writers} from "../Cursors.sol";
 using Cursors for Cur;
 using Writers for Writer;
 
@@ -38,8 +38,6 @@ abstract contract Provision is CommandBase, ProvisionHook {
         CommandContext calldata c
     ) external payable onlyCommand(provisionId, c.target) returns (bytes memory) {
         (Cur memory request, uint count, ) = cursor(c.request, 1);
-        (bytes4 key, ) = request.peek(0);
-        if (key != Keys.Bundle) revert Writers.EmptyRequest();
         Writer memory writer = Writers.allocCustodies(count);
 
         while (request.i < request.bound) {

package/commands/Settle.sol

@@ -3,31 +3,27 @@ pragma solidity ^0.8.33;
 
 import { CommandContext, CommandBase, State } from "./Base.sol";
 import { Cursors, Cur, Tx } from "../Cursors.sol";
+import { TransferHook } from "./Transfer.sol";
 using Cursors for Cur;
 
 string constant NAME = "settle";
 
 /// @title Settle
-/// @notice Command that settles each TRANSACTION state block via a virtual hook.
+/// @notice Command that consumes each TRANSACTION state block and settles it through the shared transfer hook.
 /// Produces no output state.
-abstract contract Settle is CommandBase {
+abstract contract Settle is CommandBase, TransferHook {
     uint internal immutable settleId = commandId(NAME);
 
     constructor() {
         emit Command(host, NAME, "", settleId, State.Transactions, State.Empty);
     }
 
-    /// @notice Override to settle a single transaction block.
-    /// Called once per TRANSACTION block in state.
-    /// @param value Decoded transaction (from, to, asset, meta, amount).
-    function settle(Tx memory value) internal virtual;
-
     function settle(CommandContext calldata c) external payable onlyCommand(settleId, c.target) returns (bytes memory) {
         (Cur memory state, , ) = cursor(c.state, 1);
 
         while (state.i < state.bound) {
             Tx memory value = state.unpackTxValue();
-            settle(value);
+            transfer(value);
         }
 
         state.complete();

package/commands/Transfer.sol

@@ -2,39 +2,46 @@
 pragma solidity ^0.8.33;
 
 import { CommandContext, CommandBase, State } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../Cursors.sol";
+import { Cursors, Cur, Schemas, Tx } from "../Cursors.sol";
+import { Accounts } from "../utils/Accounts.sol";
 using Cursors for Cur;
 
 string constant NAME = "transfer";
 string constant INPUT = string.concat(Schemas.Amount, "&", Schemas.Recipient);
 
+abstract contract TransferHook {
+    /// @notice Override to execute a single transfer record from the request pipeline.
+    /// Called once per bundled AMOUNT+RECIPIENT pair in the request.
+    /// @param value Decoded transfer record (from, to, asset, meta, amount).
+    function transfer(Tx memory value) internal virtual;
+}
+
 /// @title Transfer
 /// @notice Command that transfers assets from a caller to recipients specified in
 /// bundled AMOUNT+RECIPIENT request blocks. Produces no state output.
-/// The virtual `transfer(from, input)` hook is called once per bundle.
-abstract contract Transfer is CommandBase {
+/// The virtual `transfer(value)` hook is called once per bundle.
+abstract contract Transfer is CommandBase, TransferHook {
     uint internal immutable transferId = commandId(NAME);
 
     constructor() {
         emit Command(host, NAME, INPUT, transferId, State.Empty, State.Empty);
     }
 
-    /// @notice Override to execute a single transfer described by the current `input` position.
-    /// Called once per bundled AMOUNT+RECIPIENT pair in the request.
-    /// @param from Source account identifier.
-    /// @param input Live request cursor positioned at the current bundle.
-    function transfer(bytes32 from, Cur memory input) internal virtual;
-
     /// @notice Override to customize request parsing or batching for transfers.
-    /// The default implementation iterates bundles and calls `transfer(from, input)` for each.
+    /// The default implementation iterates bundles and calls `transfer(value)` for each.
     /// @param from Source account identifier.
     /// @param request Full request bytes.
     /// @return Empty bytes (transfers produce no state output).
     function transfer(bytes32 from, bytes calldata request) internal virtual returns (bytes memory) {
         (Cur memory input, , ) = cursor(request, 1);
+        Tx memory value;
+        value.from = from;
 
         while (input.i < input.bound) {
-            transfer(from, input);
+            Cur memory bundle = input.bundle();
+            (value.asset, value.meta, value.amount) = bundle.unpackAmount();
+            value.to = Accounts.ensure(bundle.unpackRecipient());
+            transfer(value);
         }
 
         input.complete();

package/events/RootZero.sol

@@ -3,15 +3,14 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-string constant ABI = "event RootZero(uint indexed host, bytes32 account, uint deadline, uint value)";
+string constant ABI = "event RootZero(bytes32 indexed account, uint deadline, uint value)";
 
 /// @notice Emitted for root-level protocol actions (e.g. governance or protocol-wide operations).
 abstract contract RootZeroEvent is EventEmitter {
-    /// @param host Host node ID where the action occurred.
     /// @param account Account identifier associated with the action.
     /// @param deadline Expiry timestamp of the action.
     /// @param value Native value associated with the action.
-    event RootZero(uint indexed host, bytes32 account, uint deadline, uint value);
+    event RootZero(bytes32 indexed account, uint deadline, uint value);
 
     constructor() {
         emit EventAbi(ABI);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/peer/Settle.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { PeerBase } from "./Base.sol";
+import { TransferHook } from "../commands/Transfer.sol";
+import { Cursors, Cur, Tx, Schemas } from "../Cursors.sol";
+
+using Cursors for Cur;
+
+string constant NAME = "peerSettle";
+
+/// @title PeerSettle
+/// @notice Peer that consumes peer-supplied TRANSACTION blocks through the shared transfer hook.
+/// Each TRANSACTION block in the request calls `transfer(value)`. Restricted to trusted peers.
+abstract contract PeerSettle is PeerBase, TransferHook {
+    uint internal immutable peerSettleId = peerId(NAME);
+
+    constructor() {
+        emit Peer(host, NAME, Schemas.Transaction, peerSettleId);
+    }
+
+    /// @notice Execute the peer-settle call.
+    function peerSettle(bytes calldata request) external payable onlyPeer returns (bytes memory) {
+        (Cur memory state, , ) = cursor(request, 1);
+
+        while (state.i < state.bound) {
+            Tx memory value = state.unpackTxValue();
+            transfer(value);
+        }
+
+        state.complete();
+        return "";
+    }
+}

package/utils/Accounts.sol

@@ -70,6 +70,17 @@ library Accounts {
         return account == toKeccak(raw);
     }
 
+    /// @notice Assert that `account` uses the Account layout tag and return it unchanged.
+    /// Ignores width, chain binding, and subtype details.
+    /// @param account Account ID to validate.
+    /// @return The same `account` value if valid.
+    function ensure(bytes32 account) internal pure returns (bytes32) {
+        if (uint8(uint(account) >> 232) != Layout.Account) {
+            revert InvalidAccount();
+        }
+        return account;
+    }
+
     /// @notice Assert that `account` belongs to the EVM account family and return it unchanged.
     /// @param account Account ID to validate.
     /// @return The same `account` value if valid.

package/blocks/Mem.sol

@@ -1,188 +0,0 @@
-// 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)))
-        }
-    }
-}