@rootzero/contracts 1.13.0 → 1.15.0

package/codec/Descriptors.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Specs} from "./Specs.sol";
+import {Lanes} from "../utils/Lanes.sol";
+
+/// @title Descriptors
+/// @notice Packing and lane metadata helpers for endpoint descriptors.
+library Descriptors {
+    /// @dev The requested lane is not part of an endpoint descriptor.
+    error InvalidLane();
+
+    /// @dev Endpoint accepts nonzero native value.
+    uint8 internal constant Funded = 1 << 0;
+    /// @dev Endpoint is restricted to the admin account.
+    uint8 internal constant Admin = 1 << 1;
+
+    /// @notice Create a descriptor from endpoint lane specifications and flags.
+    /// @dev Layout: `[state key:4][stride:1]`
+    /// `[input key:4][item:4][stride:1]`
+    /// `[output key:4][min:4][max:4][hint:3][stride:1]`
+    /// `[transactions:1]`
+    /// `[flags:1]`. Flag bits: funded = 0, admin = 1.
+    /// @param state State lane specification.
+    /// @param input Input lane specification, optionally wrapped in a container.
+    /// @param output Output writer specification.
+    /// @param transactions Transactions produced per batch.
+    /// @param flags Endpoint behavior flags.
+    /// @return descriptor Packed endpoint descriptor.
+    function create(
+        uint state,
+        uint input,
+        uint output,
+        uint8 transactions,
+        uint8 flags
+    ) internal pure returns (uint descriptor) {
+        state = Specs.normalize(state, true);
+        input = Specs.normalize(input, false);
+        output = Specs.normalize(output, true);
+
+        descriptor = pack(state, input, output, transactions, flags);
+    }
+
+    /// @dev Pack normalized endpoint specs and flags into a descriptor.
+    /// @param state Normalized direct state specification.
+    /// @param input Normalized input specification.
+    /// @param output Normalized direct output specification.
+    /// @param transactions Transactions produced per batch.
+    /// @param flags Endpoint behavior flags.
+    /// @return descriptor Packed endpoint descriptor.
+    function pack(
+        uint state,
+        uint input,
+        uint output,
+        uint8 transactions,
+        uint8 flags
+    ) private pure returns (uint descriptor) {
+        (bytes4 outer, bytes4 child) = Specs.keys(input);
+
+        descriptor |= uint(uint32(Specs.key(state))) << 224;
+        descriptor |= uint(Specs.stride(state)) << 216;
+        descriptor |= uint(uint32(outer)) << 184;
+        descriptor |= uint(uint32(child)) << 152;
+        descriptor |= uint(Specs.stride(input)) << 144;
+        descriptor |= (output >> 128) << 16;
+        descriptor |= uint(transactions) << 8;
+        descriptor |= flags;
+    }
+
+    /// @notice Return whether a descriptor contains `flag`.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param flag Flag bit or bit set to test.
+    /// @return Whether any requested flag bit is present.
+    function flagged(uint descriptor, uint8 flag) internal pure returns (bool) {
+        return uint8(descriptor) & flag != 0;
+    }
+
+    /// @notice Return the effective per-batch stride for `lane`.
+    /// @dev Descriptor creation resolves implicit spec strides, so every lane
+    /// stores its effective value directly.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param lane Lane identifier from `Lanes`.
+    /// @return Effective blocks per batch for the lane.
+    function stride(uint descriptor, uint8 lane) internal pure returns (uint8) {
+        if (lane == Lanes.State) return uint8(descriptor >> 216);
+        if (lane == Lanes.Input) return uint8(descriptor >> 144);
+        if (lane == Lanes.Output) return uint8(descriptor >> 16);
+        if (lane == Lanes.Transactions) return uint8(descriptor >> 8);
+        revert InvalidLane();
+    }
+
+    /// @notice Return the effective block key for `lane`.
+    /// @dev Input returns its outer key. Transaction blocks have a fixed
+    /// protocol key that is not stored in the descriptor.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param lane Lane identifier from `Lanes`.
+    /// @return Effective outer block key for the lane.
+    function key(uint descriptor, uint8 lane) internal pure returns (bytes4) {
+        if (lane == Lanes.State) return bytes4(uint32(descriptor >> 224));
+        if (lane == Lanes.Input) return bytes4(uint32(descriptor >> 184));
+        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 112));
+        if (lane == Lanes.Transactions) return Specs.key(Specs.Transaction);
+        revert InvalidLane();
+    }
+
+    /// @notice Return the buffer configuration for descriptor writer `lane`.
+    /// @param descriptor Packed endpoint descriptor.
+    /// @param lane Output or transaction writer lane.
+    /// @param groups Number of execution batches to allocate for.
+    /// @return capacity Initial logical byte capacity.
+    /// @return growable Whether the writer may grow beyond that capacity.
+    function allocation(uint descriptor, uint8 lane, uint groups) internal pure returns (uint capacity, bool growable) {
+        if (lane == Lanes.Output) {
+            uint spec = uint(uint128(descriptor >> 16)) << 128;
+            return Specs.allocation(spec, groups);
+        }
+        if (lane == Lanes.Transactions) {
+            uint count = groups * stride(descriptor, lane);
+            return Specs.allocation(Specs.Transaction, count);
+        }
+
+        revert InvalidLane();
+    }
+}

