@rootzero/contracts 1.14.0 → 1.16.0

package/codec/Blocks.sol

@@ -35,10 +35,6 @@ library Blocks {
     error UnexpectedValue();
     /// @dev A scoped block run contained no blocks.
     error EmptyRun();
-    /// @dev A block run was scoped with a zero stride.
-    error ZeroStride();
-    /// @dev A block count is not divisible by its declared stride.
-    error BadRatio();
 
     // -------------------------------------------------------------------------
     // Calldata inspection and navigation
@@ -147,25 +143,16 @@ library Blocks {
         }
     }
 
-    /// @notice Scope a consecutive block run into equal-sized groups.
+    /// @notice Count a run that must consume the complete region.
+    /// @dev Reverts when any well-formed trailing block has a different key.
     /// @param abs Absolute start position.
     /// @param limit Absolute region boundary.
-    /// @param key Block key forming the run.
-    /// @param stride Number of blocks per group.
-    /// @return groups Number of complete groups in the run.
-    /// @return end Absolute position immediately after the run.
-    function scope(
-        uint abs,
-        uint limit,
-        bytes4 key,
-        uint stride
-    ) internal pure returns (uint groups, uint end) {
-        if (stride == 0) revert ZeroStride();
-        uint count;
-        (count, end) = run(abs, limit, key);
-        if (count == 0) revert EmptyRun();
-        if (count % stride != 0) revert BadRatio();
-        groups = count / stride;
+    /// @param key Required block key for the complete region.
+    /// @return total Number of matching blocks.
+    /// @return end Absolute position equal to `limit`.
+    function runExact(uint abs, uint limit, bytes4 key) internal pure returns (uint total, uint end) {
+        (total, end) = run(abs, limit, key);
+        if (end != limit) revert InvalidBlock();
     }
 
     // Generic block writes
@@ -460,6 +447,33 @@ library Blocks {
 
     // Four-word payloads
 
+    /// @notice Write a POSITION block at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B128` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity owed on the liability side.
+    function writePosition(
+        bytes memory dst,
+        uint i,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure {
+        uint spec = Specs.Position;
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, spec)
+            mstore(add(p, 0x08), asset)
+            mstore(add(p, 0x28), amount)
+            mstore(add(p, 0x48), liability)
+            mstore(add(p, 0x68), debt)
+        }
+    }
+
     /// @notice Write a TRANSACTION block at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B128` bytes first.
     /// @param dst Destination buffer.
@@ -754,20 +768,18 @@ library Blocks {
     /// block size and ensure the encoded payload length fits in uint32.
     /// @param dst Destination buffer.
     /// @param i Relative write position.
-    /// @param id Node identifier.
     /// @param namespace Label namespace.
     /// @param name Label text.
-    function writeLabel(bytes memory dst, uint i, uint id, bytes32 namespace, string memory name) internal pure {
-        uint len = 64 + Sizes.Header + bytes(name).length;
+    function writeLabel(bytes memory dst, uint i, bytes32 namespace, string memory name) internal pure {
+        uint len = 32 + Sizes.Header + bytes(name).length;
         uint key = uint32(Keys.Label);
         uint stringkey = uint32(Keys.String);
         assembly ("memory-safe") {
             let p := add(add(dst, 0x20), i)
             mstore(p, or(shl(224, key), shl(192, len)))
-            mstore(add(p, 0x08), id)
-            mstore(add(p, 0x28), namespace)
+            mstore(add(p, 0x08), namespace)
 
-            let q := add(p, 0x48)
+            let q := add(p, 0x28)
             let namelen := mload(name)
             mstore(q, or(shl(224, stringkey), shl(192, namelen)))
             mcopy(add(q, 0x08), add(name, 0x20), namelen)
@@ -1251,6 +1263,28 @@ library Blocks {
 
     // Four-word payloads
 
+    /// @notice Decode a low-level fixed-width POSITION block at `abs`.
+    /// @param abs Absolute block position.
+    /// @return asset Decoded asset-side identifier.
+    /// @return amount Decoded asset-side quantity.
+    /// @return liability Decoded liability-side identifier.
+    /// @return debt Decoded liability-side debt.
+    function unpackPosition(
+        uint abs
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint head;
+        assembly ("memory-safe") {
+            head := calldataload(abs)
+        }
+        if (head >> 192 != Specs.Position >> 192) revert InvalidBlock();
+        assembly ("memory-safe") {
+            asset := calldataload(add(abs, 0x08))
+            amount := calldataload(add(abs, 0x28))
+            liability := calldataload(add(abs, 0x48))
+            debt := calldataload(add(abs, 0x68))
+        }
+    }
+
     /// @notice Decode a low-level fixed-width TRANSACTION block at `abs`.
     /// @param abs Absolute block position.
     /// @return from Decoded debit account.
@@ -1345,6 +1379,23 @@ library Blocks {
 
     // One fixed word
 
+    /// @notice Decode one ANNOTATION block and its nested block stream.
+    /// @param abs Absolute block position.
+    /// @return entity Decoded entity identifier.
+    /// @return stream Decoded annotation block stream.
+    /// @return end Absolute position after the block.
+    function unpackAnnotation(
+        uint abs
+    ) internal pure returns (uint entity, bytes calldata stream, uint end) {
+        uint limit;
+        (abs, limit) = expect(abs, Specs.Annotation);
+        assembly ("memory-safe") {
+            entity := calldataload(abs)
+        }
+        (stream, end) = unpackBytes(abs + 32);
+        if (end != limit) revert InvalidBlock();
+    }
+
     /// @notice Decode one CONTEXT block and all nested byte blocks.
     /// @param abs Absolute block position.
     /// @return account Decoded account identifier.
@@ -1444,19 +1495,17 @@ library Blocks {
 
     /// @notice Decode one LABEL block and its nested name.
     /// @param abs Absolute block position.
-    /// @return id Decoded node identifier.
     /// @return namespace Decoded label namespace.
     /// @return name Decoded label text.
     /// @return end Absolute position after the block.
-    function unpackLabel(uint abs) internal pure returns (uint id, bytes32 namespace, string memory name, uint end) {
+    function unpackLabel(uint abs) internal pure returns (bytes32 namespace, string memory name, uint end) {
         uint limit;
         (abs, limit) = expect(abs, Specs.Label);
         assembly ("memory-safe") {
-            id := calldataload(abs)
-            namespace := calldataload(add(abs, 0x20))
+            namespace := calldataload(abs)
         }
         bytes calldata value;
-        (value, end) = unpackString(abs + 64);
+        (value, end) = unpackString(abs + 32);
         if (end != limit) revert InvalidBlock();
         name = string(value);
     }
@@ -1532,6 +1581,30 @@ library Blocks {
         return create(Keys.String, bytes(value));
     }
 
+    /// @notice Encode a LABEL block.
+    /// @param namespace Label namespace.
+    /// @param name Label text.
+    /// @return Encoded LABEL block bytes.
+    function label(bytes32 namespace, string memory name) internal pure returns (bytes memory) {
+        return create(Keys.Label, bytes.concat(namespace, text(name)));
+    }
+
+    /// @notice Encode an ACTION annotation block.
+    /// @param value Canonical semantic action identifier.
+    /// @return Encoded ACTION block bytes.
+    function action(uint value) internal pure returns (bytes memory) {
+        return create(Keys.Action, bytes.concat(bytes32(value)));
+    }
+
+    /// @notice Encode a SCHEMA block.
+    /// @param spec Block specification.
+    /// @param body Schema body.
+    /// @param name Schema name.
+    /// @return Encoded SCHEMA block bytes.
+    function schema(uint spec, string memory body, bytes32 name) internal pure returns (bytes memory) {
+        return create(Keys.Schema, bytes.concat(bytes32(spec), text(body), name));
+    }
+
     /// @notice Encode a BALANCE block.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
@@ -1540,6 +1613,28 @@ library Blocks {
         return bytes.concat(Keys.Balance, bytes4(uint32(64)), asset, bytes32(amount));
     }
 
+    /// @notice Encode a POSITION block.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity owed on the liability side.
+    /// @return Encoded POSITION block bytes.
+    function position(
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure returns (bytes memory) {
+        return bytes.concat(
+            Keys.Position,
+            bytes4(uint32(128)),
+            asset,
+            bytes32(amount),
+            liability,
+            bytes32(debt)
+        );
+    }
+
     /// @notice Encode a CUSTODY block.
     /// @param host Host node ID holding the custody.
     /// @param asset Asset identifier.

package/codec/Buffers.sol

@@ -18,12 +18,12 @@ library Buffers {
 
     /// @notice Create a packed buffer cursor at write position zero.
     /// @param len Initial logical byte capacity.
-    /// @param groups Number of logical groups represented by the buffer.
+    /// @param count Number of logical items represented by the buffer.
     /// @param growable Whether writes may expand the logical capacity.
     /// @param tag Cursor identity tag.
     /// @return cur Packed buffer cursor.
-    function cursor(uint len, uint groups, bool growable, uint8 tag) internal pure returns (uint cur) {
-        cur = Cursors.create(0, len, groups, growable ? Growable : 0, tag);
+    function cursor(uint len, uint count, bool growable, uint8 tag) internal pure returns (uint cur) {
+        cur = Cursors.create(0, len, count, growable ? Growable : 0, tag);
     }
 
     /// @notice Reserve relative write space and return the updated packed buffer cursor.

package/codec/Decoders.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "./Blocks.sol";
 import {Sizes, Specs} from "./Specs.sol";
 import {Cursors, Cur} from "../utils/Cursors.sol";
@@ -32,20 +32,17 @@ library Decoders {
         cur.state = Cursors.wrap(source[i:], 0, 0);
     }
 
-    /// @notice Open the first homogeneous run in `source` using `stride`.
+    /// @notice Open the first homogeneous run in `source`.
     /// @param source Calldata block stream to open.
-    /// @param stride Number of blocks per group, or zero for an ungrouped stream.
     /// @return cur Cursor spanning the first homogeneous run.
-    function open(
-        bytes calldata source,
-        uint stride
-    ) internal pure returns (Cur memory cur) {
+    function open(bytes calldata source) internal pure returns (Cur memory cur) {
         (uint abs, uint limit) = Cursors.bounds(source);
-        if (stride == 0 && abs == limit) return cur;
+        if (abs == limit) revert Blocks.EmptyRun();
 
         bytes4 key = bytes4(source);
-        (uint groups, uint end) = Blocks.scope(abs, limit, key, stride);
-        cur.state = Cursors.create(abs, end - abs, groups, 0, 0);
+        (uint count, uint end) = Blocks.run(abs, limit, key);
+        if (count == 0) revert Blocks.EmptyRun();
+        cur.state = Cursors.create(abs, end - abs, count, 0, 0);
     }
 
     /// @notice Return whether `cur` has unread bytes.
@@ -163,6 +160,16 @@ library Decoders {
         return Blocks.find(offset + i, offset + end, key) - offset;
     }
 
+    /// @notice Count consecutive blocks with `key` from the current cursor position.
+    /// @dev Does not advance the cursor.
+    /// @param cur Cursor to inspect.
+    /// @param key Block key forming the run.
+    /// @return count Number of consecutive matching blocks.
+    function run(Cur memory cur, bytes4 key) internal pure returns (uint count) {
+        (uint i, uint offset, uint len) = cur.state.decode();
+        (count, ) = Blocks.run(offset + i, offset + len, key);
+    }
+
     /// @notice Consume one LIST block and return a cursor over its items.
     /// @param cur Cursor advanced past the list.
     /// @return items Cursor spanning the list payload.
@@ -365,6 +372,19 @@ library Decoders {
         cur.state = cur.state.seekAbs(end);
     }
 
+    /// @notice Decode and consume one ANNOTATION block.
+    /// @param cur Cursor advanced past the block.
+    /// @return entity Decoded entity identifier.
+    /// @return data Decoded annotation block stream.
+    function unpackAnnotation(
+        Cur memory cur
+    ) internal pure returns (uint entity, bytes calldata data) {
+        uint abs = cur.state.absolute();
+        uint end;
+        (entity, data, end) = Blocks.unpackAnnotation(abs);
+        cur.state = cur.state.seekAbs(end);
+    }
+
     /// @notice Decode and consume one CONTEXT block.
     /// @param cur Cursor advanced past the block.
     /// @return account Decoded account identifier.
@@ -395,13 +415,12 @@ library Decoders {
 
     /// @notice Decode and consume one LABEL block.
     /// @param cur Cursor advanced past the block.
-    /// @return id Decoded node identifier.
     /// @return namespace Decoded label namespace.
     /// @return name Decoded label text.
-    function unpackLabel(Cur memory cur) internal pure returns (uint id, bytes32 namespace, string memory name) {
+    function unpackLabel(Cur memory cur) internal pure returns (bytes32 namespace, string memory name) {
         uint abs = cur.state.absolute();
         uint end;
-        (id, namespace, name, end) = Blocks.unpackLabel(abs);
+        (namespace, name, end) = Blocks.unpackLabel(abs);
         cur.state = cur.state.seekAbs(end);
     }
 
@@ -520,6 +539,20 @@ library Decoders {
         (value.host, value.asset, value.amount) = unpackCustody(cur);
     }
 
+    /// @notice Decode and consume one POSITION block.
+    function unpackPosition(
+        Cur memory cur
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Position);
+        (asset, amount, liability, debt) = Blocks.unpackPosition(abs);
+    }
+
+    /// @notice Decode one POSITION block into its structured value.
+    function unpackPositionValue(Cur memory cur) internal pure returns (Position memory value) {
+        (value.asset, value.amount, value.liability, value.debt) = unpackPosition(cur);
+    }
+
     /// @notice Decode one TRANSACTION block into its structured value.
     /// @param cur Cursor advanced past the block.
     /// @return value Structured transaction.

package/codec/Descriptors.sol

@@ -37,7 +37,6 @@ library Descriptors {
         state = Specs.normalize(state, true);
         input = Specs.normalize(input, false);
         output = Specs.normalize(output, true);
-
         descriptor = pack(state, input, output, transactions, flags);
     }
 

package/codec/Keys.sol

@@ -5,12 +5,10 @@ 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);
-    /// @dev Wildcard key used in discovery when any block stream is accepted.
-    bytes4 constant Any = 0xffffffff;
     /// @dev Input amount - (bytes32 asset, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
@@ -21,6 +19,8 @@ library Keys {
     bytes4 constant Allowance = bytes4(keccak256("#allowance"));
     /// @dev Cross-host custody state - (uint host, bytes32 asset, uint amount)
     bytes4 constant Custody = bytes4(keccak256("#custody"));
+    /// @dev Asset-liability position state - (bytes32 asset, uint amount, bytes32 liability, uint debt)
+    bytes4 constant Position = bytes4(keccak256("#position"));
     /// @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
@@ -49,8 +49,12 @@ library Keys {
     bytes4 constant Asset = bytes4(keccak256("#asset"));
     /// @dev Node identifier - (uint id)
     bytes4 constant Node = bytes4(keccak256("#node"));
-    /// @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"));
 

package/codec/Readers.sol

@@ -94,6 +94,19 @@ library Readers {
         }
     }
 
+    /// @notice Consume a POSITION block and return its fields.
+    function unpackPosition(
+        Reader memory cur
+    ) internal pure returns (bytes32 asset, uint amount, bytes32 liability, uint debt) {
+        uint abs = consume(cur, Keys.Position, 128, 128);
+        assembly ("memory-safe") {
+            asset := mload(abs)
+            amount := mload(add(abs, 0x20))
+            liability := mload(add(abs, 0x40))
+            debt := mload(add(abs, 0x60))
+        }
+    }
+
     /// @notice Consume a TRANSACTION block and return its fields.
     /// @param cur Reader; advanced past the block.
     /// @return from Source account identifier.

package/codec/Schema.sol

@@ -36,17 +36,20 @@ 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, spec, 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 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
+// - `balance(...)`, `custody(...)`, and `position(...)` are live, linear state in the active command pipeline
 // - pipeline state belongs to the active account while the pipeline is executing
 // - while a balance or custody is in-flight as pipeline state, it is not simultaneously persisted
 //   in another ledger/store by this protocol
+// - a position pairs live asset and liability sides; commands may transform either side
+// - position state is transient and does not itself create or erase an externally persisted obligation
+// - positions support backward composition, but pipeline steps always execute in encoded order
 // - commands must preserve, transform, settle, or intentionally consume pipeline state
 // - input blocks such as `amount(...)`, `allocation(...)`, and `allowance(...)`
 //   express intent, constraints, or references
@@ -90,6 +93,7 @@ library Schemas {
 
     // Four-word payloads
 
+    string constant Position = "{ bytes32 asset, uint amount, bytes32 liability, uint debt }";
     string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
     string constant HostAccountAmount = "{ uint host, bytes32 account, bytes32 asset, uint amount }";
 
@@ -101,7 +105,12 @@ library Schemas {
     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 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 }";
 }
 

package/codec/Specs.sol

@@ -31,6 +31,8 @@ library Sizes {
     uint constant HostAmount = B96;
     /// @dev TRANSACTION block: 8 header + 32 from + 32 to + 32 asset + 32 amount = 136 bytes
     uint constant Transaction = B128;
+    /// @dev POSITION block: 8 header + four-word asset-liability pair = 136 bytes
+    uint constant Position = B128;
 }
 
 /// @title Specs
@@ -44,7 +46,6 @@ library Specs {
     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
@@ -54,17 +55,18 @@ library Specs {
     uint private constant Exact96 = 96 * SizeFields;
     uint private constant Exact128 = 128 * SizeFields;
     uint private constant UnboundedHint128 = uint(128) << 136;
+    uint private constant UnboundedMin40Hint256 = (uint(40) << 192) | (uint(256) << 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 Position = uint(bytes32(Keys.Position)) | Exact128;
     uint constant List = uint(bytes32(Keys.List)) | UnboundedHint128;
     uint constant Evm = uint(bytes32(Keys.Evm)) | UnboundedHint128;
     uint constant Bytes = uint(bytes32(Keys.Bytes)) | UnboundedHint128;
@@ -79,7 +81,9 @@ library Specs {
     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 Label = uint(bytes32(Keys.Label)) | UnboundedMin40Hint256;
+    uint constant Annotation = uint(bytes32(Keys.Annotation)) | UnboundedMin40Hint256;
+    uint constant Action = uint(bytes32(Keys.Action)) | Exact32;
     uint constant Schema = uint(bytes32(Keys.Schema)) | UnboundedMin72Hint256;
 
     uint constant Status = uint(bytes32(Keys.Status)) | Exact32;
@@ -96,12 +100,31 @@ library Specs {
     /// @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;
+        return create(uint32(blockkey), min, max, hint);
+    }
+
+    /// @notice Construct a block specification from its numeric key and encoded fields.
+    /// @param blockkey Numeric 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(uint32 blockkey, uint32 min, uint32 max, uint32 hint) internal pure returns (uint spec) {
+        spec |= uint(blockkey) << 224;
         spec |= uint(min) << 192;
         spec |= uint(max) << 160;
         spec |= uint(max24(hint)) << 136;
     }
 
+    /// @notice Construct an exact-size block specification from a numeric key.
+    /// @dev Sets the minimum, maximum, and allocation hint to `size`.
+    /// @param blockkey Numeric block key.
+    /// @param size Exact payload length and initial per-block payload capacity.
+    /// @return spec Packed exact-size block specification.
+    function create(uint32 blockkey, uint32 size) internal pure returns (uint spec) {
+        return create(blockkey, size, size, size);
+    }
+
     /// @notice Decode the block key and accepted payload range from `spec`.
     /// @param spec Packed block specification.
     /// @return blockkey Encoded block key.
@@ -215,4 +238,5 @@ library Specs {
     function group(uint spec, uint8 n) internal pure returns (uint) {
         return replace8(spec, 128, n);
     }
+
 }

package/codec/Writers.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AssetAmount, AccountAmount, HostAmount, Tx} from "../core/Types.sol";
+import {AssetAmount, AccountAmount, HostAmount, Position, Tx} from "../core/Types.sol";
 import {Blocks} from "./Blocks.sol";
 import {Buffers} from "./Buffers.sol";
 import {Sizes, Specs} from "./Specs.sol";
@@ -44,7 +44,7 @@ library Writers {
         (uint capacity, bool growable) = Specs.allocation(spec, groups);
         if (capacity == 0) return writer;
 
-        writer.cur = Buffers.cursor(capacity, groups, growable, 0);
+        writer.cur = Buffers.cursor(capacity, Specs.count(spec, groups), growable, 0);
     }
 
     // -------------------------------------------------------------------------
@@ -291,6 +291,23 @@ library Writers {
         Blocks.writeHostAccountAsset(writer.dst, i, host, account, asset);
     }
 
+    /// @notice Append a POSITION block.
+    function appendPosition(
+        Writer memory writer,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal pure {
+        uint i = reserve(writer, Sizes.Position);
+        Blocks.writePosition(writer.dst, i, asset, amount, liability, debt);
+    }
+
+    /// @notice Append a structured POSITION value.
+    function appendPosition(Writer memory writer, Position memory value) internal pure {
+        appendPosition(writer, value.asset, value.amount, value.liability, value.debt);
+    }
+
     /// @notice Append a TRANSACTION block.
     /// @param writer Destination writer.
     /// @param from Debit account identifier.
@@ -448,18 +465,16 @@ library Writers {
 
     /// @notice Append a LABEL block.
     /// @param writer Destination writer.
-    /// @param id Node identifier to encode.
     /// @param namespace Label namespace to encode.
     /// @param name Label text to encode.
     function appendLabel(
         Writer memory writer,
-        uint id,
         bytes32 namespace,
         string memory name
     ) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + bytes(name).length;
+        uint size = Sizes.B32 + Sizes.Header + bytes(name).length;
         uint i = reserve(writer, size);
-        Blocks.writeLabel(writer.dst, i, id, namespace, name);
+        Blocks.writeLabel(writer.dst, i, namespace, name);
     }
 
     /// @notice Append a SCHEMA block.