@rootzero/contracts 1.13.0 → 1.15.0

package/queries/Assets.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 asset status queries.
 abstract contract AssetStatusHook {
     /// @notice Resolve support status for one asset.
     /// Concrete implementations define the support policy and optional context codes.
@@ -17,28 +18,27 @@ abstract contract AssetStatusHook {
 
 /// @title AssetStatus
 /// @notice Rootzero query that checks support status for one or more assets.
-/// The request is a run of `ASSET` blocks.
-/// The response returns one `STATUS` form block per query entry, preserving request order.
+/// The input is a run of `ASSET` blocks.
+/// The response returns one `STATUS` form block per query entry, preserving input order.
 abstract contract AssetStatus is QueryBase, AssetStatusHook {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = query("assetStatus", Keys.Asset, Keys.Status, 0);
+        (, descriptor) = query("assetStatus", Specs.Asset, Specs.Status);
     }
 
     /// @notice Resolve asset support status for a run of requested assets.
-    /// @param request Block-stream request consisting of `asset { bytes32 asset }` blocks.
+    /// @param input Block-stream input consisting of `asset { bytes32 asset }` blocks.
     /// @return Block-stream response containing one `status { uint code }` form block per asset block.
-    function assetStatus(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory input, uint outputs) = openInput(request, descriptor);
-        Writer memory response = Writers.allocStatuses(outputs);
+    function assetStatus(bytes calldata input) external view returns (bytes memory) {
+        Execution memory exec = openInput(input, descriptor, 0);
 
-        while (input.i < input.len) {
-            bytes32 asset = input.unpackAsset();
+        while (exec.more()) {
+            bytes32 asset = exec.unpackAsset(Lanes.Input);
             uint status = assetStatus(asset);
-            response.appendStatus(status);
+            exec.outputStatus(status);
         }
 
-        return response.finish();
+        return close(exec);
     }
 }

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,44 @@
 pragma solidity ^0.8.33;
 
 import { EndpointBase } from "../core/Endpoint.sol";
+import { Descriptors } from "../codec/Descriptors.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) {
+        descriptor = Descriptors.create(Specs.Empty, input, output, 0, 0);
+        return query(name, descriptor);
+    }
+
+    /// @notice Publish an already constructed query descriptor and default label.
+    /// @param name Query entrypoint name and default label. It must exactly
+    /// match the Solidity query function name used by the canonical ABI.
+    /// @param descriptor Packed query endpoint descriptor.
+    /// @return id Query node ID.
+    /// @return published Published endpoint descriptor.
+    function query(
+        string memory name,
+        uint descriptor
+    ) internal returns (uint id, uint published) {
+        id = Nodes.toQuery(Selectors.query(name), address(this));
+        published = endpoint(id, name, descriptor);
     }
 }

package/utils/Accounts.sol

@@ -10,7 +10,6 @@ import {ensureAddr, isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol"
 ///
 /// Account IDs embed a 4-byte type tag in bits [255:224]:
 ///   - `Admin`    — chain-local EVM address in bits [191:32]
-///   - `Guardian` — chain-local EVM address in bits [191:32]
 ///   - `User`     — chain-agnostic EVM address in bits [191:32]
 ///
 /// If the first byte is zero, the account is an opaque
@@ -26,8 +25,6 @@ library Accounts {
     uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Account);
     /// @dev Full 4-byte type prefix for admin accounts (chain-local EVM address).
     uint32 constant Admin = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Admin);
-    /// @dev Full 4-byte type prefix for guardian accounts (chain-local EVM address).
-    uint32 constant Guardian = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Guardian);
     /// @dev Full 4-byte type prefix for user accounts (chain-agnostic EVM address).
     uint32 constant User = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
 
@@ -53,11 +50,6 @@ library Accounts {
         return prefix(account) == Admin;
     }
 
-    /// @notice Return true if `account` is a guardian account.
-    function isGuardian(bytes32 account) internal pure returns (bool) {
-        return prefix(account) == Guardian;
-    }
-
     /// @notice Return true if `account` is a user account.
     function isUser(bytes32 account) internal pure returns (bool) {
         return prefix(account) == User;
@@ -87,14 +79,6 @@ library Accounts {
         return value;
     }
 
-    /// @notice Assert that `value` is a guardian account and return it unchanged.
-    /// @param value Account identifier to validate.
-    /// @return account The same `value` if it is a guardian account.
-    function guardian(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isGuardian(value)) revert InvalidAccount();
-        return value;
-    }
-
     /// @notice Assert that `value` is a user account and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is a user account.