package/{blocks → codec}/Keys.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 /// @notice Standard block type selectors for the rootzero block stream protocol.
 /// Standard keys use the first 4 bytes of `keccak256("#name")` by convention.
 /// Custom block keys only need to be unique in the context where they are used;
-/// hosts may publish custom key meanings with the `Schema` event.
+/// hosts may publish custom key meanings with `#schema` annotations.
 library Keys {
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
@@ -15,18 +15,12 @@ library Keys {
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
     bytes4 constant Balance = bytes4(keccak256("#balance"));
-    /// @dev Balance constraint - (bytes32 asset, uint min, uint max)
-    bytes4 constant BalanceLimit = bytes4(keccak256("#balanceLimit"));
-    /// @dev Host-scoped request amount - (uint host, bytes32 asset, uint amount)
+    /// @dev Host-scoped input amount - (uint host, bytes32 asset, uint amount)
     bytes4 constant Allocation = bytes4(keccak256("#allocation"));
     /// @dev Host-scoped allowance cap - (uint host, bytes32 asset, uint amount)
     bytes4 constant Allowance = bytes4(keccak256("#allowance"));
     /// @dev Cross-host custody state - (uint host, bytes32 asset, uint amount)
     bytes4 constant Custody = bytes4(keccak256("#custody"));
-    /// @dev Cross-host custody constraint - (uint host, bytes32 asset, uint min, uint max)
-    bytes4 constant CustodyLimit = bytes4(keccak256("#custodyLimit"));
-    /// @dev Fee amount - (uint amount)
-    bytes4 constant Fee = bytes4(keccak256("#fee"));
     /// @dev List wrapper; payload is an embedded repeated block stream
     bytes4 constant List = bytes4(keccak256("#list"));
     /// @dev EVM-encoded payload field; layout follows standard ABI tuple encoding
@@ -39,11 +33,11 @@ library Keys {
     bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, uint amount)
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
-    /// @dev Sub-command invocation - (uint target, uint resources, #bytes as request)
+    /// @dev Sub-command invocation - (uint cmd, uint resources, #bytes as input)
     bytes4 constant Step = bytes4(keccak256("#step"));
-    /// @dev Portal relay request - (uint portal, uint resources, #bytes as request)
+    /// @dev Portal relay input - (uint portal, uint resources, #bytes as input)
     bytes4 constant Relay = bytes4(keccak256("#relay"));
-    /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)
+    /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as input)
     bytes4 constant Context = bytes4(keccak256("#context"));
     /// @dev Recoverable witness - (uint handler, uint resources, bytes32 key, #bytes as witness)
     bytes4 constant Recover = bytes4(keccak256("#recover"));
