@rootzero/contracts 1.12.0 → 1.14.0

package/{blocks → codec}/Keys.sol

@@ -7,38 +7,20 @@ pragma solidity ^0.8.33;
 /// 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.
 library Keys {
-    /// @notice Create a context-local block key.
-    /// @dev Local keys are opaque tags for host- or endpoint-specific schemas.
-    /// The caller is responsible for choosing values that are unique in the
-    /// context where they are used and publishing their meaning with `Schema`.
-    /// @param value Opaque local key value.
-    /// @return Context-local block key.
-    function local(uint32 value) internal pure returns (bytes4) {
-        return bytes4(value);
-    }
-
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
     /// @dev Wildcard key used in discovery when any block stream is accepted.
     bytes4 constant Any = 0xffffffff;
-    /// @dev Default context-local block key for hosts/endpoints that need one custom schema.
-    bytes4 constant Local = bytes4(uint32(1));
     /// @dev Input amount - (bytes32 asset, uint amount)
     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
@@ -51,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"));
@@ -63,14 +45,10 @@ 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)
     bytes4 constant Label = bytes4(keccak256("#label"));
     /// @dev Block schema publication - (bytes4 key, #string as body, bytes32 name)
@@ -78,8 +56,6 @@ library Keys {
 
     /// @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 `Schema(host, spec, schema, name)` 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,60 @@ 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 Label = "{ uint id, bytes32 namespace, #string as name }";
+    string constant Schema = "{ uint spec, #string as body, bytes32 name }";
 }
+

