@rootzero/contracts 1.14.0 → 1.16.0

package/utils/Cursors.sol

@@ -12,47 +12,57 @@ struct Cur {
 }
 
 /// @title Cursors
-/// @notice Packed cursor state and navigation for grouped byte regions.
+/// @notice Packed cursor state and navigation for 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  96-111   count (opaque consumer metadata)
 /// 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.
+///
+/// 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, count, 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 has the requested tag.
-    error MissingTag(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 items Opaque item count associated with the region.
     /// @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) {
+    function create(uint offset, uint len, uint items, uint8 flags, uint8 tag) internal pure returns (uint cur) {
         cur |= max32(offset) << 32;
         cur |= max32(len) << 64;
-        cur |= max16(groups) << 96;
+        cur |= max16(items) << 96;
         cur |= uint(flags) << 112;
         cur |= uint(tag) << 120;
     }
@@ -97,6 +107,14 @@ library Cursors {
         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, count, 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.
@@ -107,15 +125,20 @@ library Cursors {
 
     /// @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 items Opaque item 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);
+    function meta(uint cur) internal pure returns (uint items, uint8 flags, uint8 tag) {
+        items = uint16(cur >> 96);
         flags = uint8(cur >> 112);
         tag = uint8(cur >> 120);
     }
 
+    /// @notice Return the opaque item count attached to the active cursor.
+    function count(uint cur) internal pure returns (uint) {
+        return uint16(cur >> 96);
+    }
+
     /// @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.
@@ -144,6 +167,13 @@ library Cursors {
         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.
@@ -205,7 +235,7 @@ library Cursors {
     }
 
     /// @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
+    /// @dev The child starts at position zero, has no recorded count, 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.
@@ -220,22 +250,6 @@ library Cursors {
 
     // 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.
@@ -279,7 +293,38 @@ library Cursors {
         if (uint8(cur >> 120) == expected) return cur;
 
         updated = swap(cur);
-        if (uint8(updated >> 120) != expected) revert MissingTag(expected);
+        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

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/commands/admin/Label.sol

@@ -1,36 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
-using Executions for Execution;
-
-/// @title Label
-/// @notice Admin command that publishes namespaced labels for node IDs.
-/// Each LABEL block in the input emits one `Labeled` event. Only callable by
-/// the admin account.
-abstract contract Label is AdminBase {
-    uint private immutable descriptor;
-
-    constructor() {
-        (, descriptor) = command("label", Specs.Empty, Specs.Label, Specs.Empty, 0, false, true);
-    }
-
-    /// @notice Publish each LABEL block in the admin input.
-    /// @param input LABEL block stream.
-    /// @return Empty output state.
-    /// @return Empty transaction stream.
-    function label(
-        bytes32 account,
-        bytes calldata,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
-
-        while (exec.more()) {
-            (uint node, bytes32 namespace, string memory name) = exec.unpackLabel(Lanes.Input);
-            emit Labeled(node, namespace, name);
-        }
-
-        return close(exec, account);
-    }
-}

package/commands/admin/Schemas.sol

@@ -1,36 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
-using Executions for Execution;
-
-/// @title PublishSchema
-/// @notice Admin command that publishes block schemas for keys.
-/// Each SCHEMA block in the input emits one `Schema` event. Only callable by
-/// the admin account.
-abstract contract PublishSchema is AdminBase {
-    uint private immutable descriptor;
-
-    constructor() {
-        (, descriptor) = command("publishSchema", Specs.Empty, Specs.Schema, Specs.Empty, 0, false, true);
-    }
-
-    /// @notice Publish each SCHEMA block in the admin input.
-    /// @param input SCHEMA block stream.
-    /// @return Empty output state.
-    /// @return Empty transaction stream.
-    function publishSchema(
-        bytes32 account,
-        bytes calldata,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
-
-        while (exec.more()) {
-            (uint spec, string memory body, bytes32 name) = exec.unpackSchema(Lanes.Input);
-            emit Schema(host, spec, body, name);
-        }
-
-        return close(exec, account);
-    }
-}

package/events/Labeled.sol

@@ -1,21 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {EventEmitter} from "./Emitter.sol";
-
-/// @notice Emitted to attach a human-readable namespaced label to an entity.
-/// @dev Labels are claims by the emitting contract. Any contract may emit a
-/// label for any entity, so off-chain indexers must decide which emitters are
-/// trusted for each labeled entity or namespace.
-abstract contract LabeledEvent is EventEmitter {
-    string private constant ABI = "event Labeled(uint indexed entity, bytes32 namespace, string name)";
-
-    /// @param entity Entity being labeled.
-    /// @param namespace Label namespace.
-    /// @param name Human-readable name within the namespace.
-    event Labeled(uint indexed entity, bytes32 namespace, string name);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}

package/events/Position.sol

@@ -1,22 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {EventEmitter} from "./Emitter.sol";
-
-/// @notice Emitted when the reported value of an asset-backed position changes or is observed.
-/// A value of 0 should be interpreted as a closed position.
-abstract contract PositionEvent is EventEmitter {
-    string private constant ABI = "event Position(bytes32 indexed account, bytes32 asset, uint value, uint32 action, uint context, uint queryId)";
-
-    /// @param account Account identifier that owns or is associated with the position.
-    /// @param asset Asset identifier for the asset class.
-    /// @param value Context-specific position value; 0 indicates a closed position.
-    /// @param action Primary operation hint from `Actions`.
-    /// @param context Reserved context value for future use.
-    /// @param queryId Query ID associated with the position lookup or reporting context.
-    event Position(bytes32 indexed account, bytes32 asset, uint value, uint32 action, uint context, uint queryId);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}

package/events/Schema.sol

@@ -1,23 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {EventEmitter} from "./Emitter.sol";
-
-/// @title SchemaEvent
-/// @notice Emitted during host deployment to publish a block spec and payload schema.
-/// Block keys are opaque `bytes4` tags. Standard protocol blocks use
-/// keccak-derived keys by convention, but custom block keys only need to be
-/// unique within the publishing host/schema context.
-abstract contract SchemaEvent is EventEmitter {
-    string private constant ABI = "event Schema(uint indexed host, uint spec, string body, bytes32 name)";
-
-    /// @param host Host node ID that publishes this block schema.
-    /// @param spec Block specification being defined by `host`.
-    /// @param body Schema DSL string describing the block payload body.
-    /// @param name Optional block alias used by endpoint descriptors and nested schemas.
-    event Schema(uint indexed host, uint spec, string body, bytes32 name);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}