@@ -51,23 +45,21 @@ library Keys {
     bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
     /// @dev Raw external call - (uint target, uint resources, #bytes as payload)
     bytes4 constant Call = bytes4(keccak256("#call"));
-    /// @dev Authentication proof - (uint cid, uint deadline, #bytes as proof); must appear last in its segment
-    bytes4 constant Auth = bytes4(keccak256("#auth"));
     /// @dev Asset descriptor without amount - (bytes32 asset)
     bytes4 constant Asset = bytes4(keccak256("#asset"));
     /// @dev Node identifier - (uint id)
     bytes4 constant Node = bytes4(keccak256("#node"));
-    /// @dev Relayer bounty - (uint amount, bytes32 relayer)
-    bytes4 constant Bounty = bytes4(keccak256("#bounty"));
-    /// @dev Mutable node label - (uint id, bytes32 namespace, #string as name)
+    /// @dev Entity label annotation - (bytes32 namespace, #string as name)
     bytes4 constant Label = bytes4(keccak256("#label"));
+    /// @dev Entity annotations - (uint entity, #bytes as data)
+    bytes4 constant Annotation = bytes4(keccak256("#annotation"));
+    /// @dev Primary semantic action annotation - (uint action)
+    bytes4 constant Action = bytes4(keccak256("#action"));
     /// @dev Block schema publication - (bytes4 key, #string as body, bytes32 name)
     bytes4 constant Schema = bytes4(keccak256("#schema"));
 
     /// @dev Structural status form - (uint code)
     bytes4 constant Status = bytes4(keccak256("#status"));
-    /// @dev Structural asset amount form - (bytes32 asset, uint amount)
-    bytes4 constant AssetAmount = bytes4(keccak256("#assetAmount"));
     /// @dev Structural account asset form - (bytes32 account, bytes32 asset)
     bytes4 constant AccountAsset = bytes4(keccak256("#accountAsset"));
     /// @dev Structural account amount form - (bytes32 account, bytes32 asset, uint amount)

package/codec/Readers.sol

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Sizes, Specs} from "./Specs.sol";
+import {Keys} from "./Keys.sol";
+
+/// @notice Mutable reader over a block stream stored in memory.
+/// All positions (`i`) are byte offsets relative to the start of `source`.
+struct Reader {
+    /// @dev Current read position, relative to the source start.
+    uint i;
+    /// @dev Memory bytes containing the complete source region.
+    bytes source;
+}
+
+using Readers for Reader;
+
+/// @title Readers
+/// @notice Memory block stream parser for the rootzero protocol.
+/// A `Reader` advances through an existing `bytes memory` source without copying its contents.
+/// Blocks are encoded as `[bytes4 key][bytes4 payloadLen][payload]`.
+library Readers {
+    /// @dev The current block has a truncated header or payload, an unexpected key,
+    ///      or a payload size outside the accepted range.
+    error InvalidBlock();
+
+    /// @notice Create a reader backed by a memory byte array.
+    /// @param source Memory bytes containing the block stream.
+    /// @return cur Reader positioned at the beginning of `source`.
+    function open(bytes memory source) internal pure returns (Reader memory cur) {
+        cur.source = source;
+    }
+
+    /// @notice Return whether the reader has consumed its entire source.
+    /// @param cur Reader whose position should be checked.
+    /// @return Whether `cur.i` equals the source length.
+    function done(Reader memory cur) internal pure returns (bool) {
+        return cur.i == cur.source.length;
+    }
+
+    /// @notice Return whether the reader has bytes left to consume.
+    /// @param cur Reader whose position should be checked.
+    /// @return Whether `cur.i` differs from the source length.
+    function more(Reader memory cur) internal pure returns (bool) {
+        return cur.i != cur.source.length;
+    }
+
+    /// @notice Validate and consume the current block, advancing `cur.i` past it.
+    /// @param cur Reader to advance.
+    /// @param key Expected block key.
+    /// @param min Minimum payload length.
+    /// @param max Maximum payload length; zero means unbounded.
+    /// @return abs Absolute memory address of the payload start.
+    function consume(
+        Reader memory cur,
+        bytes4 key,
+        uint min,
+        uint max
+    ) private pure returns (uint abs) {
+        bytes memory source = cur.source;
+        uint i = cur.i;
+
+        if (i > source.length || source.length - i < Sizes.Header) revert InvalidBlock();
+
+        bytes4 current;
+        uint len;
+        assembly ("memory-safe") {
+            let header := mload(add(add(source, 0x20), i))
+            current := header
+            len := and(shr(192, header), 0xffffffff)
+            abs := add(add(source, 0x28), i)
+        }
+
+        if (current != key || len < min || (max != 0 && len > max)) revert InvalidBlock();
+        if (len > source.length - i - Sizes.Header) revert InvalidBlock();
+        cur.i = i + Sizes.Header + len;
+    }
+
+    /// @notice Validate and consume the current block described by `spec`.
+    function consume(Reader memory cur, uint spec) internal pure returns (uint abs) {
+        (bytes4 key, uint32 min, uint32 max) = Specs.decode(spec);
+        return consume(cur, key, min, max);
+    }
+
+    /// @notice Consume a BALANCE block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return asset Asset identifier.
+    /// @return amount Token amount.
+    function unpackBalance(Reader memory cur) internal pure returns (bytes32 asset, uint amount) {
+        uint abs = consume(cur, Keys.Balance, 64, 64);
+        assembly ("memory-safe") {
+            asset := mload(abs)
+            amount := mload(add(abs, 0x20))
+        }
+    }
+
+    /// @notice Consume a TRANSACTION block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return from Source account identifier.
+    /// @return to Destination account identifier.
+    /// @return asset Asset identifier.
+    /// @return amount Token amount.
+    function unpackTransaction(
+        Reader memory cur
+    ) internal pure returns (bytes32 from, bytes32 to, bytes32 asset, uint amount) {
+        uint abs = consume(cur, Keys.Transaction, 128, 128);
+        assembly ("memory-safe") {
+            from := mload(abs)
+            to := mload(add(abs, 0x20))
+            asset := mload(add(abs, 0x40))
+            amount := mload(add(abs, 0x60))
+        }
+    }
+}