@@ -110,13 +94,6 @@ library Accounts {
         return bytes32(toLocalBase(Admin) | (uint(uint160(account)) << 32));
     }
 
-    /// @notice Encode an EVM address as a chain-local guardian account ID.
-    /// @param account EVM address to embed.
-    /// @return Guardian account ID bound to the current chain.
-    function toGuardian(address account) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Guardian) | (uint(uint160(account)) << 32));
-    }
-
     /// @notice Encode an EVM address as a chain-agnostic user account ID.
     /// @param account EVM address to embed.
     /// @return User account ID without a chain binding.

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,367 @@
+// 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 cursor is one 128-bit value with this layout. A pair is a 256-bit value
+/// containing a lower cursor in bits 0-127 and an optional higher cursor in
+/// bits 128-255. The lower cursor is the active cursor: navigation and
+/// inspection operations target it, and `select` swaps a requested tagged
+/// cursor into that position while preserving the pair.
+///
+/// A mark is a standalone cursor value used as an immutable positional
+/// reference. It retains the cursor's offset, length, groups, flags, and tag,
+/// but may carry a different `i`. A mark has no intrinsic boundary or movement
+/// semantics; callers may later use its position for comparison, validation,
+/// seeking, or another operation. Because it has the ordinary single-cursor
+/// layout, existing positional decoding and absolute-position rules also apply
+/// to marks. A zero mark identifies the empty cursor at position zero; `before`
+/// therefore treats it as already reached.
+///
+/// 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 matches the requested identity.
+    error MissingCursor();
+
+    // 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 active cursor without its position.
+    /// @dev Ignores the upper cursor when `cur` is a pair.
+    /// @param cur Packed cursor or cursor pair.
+    /// @return The lower cursor's offset, length, groups, flags, and tag.
+    function frame(uint cur) internal pure returns (uint) {
+        return clear32(uint128(cur), 0);
+    }
+
+    /// @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 Require the lower cursor to be positioned at absolute position `abs`.
+    /// @param cur Packed cursor or cursor pair.
+    /// @param abs Expected absolute position.
+    function expectAbs(uint cur, uint abs) internal pure {
+        if (absolute(cur) != abs) 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 MissingCursor();
+    }
+
+    // Marks
+
+    /// @notice Select the live cursor whose frame matches the active cursor in `mark`.
+    /// @dev Only the lower 128 bits of `mark` are considered. The returned value
+    /// preserves the cursor pair and places the matching cursor in the lower half.
+    /// A zero frame may select an empty cursor lane.
+    /// @param cur Packed cursor or cursor pair to search.
+    /// @param mark Cursor-shaped positional reference to match.
+    /// @return located Cursor pair with the matching cursor active.
+    function locate(uint cur, uint mark) internal pure returns (uint located) {
+        uint expected = frame(mark);
+        if (frame(cur) == expected) return cur;
+
+        located = swap(cur);
+        if (frame(located) != expected) revert MissingCursor();
+    }
+
+    /// @notice Return whether a matched cursor is positioned before `mark`.
+    /// @dev Returns false at the mark and reverts after it. Only the active lower
+    /// cursor in `mark` participates in the comparison. A zero mark represents
+    /// the already-reached position of an empty cursor.
+    /// @param cur Packed cursor or cursor pair containing the marked cursor.
+    /// @param mark Cursor-shaped positional reference.
+    /// @return Whether the live cursor position precedes the marked position.
+    function before(uint cur, uint mark) internal pure returns (bool) {
+        uint i = uint32(locate(cur, mark));
+        uint target = uint32(mark);
+        if (i > target) revert OutOfBounds();
+        return i < target;
+    }
+
+    // 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/Layout.sol

@@ -40,8 +40,6 @@ library Layout {
 
     /// @dev Admin account — chain-local, backed by an EVM address.
     uint8 constant Admin = 0x01;
-    /// @dev Guardian account — chain-local, backed by an EVM address.
-    uint8 constant Guardian = 0x02;
     /// @dev User account — chain-agnostic, backed by an EVM address.
     uint8 constant User = 0x03;
     // -------------------------------------------------------------------------

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.