@rootzero/contracts 1.13.0 → 1.14.0

package/queries/Balances.sol

@@ -1,12 +1,13 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cur, Cursors, Keys, Writer, Writers} from "../Cursors.sol";
+import {Specs} from "../Codec.sol";
+import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 import {QueryBase} from "./Base.sol";
 
-using Cursors for Cur;
-using Writers for Writer;
+using Executions for Execution;
 
+/// @notice Hook implemented by hosts that expose account balance queries.
 abstract contract GetBalancesHook {
     /// @notice Resolve one account's balance for one supported asset.
     /// Concrete implementations define how assets are resolved.
@@ -18,28 +19,27 @@ abstract contract GetBalancesHook {
 
 /// @title GetBalances
 /// @notice Rootzero query that resolves balances for one or more `(account, asset)` tuples.
-/// The request is a run of `ACCOUNT_ASSET` form blocks.
-/// The response returns one `ACCOUNT_AMOUNT` form block per requested position, preserving request order.
+/// The input is a run of `ACCOUNT_ASSET` form blocks.
+/// The response returns one `ACCOUNT_AMOUNT` form block per requested position, preserving input order.
 abstract contract GetBalances is QueryBase, GetBalancesHook {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = query("getBalances", Keys.AccountAsset, Keys.AccountAmount, 0);
+        (, descriptor) = query("getBalances", Specs.AccountAsset, Specs.AccountAmount);
     }
 
     /// @notice Resolve balances for a run of requested `(account, asset)` tuples.
-    /// @param request Block-stream request consisting of `accountAsset(account, asset)*`.
-    /// @return Block-stream response containing one `accountAmount(account, asset, amount)` block per request block.
-    function getBalances(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory input, uint outputs) = openInput(request, descriptor);
-        Writer memory response = Writers.allocAccountAmounts(outputs);
-
-        while (input.i < input.len) {
-            (bytes32 account, bytes32 asset) = input.unpackAccountAsset();
+    /// @param input Block-stream input consisting of `accountAsset(account, asset)*`.
+    /// @return Block-stream response containing one `accountAmount(account, asset, amount)` block per input block.
+    function getBalances(bytes calldata input) external view returns (bytes memory) {
+        Execution memory exec = openInput(input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 account, bytes32 asset) = exec.unpackAccountAsset(Lanes.Input);
             uint amount = getBalance(account, asset);
-            response.appendAccountAmount(account, asset, amount);
+            exec.outputAccountAmount(account, asset, amount);
         }
 
-        return response.finish();
+        return close(exec);
     }
 }

package/queries/Base.sol

@@ -2,30 +2,29 @@
 pragma solidity ^0.8.33;
 
 import { EndpointBase } from "../core/Endpoint.sol";
+import { Specs } from "../codec/Specs.sol";
 import { Nodes } from "../utils/Nodes.sol";
 import { Selectors } from "../utils/Selectors.sol";
 
 /// @title QueryBase
 /// @notice Abstract base for rootzero query contracts.
-/// Queries are view-only entry points that consume a block-stream request and
+/// Queries are view-only entry points that consume a block-stream input and
 /// return a block-stream response.
 abstract contract QueryBase is EndpointBase {
 
     /// @notice Publish query metadata and a default label.
-    /// @param name Default human-readable query label and selector name.
-    /// @param input Packed input lane plus optional group byte.
-    /// @param output Packed output lane plus optional group byte.
-    /// @param selector Query ABI selector, or zero to derive it from `name`.
+    /// @param name Query entrypoint name and default label. It must exactly
+    /// match the Solidity query function name used by the canonical ABI.
+    /// @param input Input block specification.
+    /// @param output Output block specification.
     /// @return id Query node ID.
     /// @return descriptor Packed endpoint lane metadata and flags.
     function query(
         string memory name,
-        bytes9 input,
-        bytes9 output,
-        bytes4 selector
-    ) internal returns (uint id, bytes32 descriptor) {
-        selector = selector == bytes4(0) ? Selectors.query(name) : selector;
-        id = Nodes.toQuery(selector, address(this));
-        descriptor = endpoint(id, name, bytes9(0), input, output, false, false);
+        uint input,
+        uint output
+    ) internal returns (uint id, uint descriptor) {
+        id = Nodes.toQuery(Selectors.query(name), address(this));
+        descriptor = endpoint(id, name, Specs.Empty, input, output, 0, 0);
     }
 }

package/utils/Actions.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+/// @notice Canonical action identifiers used by protocol events.
 library Actions {
     uint32 constant None = 0;
     uint32 constant Transfer = 1;

package/utils/Cursors.sol

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {clear32, max16, max32, max128} from "./Utils.sol";
+
+/// @notice Mutable memory wrapper around a packed cursor.
+/// @dev A second tagged cursor may occupy the upper 128-bit lane of `state`.
+/// Cursor operations target the lower lane; `Cursors.select` swaps the requested
+/// tagged cursor into that position.
+struct Cur {
+    uint state;
+}
+
+/// @title Cursors
+/// @notice Packed cursor state and navigation for grouped byte regions.
+/// @dev Each 128-bit cursor uses the following layout:
+/// bits   0-31    i
+/// bits  32-63    offset
+/// bits  64-95    len
+/// bits  96-111   groups
+/// bits 112-119   flags (consumer-defined)
+/// bits 120-127   tag
+/// A packed word may contain a lower cursor in bits 0-127 and a higher cursor
+/// in bits 128-255. Operations target the lower cursor; `select` swaps a
+/// requested tagged cursor into that position.
+/// The zero word represents an absent cursor.
+library Cursors {
+    /// @dev A cursor position exceeds its logical length.
+    error OutOfBounds();
+
+    /// @dev Two optional group counts are both set but do not match.
+    error BadRatio();
+
+    /// @dev A cursor is not positioned at the expected offset.
+    error UnexpectedPosition();
+
+    /// @dev Paired cursors must have different identity tags.
+    error DuplicateTag(uint8 tag);
+
+    /// @dev Neither packed cursor has the requested tag.
+    error MissingTag(uint8 tag);
+
+    // Creation and sources
+
+    /// @notice Create a cursor positioned at its beginning.
+    /// @param offset Absolute source or buffer offset.
+    /// @param len Logical byte length.
+    /// @param groups Logical group count.
+    /// @param flags Consumer-defined flags.
+    /// @param tag Cursor identity tag.
+    /// @return cur Packed cursor.
+    function create(uint offset, uint len, uint groups, uint8 flags, uint8 tag) internal pure returns (uint cur) {
+        cur |= max32(offset) << 32;
+        cur |= max32(len) << 64;
+        cur |= max16(groups) << 96;
+        cur |= uint(flags) << 112;
+        cur |= uint(tag) << 120;
+    }
+
+    /// @notice Return the absolute calldata position where `source` begins.
+    /// @param source Calldata slice whose base is requested.
+    /// @return abs Absolute calldata position.
+    function base(bytes calldata source) internal pure returns (uint abs) {
+        assembly ("memory-safe") {
+            abs := source.offset
+        }
+    }
+
+    /// @notice Return the absolute calldata start and exclusive end of `source`.
+    /// @param source Calldata slice whose bounds are requested.
+    /// @return abs Absolute start position.
+    /// @return end Absolute exclusive end position.
+    function bounds(bytes calldata source) internal pure returns (uint abs, uint end) {
+        abs = base(source);
+        end = abs + source.length;
+    }
+
+    /// @notice Create a cursor backed by a calldata slice.
+    /// @param source Calldata slice represented by the cursor.
+    /// @param flags Consumer-defined flags.
+    /// @param tag Cursor identity tag.
+    /// @return cur Packed cursor positioned at the slice beginning.
+    function wrap(bytes calldata source, uint8 flags, uint8 tag) internal pure returns (uint cur) {
+        cur = create(base(source), source.length, 0, flags, tag);
+    }
+
+    // Inspection
+
+    /// @notice Decode the positional fields from the lower cursor.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return i Current relative position.
+    /// @return offset Absolute base offset.
+    /// @return len Logical byte length.
+    function decode(uint cur) internal pure returns (uint i, uint offset, uint len) {
+        i = uint32(cur);
+        offset = uint32(cur >> 32);
+        len = uint32(cur >> 64);
+    }
+
+    /// @notice Return the absolute position of the lower cursor as `offset + i`.
+    /// @dev Performs no bounds check.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return Absolute current position.
+    function absolute(uint cur) internal pure returns (uint) {
+        return uint32(cur) + uint32(cur >> 32);
+    }
+
+    /// @notice Decode the consumer metadata and identity tag from the lower cursor.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return groups Logical group count.
+    /// @return flags Consumer-defined flags.
+    /// @return tag Cursor identity tag.
+    function meta(uint cur) internal pure returns (uint groups, uint8 flags, uint8 tag) {
+        groups = uint16(cur >> 96);
+        flags = uint8(cur >> 112);
+        tag = uint8(cur >> 120);
+    }
+
+    /// @notice Return whether both packed cursors remain at their initial positions.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return Whether both lane positions are zero.
+    function initial(uint cur) internal pure returns (bool) {
+        return uint32(cur) == 0 && uint32(cur >> 128) == 0;
+    }
+
+    /// @notice Return whether the lower cursor's current position precedes its length.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return Whether the lower cursor has bytes remaining.
+    function more(uint cur) internal pure returns (bool) {
+        return uint32(cur) < uint32(cur >> 64);
+    }
+
+    /// @notice Return whether either packed cursor has remaining bytes.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return Whether either lane has bytes remaining.
+    function any(uint cur) internal pure returns (bool) {
+        return more(cur) || more(cur >> 128);
+    }
+
+    /// @notice Require the lower cursor to be positioned at `i`.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param i Expected relative position.
+    function expect(uint cur, uint i) internal pure {
+        if (uint32(cur) != i) revert UnexpectedPosition();
+    }
+
+    /// @notice Return whether the lower cursor contains `flag`.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param flag Consumer-defined flag bit or bit set.
+    /// @return Whether any requested flag bit is present.
+    function flagged(uint cur, uint8 flag) internal pure returns (bool) {
+        return uint8(cur >> 112) & flag != 0;
+    }
+
+    // Navigation
+
+    /// @dev Return `cur` after ensuring its lower position does not exceed its length.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return Validated cursor unchanged.
+    function validate(uint cur) private pure returns (uint) {
+        if (uint32(cur) > uint32(cur >> 64)) revert OutOfBounds();
+        return cur;
+    }
+
+    /// @notice Move the lower cursor forward to `i`.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param i New relative position; must not move backward.
+    /// @return updated Cursor with the new lower position.
+    function seek(uint cur, uint i) internal pure returns (uint updated) {
+        uint current = uint32(cur);
+        uint len = uint32(cur >> 64);
+        if (i < current || i > len) revert OutOfBounds();
+        updated = clear32(cur, 0) | i;
+    }
+
+    /// @notice Replace the lower cursor's position using an absolute position.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param abs New absolute position.
+    /// @return updated Cursor with the corresponding relative position.
+    function seekAbs(uint cur, uint abs) internal pure returns (uint updated) {
+        uint offset = uint32(cur >> 32);
+        if (abs < offset) revert OutOfBounds();
+        updated = seek(cur, abs - offset);
+    }
+
+    /// @notice Advance the current position of the lower cursor.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param amount Number of bytes to advance.
+    /// @return updated Cursor advanced by `amount`.
+    function advance(uint cur, uint amount) internal pure returns (uint updated) {
+        uint i = uint32(validate(cur));
+        uint len = uint32(cur >> 64);
+        if (amount > len - i) revert OutOfBounds();
+        updated = cur + amount;
+    }
+
+    /// @notice Replace the logical length of the lower cursor.
+    /// @dev A cursor cannot be resized below its current position.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param len New logical length.
+    /// @return updated Cursor with the replaced length.
+    function resize(uint cur, uint len) internal pure returns (uint updated) {
+        if (uint32(cur) > max32(len)) revert OutOfBounds();
+        updated = clear32(cur, 64) | (len << 64);
+    }
+
+    /// @notice Create a child cursor over `[start, end)` within the lower cursor.
+    /// @dev The child starts at position zero, has no groups, and uses the
+    /// supplied tag. Any higher cursor is omitted.
+    /// @param cur Parent cursor or cursor pair.
+    /// @param start Child start relative to the parent base.
+    /// @param end Child exclusive end relative to the parent base.
+    /// @param tag Child identity tag.
+    /// @return child Packed child cursor.
+    function slice(uint cur, uint start, uint end, uint8 tag) internal pure returns (uint child) {
+        (, uint offset, uint len) = decode(validate(cur));
+        if (start > end || end > len) revert OutOfBounds();
+        child = create(offset + start, end - start, 0, 0, tag);
+    }
+
+    // Pairing and selection
+
+    /// @notice Reconcile both packed cursor lanes with an expected group count.
+    /// @dev Zero lanes and lanes with zero groups do not constrain the result.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param expected Expected group count; zero accepts the encoded count.
+    /// @return groups Reconciled effective group count.
+    function reconcile(uint cur, uint expected) internal pure returns (uint groups) {
+        uint low = uint16(cur >> 96);
+        uint high = uint16(cur >> 224);
+        if (low != 0 && high != 0 && low != high) revert BadRatio();
+
+        groups = low != 0 ? low : high;
+        if (groups != 0 && expected != 0 && groups != expected) revert BadRatio();
+        if (groups == 0) groups = expected;
+        max16(groups);
+    }
+
+    /// @notice Combine two cursors into one packed word.
+    /// @dev Zero represents absence and acts as the identity value.
+    /// @param low Cursor placed in the lower lane.
+    /// @param high Cursor placed in the higher lane.
+    /// @return cur Packed cursor pair, or the nonzero cursor when one is absent.
+    function pair(uint low, uint high) internal pure returns (uint cur) {
+        low = validate(max128(low));
+        high = validate(max128(high));
+
+        if (low == 0) return high;
+        if (high == 0) return low;
+
+        uint8 tag = uint8(low >> 120);
+        if (tag == uint8(high >> 120)) revert DuplicateTag(tag);
+
+        cur = low | (high << 128);
+    }
+
+    /// @notice Swap the lower and higher cursors.
+    /// @param cur Packed cursor pair.
+    /// @return updated Pair with its lanes exchanged.
+    function swap(uint cur) internal pure returns (uint updated) {
+        updated = (cur << 128) | (cur >> 128);
+    }
+
+    /// @notice Return whether either packed cursor has the nonzero `expected` tag.
+    /// @dev Tag zero denotes an untagged cursor and is never matched by this helper.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param expected Nonzero identity tag to find.
+    /// @return Whether either lane has the requested tag.
+    function contains(uint cur, uint8 expected) internal pure returns (bool) {
+        return expected != 0 && (uint8(cur >> 120) == expected || uint8(cur >> 248) == expected);
+    }
+
+    /// @notice Move the cursor with `expected` into the lower position.
+    /// @dev If both cursors share the tag, the existing lower cursor is retained.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param expected Identity tag to select.
+    /// @return updated Cursor word with the selected lane in the lower position.
+    function select(uint cur, uint8 expected) internal pure returns (uint updated) {
+        if (uint8(cur >> 120) == expected) return cur;
+
+        updated = swap(cur);
+        if (uint8(updated >> 120) != expected) revert MissingTag(expected);
+    }
+
+    // Consumption
+
+    /// @notice Return a cursor's absolute position and advance it.
+    /// @dev Intended for fixed-width consumers that know their complete encoded size.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param amount Number of bytes to consume.
+    /// @return updated Cursor advanced by `amount`.
+    /// @return abs Absolute pre-advance position.
+    function consume(uint cur, uint amount) internal pure returns (uint updated, uint abs) {
+        abs = Cursors.absolute(cur);
+        updated = advance(cur, amount);
+    }
+
+    /// @notice Select a tagged cursor, return its absolute position, and advance it.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param tag Identity tag to select.
+    /// @param amount Number of bytes to consume.
+    /// @return updated Cursor pair with the selected lane advanced.
+    /// @return abs Absolute pre-advance position in the selected lane.
+    function consume(uint cur, uint8 tag, uint amount) internal pure returns (uint updated, uint abs) {
+        updated = select(cur, tag);
+        (updated, abs) = consume(updated, amount);
+    }
+}

package/utils/Lanes.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @notice Conventional identifiers shared by endpoint execution lanes.
+library Lanes {
+    /// @dev Decoder lane containing endpoint input blocks.
+    uint8 internal constant Input = 1;
+    /// @dev Decoder lane containing command state blocks.
+    uint8 internal constant State = 2;
+    /// @dev Writer lane containing regular endpoint output blocks.
+    uint8 internal constant Output = 3;
+    /// @dev Writer lane containing deferred transaction blocks.
+    uint8 internal constant Transactions = 4;
+}

package/utils/Selectors.sol

@@ -6,9 +6,9 @@ pragma solidity ^0.8.33;
 library Selectors {
     /// @notice Derive the ABI selector for a command entrypoint.
     /// @param name Command function name.
-    /// @return Selector for `name((bytes32,bytes,bytes))`.
+    /// @return Selector for `name(bytes32,bytes,bytes)`.
     function command(string memory name) internal pure returns (bytes4) {
-        return derive(name, "((bytes32,bytes,bytes))");
+        return derive(name, "(bytes32,bytes,bytes)");
     }
 
     /// @notice Derive the ABI selector for a port entrypoint.

package/utils/Utils.sol

@@ -83,6 +83,52 @@ function max160(uint value) pure returns (uint) {
     return value;
 }
 
+// Packed fields
+
+/// @notice Clear the 8-bit field beginning at `shift`.
+function clear8(uint value, uint shift) pure returns (uint) {
+    return value & ~(uint(type(uint8).max) << shift);
+}
+
+/// @notice Clear the 16-bit field beginning at `shift`.
+function clear16(uint value, uint shift) pure returns (uint) {
+    return value & ~(uint(type(uint16).max) << shift);
+}
+
+/// @notice Clear the 32-bit field beginning at `shift`.
+function clear32(uint value, uint shift) pure returns (uint) {
+    return value & ~(uint(type(uint32).max) << shift);
+}
+
+/// @notice Clear the 64-bit field beginning at `shift`.
+function clear64(uint value, uint shift) pure returns (uint) {
+    return value & ~(uint(type(uint64).max) << shift);
+}
+
+/// @notice Replace the 8-bit field beginning at `shift` with `field`.
+/// @dev Reverts when `field` does not fit in 8 bits.
+function replace8(uint value, uint shift, uint field) pure returns (uint) {
+    return clear8(value, shift) | (max8(field) << shift);
+}
+
+/// @notice Replace the 16-bit field beginning at `shift` with `field`.
+/// @dev Reverts when `field` does not fit in 16 bits.
+function replace16(uint value, uint shift, uint field) pure returns (uint) {
+    return clear16(value, shift) | (max16(field) << shift);
+}
+
+/// @notice Replace the 32-bit field beginning at `shift` with `field`.
+/// @dev Reverts when `field` does not fit in 32 bits.
+function replace32(uint value, uint shift, uint field) pure returns (uint) {
+    return clear32(value, shift) | (max32(field) << shift);
+}
+
+/// @notice Replace the 64-bit field beginning at `shift` with `field`.
+/// @dev Reverts when `field` does not fit in 64 bits.
+function replace64(uint value, uint shift, uint field) pure returns (uint) {
+    return clear64(value, shift) | (max64(field) << shift);
+}
+
 /// @notice Assert that `n` is evenly divisible by `divisor`.
 /// No-op when `divisor` is zero.
 function divisible(uint n, uint divisor) pure {

package/Cursors.sol

@@ -1,16 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-// Aggregator: re-exports all block stream primitives (Cursors, Readers, Writers, Schema, Keys, Sizes).
-// Import this file to get access to the full block encoding/decoding surface in one import.
-
-import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
-import { Forms, Sizes } from "./blocks/Schema.sol";
-import { Keys } from "./blocks/Keys.sol";
-import { Schemas } from "./blocks/Schema.sol";
-import { Cursors, Cur, Readers, Reader } from "./blocks/Cursors.sol";
-import { Writer, Writers, Hints } from "./blocks/Writers.sol";
-
-
-
-