package/{blocks → codec}/Schema.sol

@@ -12,7 +12,7 @@ pragma solidity ^0.8.33;
 // - an empty schema string means the block has no structured payload
 // - commas separate siblings at every level
 // - braces define the current block payload body
-// - command requests are a single run when the request schema is non-empty
+// - command inputs are a single run when the input schema is non-empty
 // - command state is a single active state run without trailing globals
 // - run items may repeat at top level for batching
 // - `maybe #x` marks an optional block item
@@ -36,11 +36,11 @@ pragma solidity ^0.8.33;
 // - generic lists use the stable key derived from `#list`
 // - standard keys are derived from block aliases, e.g. bytes4(keccak256("#amount"))
 // - custom keys are opaque bytes4 tags and only need to be unique in their
-//   active context; use `Schema(host, key, schema, name)` to publish their meaning
+//   active context; use a `#schema` annotation to publish their meaning
 // - see `docs/Schema.md` for the full working spec
 //
 // Pipeline state:
-// - command request and state streams are each a single run of blocks under the
+// - command input and state streams are each a single run of blocks under the
 //   current protocol convention; the block format may support other shapes in
 //   future protocol surfaces
 // - `balance(...)` and `custody(...)` are live, linear state in the active command pipeline
@@ -48,102 +48,65 @@ pragma solidity ^0.8.33;
 // - while a balance or custody is in-flight as pipeline state, it is not simultaneously persisted
 //   in another ledger/store by this protocol
 // - commands must preserve, transform, settle, or intentionally consume pipeline state
-// - request blocks such as `amount(...)`, `allocation(...)`, and `allowance(...)`
+// - input blocks such as `amount(...)`, `allocation(...)`, and `allowance(...)`
 //   express intent, constraints, or references
-// - request and value/response blocks are not live state
+// - input and value/response blocks are not live state
 //
-// Signed blocks:
-// - an authenticated input segment ends with one trailing AUTH block
-// - 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 Schemas
 /// @notice Human-readable schema string constants for each block type.
 /// These strings describe payload layout for discovery events and docs; block
 /// aliases map to standard keys by convention. Custom blocks may use any unique
 /// bytes4 key in their active context.
 library Schemas {
+    // Empty and reserved payloads
+
     string constant Unit = "";
-    string constant Node = "{ uint id }";
-    string constant Account = "{ bytes32 account }";
-    string constant Asset = "{ bytes32 asset }";
-    string constant Amount = "{ bytes32 asset, uint amount }";
-    string constant Balance = "{ bytes32 asset, uint amount }";
-    string constant BalanceLimit = "{ bytes32 asset, uint min, uint max }";
-    string constant Custody = "{ uint host, bytes32 asset, uint amount }";
-    string constant CustodyLimit = "{ uint host, bytes32 asset, uint min, uint max }";
-    string constant Allocation = "{ uint host, bytes32 asset, uint amount }";
-    string constant Allowance = "{ uint host, bytes32 asset, uint amount }";
-    string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
-    string constant Context = "{ bytes32 account, #bytes as state, #bytes as request }";
-    string constant Recover = "{ uint handler, uint resources, bytes32 key, #bytes as witness }";
-    string constant Call = "{ uint target, uint resources, #bytes as payload }";
-    string constant Step = "{ uint target, uint resources, #bytes as request }";
-    string constant Relay = "{ uint portal, uint resources, #bytes as request }";
-    string constant Dispatch = "{ uint portal, uint resources, #bytes as payload }";
-    string constant Bounty = "{ uint amount, bytes32 relayer }";
-    string constant Fee = "{ uint amount }";
-    string constant Auth = "{ uint cid, uint deadline, #bytes as proof }";
-    string constant Label = "{ uint id, bytes32 namespace, #string as name }";
-    string constant Schema = "{ bytes4 key, #string as body, bytes32 name }";
     string constant Bytes = "";
     string constant String = "";
     string constant List = "";
     string constant Evm = "";
-}
 