package/codec/Specs.sol

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Keys} from "./Keys.sol";
+import {max24, replace8, replace32} from "../utils/Utils.sol";
+
+/// @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 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 ALLOCATION/CUSTODY block: 8 header + 32 host + 32 asset + 32 amount = 104 bytes
+    uint constant HostAmount = B96;
+    /// @dev TRANSACTION block: 8 header + 32 from + 32 to + 32 asset + 32 amount = 136 bytes
+    uint constant Transaction = B128;
+}
+
+/// @title Specs
+/// @notice Word-aligned block specifications encoded as
+/// `[key:4][min:4][max:4][hint:3][stride:1][container:4][reserved:12]`.
+/// The upper eight bytes of a fixed-layout spec are its encoded block header,
+/// allowing the entire spec word to be written directly as that header.
+/// A maximum of zero means unbounded and requires a growable writer.
+library Specs {
+    /// @dev A payload is incompatible with its block specification.
+    error InvalidSpec();
+    /// @dev A direct specification cannot contain a wrapper block.
+    error InvalidContainer();
+
+    uint private constant SizeFields = (uint(1) << 192) | (uint(1) << 160) | (uint(1) << 136);
+
+    // Reusable field shapes keep public specs readable while remaining valid
+    // compile-time constant expressions.
+    uint private constant Exact32 = 32 * SizeFields;
+    uint private constant Exact64 = 64 * SizeFields;
+    uint private constant Exact96 = 96 * SizeFields;
+    uint private constant Exact128 = 128 * SizeFields;
+    uint private constant UnboundedHint128 = uint(128) << 136;
+    uint private constant UnboundedMin72Hint256 = (uint(72) << 192) | (uint(256) << 136);
+    uint private constant UnboundedMin48Hint512 = (uint(48) << 192) | (uint(512) << 136);
+    uint private constant UnboundedMin104Hint256 = (uint(104) << 192) | (uint(256) << 136);
+
+    uint constant Empty = uint(bytes32(Keys.Empty));
+    uint constant Any = uint(bytes32(Keys.Any)) | UnboundedHint128;
+    uint constant Amount = uint(bytes32(Keys.Amount)) | Exact64;
+    uint constant Balance = uint(bytes32(Keys.Balance)) | Exact64;
+    uint constant Allocation = uint(bytes32(Keys.Allocation)) | Exact96;
+    uint constant Allowance = uint(bytes32(Keys.Allowance)) | Exact96;
+    uint constant Custody = uint(bytes32(Keys.Custody)) | Exact96;
+    uint constant List = uint(bytes32(Keys.List)) | UnboundedHint128;
+    uint constant Evm = uint(bytes32(Keys.Evm)) | UnboundedHint128;
+    uint constant Bytes = uint(bytes32(Keys.Bytes)) | UnboundedHint128;
+    uint constant String = uint(bytes32(Keys.String)) | UnboundedHint128;
+    uint constant Account = uint(bytes32(Keys.Account)) | Exact32;
+    uint constant Transaction = uint(bytes32(Keys.Transaction)) | Exact128;
+    uint constant Step = uint(bytes32(Keys.Step)) | UnboundedMin72Hint256;
+    uint constant Relay = uint(bytes32(Keys.Relay)) | UnboundedMin72Hint256;
+    uint constant Context = uint(bytes32(Keys.Context)) | UnboundedMin48Hint512;
+    uint constant Recover = uint(bytes32(Keys.Recover)) | UnboundedMin104Hint256;
+    uint constant Dispatch = uint(bytes32(Keys.Dispatch)) | UnboundedMin72Hint256;
+    uint constant Call = uint(bytes32(Keys.Call)) | UnboundedMin72Hint256;
+    uint constant Asset = uint(bytes32(Keys.Asset)) | Exact32;
+    uint constant Node = uint(bytes32(Keys.Node)) | Exact32;
+    uint constant Label = uint(bytes32(Keys.Label)) | UnboundedMin72Hint256;
+    uint constant Schema = uint(bytes32(Keys.Schema)) | UnboundedMin72Hint256;
+
+    uint constant Status = uint(bytes32(Keys.Status)) | Exact32;
+    uint constant AccountAsset = uint(bytes32(Keys.AccountAsset)) | Exact64;
+    uint constant AccountAmount = uint(bytes32(Keys.AccountAmount)) | Exact96;
+    uint constant HostAmount = uint(bytes32(Keys.HostAmount)) | Exact96;
+    uint constant HostAccountAsset = uint(bytes32(Keys.HostAccountAsset)) | Exact96;
+    uint constant HostAccountAmount = uint(bytes32(Keys.HostAccountAmount)) | Exact128;
+
+    /// @notice Construct a block specification from its encoded fields.
+    /// @param blockkey Encoded block key.
+    /// @param min Minimum accepted payload length.
+    /// @param max Maximum accepted payload length; zero means unbounded.
+    /// @param hint Initial per-block payload capacity.
+    /// @return spec Packed block specification.
+    function create(bytes4 blockkey, uint32 min, uint32 max, uint32 hint) internal pure returns (uint spec) {
+        spec |= uint(uint32(blockkey)) << 224;
+        spec |= uint(min) << 192;
+        spec |= uint(max) << 160;
+        spec |= uint(max24(hint)) << 136;
+    }
+
+    /// @notice Decode the block key and accepted payload range from `spec`.
+    /// @param spec Packed block specification.
+    /// @return blockkey Encoded block key.
+    /// @return min Minimum accepted payload length.
+    /// @return max Maximum accepted payload length; zero means unbounded.
+    function decode(uint spec) internal pure returns (bytes4 blockkey, uint32 min, uint32 max) {
+        blockkey = bytes4(uint32(spec >> 224));
+        min = uint32(spec >> 192);
+        max = uint32(spec >> 160);
+    }
+
+    /// @notice Return the block key encoded in `spec`.
+    /// @param spec Packed block specification.
+    /// @return Encoded block key.
+    function key(uint spec) internal pure returns (bytes4) {
+        return bytes4(uint32(spec >> 224));
+    }
+
+    /// @notice Return the raw stride encoded in `spec`.
+    /// @dev Contextual defaults are applied by helpers such as `count`.
+    /// @param spec Packed block specification.
+    /// @return Encoded block stride.
+    function stride(uint spec) internal pure returns (uint8) {
+        return uint8(spec >> 128);
+    }
+
+    /// @notice Return the canonical form of `spec` with implicit defaults resolved.
+    /// @param spec Packed block specification.
+    /// @param direct Whether the specification must not contain a wrapper block.
+    /// @dev A present spec with an encoded zero stride receives stride one;
+    /// the empty spec remains unchanged.
+    /// @return Canonical specification.
+    function normalize(uint spec, bool direct) internal pure returns (uint) {
+        if (direct && uint32(spec >> 96) != 0) revert InvalidContainer();
+        if (stride(spec) == 0 && key(spec) != bytes4(0)) spec |= uint(1) << 128;
+        return spec;
+    }
+
+    /// @notice Return the effective outer block key and optional wrapped child key.
+    /// @dev A direct spec returns its own key as `outer` and a zero `child`.
+    /// @param spec Packed block specification.
+    /// @return outer Effective outer block key.
+    /// @return child Wrapped child key, or zero for a direct specification.
+    function keys(uint spec) internal pure returns (bytes4 outer, bytes4 child) {
+        child = key(spec);
+        outer = bytes4(uint32(spec >> 96));
+
+        if (outer == bytes4(0)) {
+            outer = child;
+            child = bytes4(0);
+        }
+    }
+
+    /// @notice Return whether a payload size lies within a specification's bounds.
+    /// @param spec Packed block specification.
+    /// @param size Payload length to test.
+    /// @return Whether the payload length is accepted.
+    function accepts(uint spec, uint size) internal pure returns (bool) {
+        uint32 min = uint32(spec >> 192);
+        uint32 max = uint32(spec >> 160);
+        return size >= min && (max == 0 || size <= max);
+    }
+
+    /// @notice Validate a payload size against a specification's bounds.
+    /// @param spec Packed block specification.
+    /// @param size Payload length to validate.
+    function validate(uint spec, uint size) internal pure {
+        if (!accepts(spec, size)) revert InvalidSpec();
+    }
+
+    /// @notice Return an exact payload size constrained to an accepted range.
+    /// @param spec Packed block specification.
+    /// @param min Smallest exact size accepted by the caller.
+    /// @param max Largest exact size accepted by the caller.
+    /// @return size Exact payload size encoded by the specification.
+    function exact(uint spec, uint min, uint max) internal pure returns (uint size) {
+        size = uint32(spec >> 192);
+        if (size != uint32(spec >> 160) || size < min || size > max) revert InvalidSpec();
+    }
+
+    /// @notice Return the number of blocks represented by `groups`.
+    /// @param spec Packed block specification.
+    /// @param groups Number of groups.
+    /// @return Number of blocks across all groups.
+    function count(uint spec, uint groups) internal pure returns (uint) {
+        return groups * stride(normalize(spec, false));
+    }
+
+    /// @notice Return the buffer configuration for `groups` of `spec`.
+    /// @dev Dynamic specs use their allocation hint and a maximum of zero means growable.
+    /// @param spec Packed block specification.
+    /// @param groups Number of groups to allocate.
+    /// @return capacity Initial encoded byte capacity.
+    /// @return growable Whether the buffer may grow beyond its initial capacity.
+    function allocation(uint spec, uint groups) internal pure returns (uint capacity, bool growable) {
+        capacity = count(spec, groups) * (Sizes.Header + uint24(spec >> 136));
+        growable = uint32(spec >> 160) == 0;
+    }
+
+    /// @notice Return `spec` annotated as a generic LIST item.
+    /// @param spec Child block specification.
+    /// @return Specification wrapped in a LIST container.
+    function many(uint spec) internal pure returns (uint) {
+        return replace32(spec, 96, uint32(key(List)));
+    }
+
+    /// @notice Return `spec` grouped with an explicit stride.
+    /// @param spec Packed block specification.
+    /// @param n Number of blocks per group.
+    /// @return Specification with its stride replaced by `n`.
+    function group(uint spec, uint8 n) internal pure returns (uint) {
+        return replace8(spec, 128, n);
+    }
+}