-/// @title Forms
-/// @notice Reusable structural block schemas for core tuple shapes.
-/// These describe payload form without assigning command or query semantics.
-library Forms {
+    // One-word payloads
+
+    string constant Node = "{ uint id }";
+    string constant Account = "{ bytes32 account }";
+    string constant Asset = "{ bytes32 asset }";
     string constant Status = "{ uint code }";
-    string constant AssetAmount = "{ bytes32 asset, uint amount }";
+
+    // Two-word payloads
+
+    string constant Amount = "{ bytes32 asset, uint amount }";
+    string constant Balance = "{ bytes32 asset, uint amount }";
     string constant AccountAsset = "{ bytes32 account, bytes32 asset }";
+
+    // Three-word payloads
+
+    string constant Allocation = "{ uint host, bytes32 asset, uint amount }";
+    string constant Allowance = "{ uint host, bytes32 asset, uint amount }";
+    string constant Custody = "{ uint host, bytes32 asset, uint amount }";
     string constant AccountAmount = "{ bytes32 account, bytes32 asset, uint amount }";
     string constant HostAmount = "{ uint host, bytes32 asset, uint amount }";
     string constant HostAccountAsset = "{ uint host, bytes32 account, bytes32 asset }";
+
+    // Four-word payloads
+
+    string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
     string constant HostAccountAmount = "{ uint host, bytes32 account, bytes32 asset, uint amount }";
-}
 
-/// @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 Shared block header size: 4-byte key + 4-byte payload length.
-    uint constant Header = 8;
-    /// @dev One fixed-width payload word.
-    uint constant Word = 32;
-    /// @dev 8 header + 32 payload = 40 bytes total.
-    uint constant B32 = Header + Word;
-    /// @dev 8 header + 64 payload = 72 bytes total.
-    uint constant B64 = Header + 2 * Word;
-    /// @dev 8 header + 96 payload = 104 bytes total.
-    uint constant B96 = Header + 3 * Word;
-    /// @dev 8 header + 128 payload = 136 bytes total.
-    uint constant B128 = Header + 4 * Word;
-    /// @dev 8 header + 160 payload = 168 bytes total.
-    uint constant B160 = Header + 5 * Word;
-    /// @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 + nested BYTES block with 85-byte proof = 165 bytes
-    uint constant Auth = B64 + Header + Proof;
-    /// @dev STATUS block: 8 header + 32 status code = 40 bytes
-    uint constant Status = B32;
-    /// @dev AMOUNT block: 8 header + 32 asset + 32 amount = 72 bytes
-    uint constant Amount = B64;
-    /// @dev BALANCE block: 8 header + 32 asset + 32 amount = 72 bytes
-    uint constant Balance = B64;
-    /// @dev BALANCE_LIMIT block: 8 header + 32 asset + 32 min + 32 max = 104 bytes
-    uint constant BalanceLimit = B96;
-    /// @dev FEE block: 8 header + 32 amount = 40 bytes
-    uint constant Fee = B32;
-    /// @dev BOUNTY block: 8 header + 32 amount + 32 relayer = 72 bytes
-    uint constant Bounty = B64;
-    /// @dev ALLOCATION/CUSTODY block: 8 header + 32 host + 32 asset + 32 amount = 104 bytes
-    uint constant HostAmount = B96;
-    /// @dev CUSTODY_LIMIT block: 8 header + 32 host + 32 asset + 32 min + 32 max = 136 bytes
-    uint constant CustodyLimit = B128;
-    /// @dev TRANSACTION block: 8 header + 32 from + 32 to + 32 asset + 32 amount = 136 bytes
-    uint constant Transaction = B128;
+    // Composite payloads
+
+    string constant Call = "{ uint target, uint resources, #bytes as payload }";
+    string constant Step = "{ uint cmd, uint resources, #bytes as input }";
+    string constant Relay = "{ uint portal, uint resources, #bytes as input }";
+    string constant Dispatch = "{ uint portal, uint resources, #bytes as payload }";
+    string constant Context = "{ bytes32 account, #bytes as state, #bytes as input }";
+    string constant Recover = "{ uint handler, uint resources, bytes32 key, #bytes as witness }";
+    string constant Annotation = "{ uint entity, #bytes as data }";
+
+    // Annotation payloads
+
+    string constant Action = "{ uint action }";
+    string constant Label = "{ bytes32 namespace, #string as name }";
+    string constant Schema = "{ uint spec, #string as body, bytes32 name }";
 }
+