@rootzero/contracts 0.9.1 → 0.9.3

package/Commands.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports command, control, and remote abstractions.
+// Aggregator: re-exports command, admin, and peer abstractions.
 // Import this file to inherit from the full rootzero command surface without managing individual paths.
 
-import { CommandBase, CommandContext, CommandPayable, encodeCommandCall } from "./commands/Base.sol";
+import { CommandBase, CommandContext, CommandPayable } from "./commands/Base.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Burn, BurnHook } from "./commands/Burn.sol";
 import { CreditAccount, CreditAccountHook } from "./commands/Credit.sol";
@@ -14,20 +14,20 @@ import { PipePayable, PipePayableHook } from "./commands/Pipe.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
 import { Transfer, TransferHook } from "./commands/Transfer.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
-import { AllowAssets, AllowAssetsHook } from "./commands/control/AllowAssets.sol";
-import { Destroy, DestroyHook } from "./commands/control/Destroy.sol";
-import { ExecutePayable } from "./commands/control/Execute.sol";
-import { Authorize } from "./commands/control/Authorize.sol";
-import { DenyAssets, DenyAssetsHook } from "./commands/control/DenyAssets.sol";
-import { Init, InitHook } from "./commands/control/Init.sol";
-import { Allowance, AllowanceHook } from "./commands/control/Allowance.sol";
-import { Unauthorize } from "./commands/control/Unauthorize.sol";
-import { RemoteBase, encodeRemoteCall } from "./remote/Base.sol";
-import { RemoteAllowance } from "./remote/Allowance.sol";
-import { RemoteAssetPull, AssetPullHook } from "./remote/AssetPull.sol";
-import { RemoteAllowAssets } from "./remote/AllowAssets.sol";
-import { RemoteDenyAssets } from "./remote/DenyAssets.sol";
-import { RemoteSettle } from "./remote/Settle.sol";
+import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
+import { Destroy, DestroyHook } from "./commands/admin/Destroy.sol";
+import { ExecutePayable } from "./commands/admin/Execute.sol";
+import { Authorize } from "./commands/admin/Authorize.sol";
+import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
+import { Init, InitHook } from "./commands/admin/Init.sol";
+import { Allowance, AllowanceHook } from "./commands/admin/Allowance.sol";
+import { Unauthorize } from "./commands/admin/Unauthorize.sol";
+import { PeerBase, encodePeerCall } from "./peer/Base.sol";
+import { PeerAllowance } from "./peer/Allowance.sol";
+import { PeerBalancePull, BalancePullHook } from "./peer/BalancePull.sol";
+import { PeerAllowAssets } from "./peer/AllowAssets.sol";
+import { PeerDenyAssets } from "./peer/DenyAssets.sol";
+import { PeerSettle } from "./peer/Settle.sol";
 
 
 

package/Cursors.sol

@@ -9,7 +9,7 @@ import { Forms, Sizes } from "./blocks/Schema.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Schemas } from "./blocks/Schema.sol";
 import { Cursors, Cur } from "./blocks/Cursors.sol";
-import { ALLOC_SCALE, Writer, Writers } from "./blocks/Writers.sol";
+import { Writer, Writers } from "./blocks/Writers.sol";
 
 
 

package/Events.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to get access to every event emitter in one import.
 
 import { AccessEvent } from "./events/Access.sol";
-import { ControlEvent } from "./events/Control.sol";
+import { AdminEvent } from "./events/Admin.sol";
 import { AssetEvent } from "./events/Asset.sol";
 import { BalanceEvent } from "./events/Balance.sol";
 import { CollateralEvent } from "./events/Collateral.sol";
@@ -17,9 +17,9 @@ import { EventEmitter } from "./events/Emitter.sol";
 import { GovernedEvent } from "./events/Governed.sol";
 import { HostAnnouncedEvent } from "./events/Host.sol";
 import { ListingEvent } from "./events/Listing.sol";
-import { RemoteEvent } from "./events/Remote.sol";
+import { PeerEvent } from "./events/Peer.sol";
 import { QueryEvent } from "./events/Query.sol";
-import { RootZeroEvent } from "./events/RootZero.sol";
+import { PipedEvent } from "./events/Piped.sol";
 import { SwapEvent } from "./events/Swap.sol";
 import { WithdrawalEvent } from "./events/Withdraw.sol";
 

package/Utils.sol

@@ -11,7 +11,7 @@ import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids, Selectors } from "./utils/Ids.sol";
 import { Layout } from "./utils/Layout.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, isLocal, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, isLocalChain, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
 import { Budget, Values } from "./utils/Value.sol";
 
 

package/blocks/Cursors.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.33;
 import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, Tx} from "../core/Types.sol";
 import {Sizes} from "./Schema.sol";
 import {Keys} from "./Keys.sol";
-import {ALLOC_SCALE, Writer, Writers} from "./Writers.sol";
+import {Writer, Writers} from "./Writers.sol";
 
 /// @notice Zero-copy view into a calldata block stream.
 /// All positions (`i`, `bound`) are byte offsets relative to the start of the source region.
@@ -45,7 +45,7 @@ library Cursors {
     error ZeroNode();
     /// @dev A field value did not match the expected value.
     error UnexpectedValue();
-    /// @dev Input and output block counts are not proportional to their declared group sizes.
+    /// @dev Prime block counts are not divisible by, or do not match, their declared group sizes.
     error BadRatio();
     // -------------------------------------------------------------------------
     // Cursor construction and navigation
@@ -87,6 +87,25 @@ library Cursors {
         out.len = to - from;
     }
 
+    /// @notice Return the full cursor region as a calldata slice.
+    /// Does not advance the cursor; `cur.i` and `cur.bound` are ignored.
+    /// @param cur Cursor whose backing region should be returned.
+    /// @return data Calldata view over `[cur.offset, cur.offset + cur.len)`.
+    function raw(Cur memory cur) internal pure returns (bytes calldata data) {
+        if (cur.len > msg.data.length || cur.offset > msg.data.length - cur.len) revert MalformedBlocks();
+        data = msg.data[cur.offset:cur.offset + cur.len];
+    }
+
+    /// @notice Return a sub-range of the cursor region as a calldata slice.
+    /// Does not advance the cursor; `cur.i` and `cur.bound` are ignored.
+    /// @param cur Source cursor.
+    /// @param from Start byte offset within the source region (inclusive).
+    /// @param to End byte offset within the source region (exclusive).
+    /// @return data Calldata view over the requested sub-range.
+    function raw(Cur memory cur, uint from, uint to) internal pure returns (bytes calldata data) {
+        data = cur.slice(from, to).raw();
+    }
+
     /// @notice Read a block header at position `i` without advancing the cursor.
     /// @param cur Source cursor.
     /// @param i Byte offset of the block header within the source region.
@@ -109,17 +128,30 @@ library Cursors {
         return cur.i + Sizes.Header + len;
     }
 
-    /// @notice Return true if the current cursor position contains a block header with the given key.
+    /// @notice Return true if the current cursor position is at a block header with the given key.
     /// Returns false when `cur.i` is out of bounds or the key differs.
     /// @param cur Source cursor.
     /// @param key Expected block type identifier.
     /// @return Whether the block header at `cur.i` uses `key`.
-    function has(Cur memory cur, bytes4 key) internal pure returns (bool) {
+    function isAt(Cur memory cur, bytes4 key) internal pure returns (bool) {
         if (cur.i + 8 > cur.len) return false;
         uint abs = cur.offset + cur.i;
         return bytes4(msg.data[abs:abs + 4]) == key;
     }
 
+    /// @notice Return whether the remaining cursor region is empty or exactly one block with `key`.
+    /// Returns false for an empty remaining region. Reverts if the next block has another key or
+    /// if a matching block is followed by trailing bytes.
+    /// @param cur Source cursor.
+    /// @param key Expected optional block key.
+    /// @return Whether the remaining region contains exactly one block with `key`.
+    function maybeOnly(Cur memory cur, bytes4 key) internal pure returns (bool) {
+        if (cur.i == cur.len) return false;
+        if (!cur.isAt(key)) revert InvalidBlock();
+        if (cur.past() != cur.len) revert IncompleteCursor();
+        return true;
+    }
+
     /// @notice Validate a block at position `i` and return its payload location.
     /// Does not advance the cursor.
     /// @param cur Source cursor.
@@ -249,23 +281,33 @@ library Cursors {
         cur.i = next;
     }
 
+    /// @notice Consume an optional block with the given key and return a cursor over the full block slice.
+    /// If the current block key does not match, returns an empty cursor and leaves `cur.i` unchanged.
+    /// Otherwise behaves like `take(cur, key)`.
+    /// @param cur Cursor positioned at an optional block.
+    /// @param key Optional block type key.
+    /// @return out Cursor scoped to the full matching block, or empty when no matching block is present.
+    function maybeTake(Cur memory cur, bytes4 key) internal pure returns (Cur memory out) {
+        return cur.isAt(key) ? take(cur, key) : cur.slice(cur.i, cur.i);
+    }
+
     /// @notice Consume an optional ROUTE block at the current position and return a cursor over the full block slice.
     /// If the current block is not ROUTE, returns an empty cursor and leaves `cur.i` unchanged.
     /// Otherwise behaves like `take(cur, Keys.Route)`.
     /// @param cur Cursor positioned at an optional ROUTE block.
     /// @return out Cursor scoped to the full ROUTE block, or empty when no ROUTE block is present.
     function maybeRoute(Cur memory cur) internal pure returns (Cur memory out) {
-        return cur.has(Keys.Route) ? take(cur, Keys.Route) : cur.slice(cur.i, cur.i);
+        return maybeTake(cur, Keys.Route);
     }
 
-    /// @notice Enter a List block, prime its member run, and return the raw block count.
+    /// @notice Enter a List block, prime its member run, and return the group count.
     /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
     /// @param group Expected block group size for the list item stream.
-    /// @return count Total number of blocks in the list payload (a multiple of `group`).
+    /// @return groups Number of block groups in the list payload.
     /// @return next Byte offset immediately after the list payload.
-    function list(Cur memory cur, uint group) internal pure returns (uint count, uint next) {
+    function list(Cur memory cur, uint group) internal pure returns (uint groups, uint next) {
         next = list(cur);
-        (, count, ) = cur.primeRun(group);
+        (, , groups) = cur.primeRun(group);
         if (cur.bound != next) revert IncompleteCursor();
     }
 

package/blocks/Keys.sol

@@ -34,7 +34,7 @@ library Keys {
     bytes4 constant Bundle = bytes4(keccak256("bundle(bytes data)"));
     /// @dev List wrapper - (bytes data); payload is an embedded repeated block stream
     bytes4 constant List = bytes4(keccak256("list(bytes data)"));
-    /// @dev Frame wrapper - (bytes data); payload is schema-defined concatenated member payloads
+    /// @dev Frame wrapper - (bytes data); payload is schema-defined fields, optionally followed by block-stream items
     bytes4 constant Frame = bytes4(keccak256("frame(bytes data)"));
     /// @dev Extensible routing field - (bytes data); layout is command-defined
     bytes4 constant Route = bytes4(keccak256("route(bytes data)"));

package/blocks/Schema.sol

@@ -16,24 +16,73 @@ pragma solidity ^0.8.33;
 //   and can be decoded with `abi.decode`
 // - chain-specific payload blocks are request-only escape hatches and should never be used for pipeline state
 // - prefer ordinary protocol blocks whenever possible; chain-specific payload blocks should be a last resort
+// - prefer frames for typed custom payloads; reserved extensible blocks such as `route(...)` and `item(...)`
+//   should be used only when a stable protocol-level key or opaque escape hatch is needed
 //
 // Schema DSL:
-// - `;` separates top-level sibling blocks
+// - `;` separates top-level items
+// - command, peer, and query schemas have the top-level form `prime`, `prime; global; global`,
+//   `empty; global; global`, or `""` for no request items at all
+// - the first top-level item is the prime item unless it is the schema-only `empty` sentinel
+// - the prime item must have one runtime key; helpers consume the consecutive run of blocks with
+//   that key as the per-operation batch, and `Command.shape` is defined over those prime runs
+// - `empty` emits no block, has no runtime key, and must only appear as the first top-level item
+//   before global blocks; it means the schema has no prime item
+// - top-level items after the prime item or `empty` are global batch support blocks: they apply to
+//   the whole batch, may be searched or consumed separately by the command, and are not counted as
+//   per-operation prime blocks
 // - `&` bundles adjacent blocks into one bundle block
 // - `+` frames adjacent fixed-layout block payloads into one frame block
-// - `&` and `+` follow the same grouping and normalization rules, except they emit different wrapper blocks
+// - `+&` appends adjacent blocks to a frame as full block-stream items, preserving their headers
+// - leading `&` is shorthand for an anonymous bundle
+// - leading `+&` is shorthand for an anonymous frame with only a block-stream tail
+// - `&`, `+`, and `+&` follow the same grouping and normalization rules, except they emit different payload forms
 // - `name = a & b` introduces a named bundle item with a local key derived from the raw input string
 // - `name = a + b` introduces a named frame item with a local key derived from the raw input string
+// - `alias: item` attaches a presentation alias to the following schema item for off-chain APIs,
+//   docs, and UI labels
 // - `bundle = a & b` introduces an anonymous child bundle item
 // - `frame = a + b` introduces an anonymous child frame item, like `bundle = ...` and `list = ...`
+// - `(fields...)` in item position is shorthand for an anonymous frame with those fields
+// - `(fields...)` inside an existing frame introduces anonymous flattened frame fields without a nested frame key
 // - postfix `[]` marks a repeated list in the simple suffix form, e.g. `asset(...)[]`
+// - postfix `?` marks an optional item, e.g. `account(...)?`
 // - `name[] = a & b` introduces a named list with a local key derived from the raw input string
+// - `name? = a & b` introduces an optional named structural item
+// - `name[]? = a & b` introduces an optional named list; `?[]` is invalid
 // - `list = a & b` introduces an anonymous list whose repeated item is the bundled shape `a & b`
+// - `bundle? = a & b`, `frame? = a + b`, and `list? = a & b` introduce optional anonymous structural items
 // - empty entries are ignored, but structural markers are preserved after normalization
+// - aliases are presentation metadata: they do not add bytes, headers, fields, or wrappers,
+//   and they do not change the payload layout of the item they label
+// - aliases are not stripped before on-chain local-key derivation; when a named structural item is keyed by
+//   bytes4(keccak256(bytes(rawSchemaInput))), any alias text present in that raw string is part of identity
+// - off-chain presentation should use `alias:` when present, otherwise the schema item name when available
+// - if sibling presentation names collide, off-chain tools should append zero-based suffixes in encounter order,
+//   e.g. `amount(...) + amount(...)` presents as `amount0` and `amount1`
+// - when possible, off-chain tools should preserve item grouping for repeated schemas, e.g. `amount0.asset`,
+//   `amount0.meta`, `amount0.amount`, then `amount1.asset`, `amount1.meta`, `amount1.amount`
+// - if fields within one presentation group collide, off-chain tools should suffix those field names in
+//   encounter order, e.g. `(uint amount, uint amount)` presents as `amount0` and `amount1`
+// - optionality is schema metadata only; when an optional item is present, it uses the same encoding as the
+//   non-optional form, and when absent, no placeholder block is emitted
+// - optional children inside a present bundle, list item, or `+&` frame tail may be absent while the
+//   parent structural block is still emitted; for example `& account(...)?` and `+& account(...)?`
+//   can encode as an empty BUNDLE or empty FRAME when the account child is absent
+// - optional `?` is not allowed on flattened `+` frame members because frame fields have no child key or length;
+//   use `(fields...)?` as an optional frame item, make the whole frame optional, or use `+&` for
+//   optional block-stream tail items
 // - grouping parentheses are not part of the DSL; parentheses are only used in block field lists
+//   and anonymous frame field groups
+// - anonymous frame field groups in item position are promoted to anonymous frame items, so `(fields...)[]`
+//   means a list of anonymous frame items and `(fields...)?` means an optional anonymous frame item
+// - anonymous frame field groups inside an existing frame are flattened fields, not nested frame items, and
+//   cannot be appended with `+&`
 // - `+` binds tighter than `&`, so `a & b + c` normalizes as `a & (b + c)`
+// - `+&` binds like `+`, so `a & b +& c` normalizes as `a & (b +& c)`
 // - if `&` appears, the result remains a bundle even when only one non-empty child remains
 // - if `+` appears, the result remains a frame even when only one non-empty child remains
+// - if `+&` appears, the result remains a frame even when only one non-empty child remains
 // - after ignoring empty entries, repeated adjacent separators collapse while preserving bundle/frame/list shape
 // - bundled blocks preserve member order, so `a & b` differs from `b & a`
 // - a bundle block's self payload is an embedded normal block stream of its bundled members
@@ -42,14 +91,20 @@ pragma solidity ^0.8.33;
 // - a frame block's self payload is the concatenated payload fields of its framed members
 // - framed members do not keep their ordinary block headers; the emitted schema defines the frame layout
 // - framed members must be fixed-layout block forms because frame payloads contain no child lengths or block keys
+// - anonymous frame field groups must also be fixed-layout and contribute only their fields, in order
+// - `+&` members keep their ordinary block encoding inside the frame payload, so dynamic blocks are allowed there
+// - `+&` starts a block-stream tail inside the frame; fixed-layout `+` members may not follow it
 // - frames may be bundled like ordinary block items, but bundles/lists cannot be framed
-// - top-level blocks of the same type should be grouped together
-// - primary / driving blocks should appear before auxiliary blocks
+// - prime blocks of the same type should be grouped together so the prime run is contiguous
+// - primary / driving blocks should be the prime item; auxiliary batch-wide blocks should follow
+//   as global `;` siblings
 // - `route(<fields...>)`, `item(<fields...>)`, `evm(<fields...>)`, `query(<fields...>)`,
 //   and `response(<fields...>)` are reserved extensible schema forms whose keys are always
 //   `Keys.Route`, `Keys.Item`, `Keys.Evm`, `Keys.Query`, and `Keys.Response` respectively
 // - these extensible forms work like dynamic `bytes` blocks: they may carry arbitrary
 //   payload bytes while keeping one fixed key per semantic block type
+// - prefer `frame = ...`, `(fields...)`, and `+&` tails over `route(...)` and `item(...)` when the payload
+//   can be described by the schema DSL; frames give off-chain tools typed layouts and better generated APIs
 // - `evm(<fields...>)` differs from bundle/list payloads: its bytes are not an embedded block stream
 // - `evm(uint foo, uint bar)` is a schema declaration only; on-chain the block key is still `Keys.Evm`
 //   and the payload can be decoded from `bytes data` using the local runtime's native decoder
@@ -57,21 +112,59 @@ pragma solidity ^0.8.33;
 // - anonymous `&` compiles to a `Keys.Bundle` block whose self payload is the bundled member block stream
 // - anonymous `[]` compiles to a `Keys.List` block whose self payload is the repeated item block stream
 // - anonymous `+` compiles to a `Keys.Frame` block whose self payload is the framed member payload fields
+// - anonymous `+&` compiles to a `Keys.Frame` block whose self payload is fixed framed fields
+//   followed by an embedded normal block-stream tail
+// - bare `(fields...)` compiles to a `Keys.Frame` block whose self payload is those fields
 // - named lists, bundles, and frames use bytes4(keccak256(bytes(rawSchemaInput))) as their block key
 // - named structural keys are custom/local identifiers, not global protocol keys; formatting is part of identity
+// - `payment: frame = amount(...) +& fee(...)` means an anonymous frame whose runtime key is still `Keys.Frame`,
+//   with `payment` as its off-chain presentation name
+// - `quote: payment = amount(...) + fee(...)` means a named frame with presentation alias `quote`;
+//   its local runtime key is derived from the full raw schema string including `quote:`
+// - `frame = debit: amount(...) + credit: amount(...)` means the two flattened amount groups should be
+//   presented off-chain as `debit` and `credit`, while encoding remains the same as without aliases
+// - `frame = amount(...) + amount(...)` has the same encoding as the aliased form above, but off-chain tools
+//   should present the groups as `amount0` and `amount1`
 // - `asset(...)[]` means a list whose repeated item is the block `asset(...)`
+// - `account(...)?` means an optional account block
 // - `steps[] = asset(...) & account(...)` means a named list whose repeated item is the bundle
 //   `asset(...) & account(...)`
+// - `steps[]? = asset(...) & account(...)` means that named list may be absent
+// - `memo? = evm(bytes data)` means an optional named local item whose payload, when present, is EVM-encoded
 // - `payment = amount(...) + fee(...)` means a named frame whose payload is
 //   `asset | meta | amount | fee` and whose on-chain key is derived from that raw schema string
+// - `payment = amount(...) + (uint fee, uint rate)` means a named frame whose payload is
+//   `asset | meta | amount | fee | rate`, without inventing a child block name for the extra fields
+// - `payment = (uint fee, uint rate)` means a named frame whose payload is `fee | rate`
+// - `payment = amount(...) +& fee(...)` means a named frame whose payload is
+//   `asset | meta | amount | [fee key | fee len | fee amount]`
+// - `payment = amount(...) +& fee(...)?` means a named frame with an amount prefix and optional fee block tail
+// - `payment = amount(...) +& list? = fee(...)` means a named frame with an amount prefix and
+//   an optional anonymous list block tail
+// - `payment = amount(...)? + fee(...)` is invalid because `amount(...)` would be an optional flattened frame member
+// - `(uint fee)` means an anonymous frame with one `fee` field
+// - `(uint fee)[]` means a list of anonymous frames whose repeated item has one `fee` field
+// - `(uint fee)?` means an optional anonymous frame with one `fee` field
+// - `amount(...) & (uint fee)` means a bundle containing an amount block and an anonymous fee frame
+// - `amount(...) +& (uint fee)` is invalid because `+&` appends existing block-stream items, not field groups
 // - `amount(...) & fee(...) + account(...)` means `amount(...) & (fee(...) + account(...))`;
 //   it compiles to a bundle containing one amount block followed by one frame block
+// - `amount(...) & fee(...) +& account(...)` means `amount(...) & (fee(...) +& account(...))`;
+//   it compiles to a bundle containing one amount block followed by one frame block with an account block tail
 // - `bundle = account(...) & evm(bytes routeData)` means an anonymous child bundle with those bundled members
+// - `bundle? = account(...) & auth(...)` means that anonymous bundle may be absent
 // - `frame = amount(...) + fee(...)` means an anonymous child frame with those framed payload fields
+// - `frame? = amount(...) + fee(...)` means that anonymous frame may be absent
+// - `frame = amount(...) +& fee(...)` means an anonymous child frame with amount fields plus a fee block tail
 // - `list = asset(...) & account(...)` means an anonymous child list whose repeated item is the
 //   bundle `asset(...) & account(...)`
+// - `list? = fee(...)` means that anonymous list may be absent
 // - `"amount(...) &"` and `"& amount(...)"` both normalize to a bundle containing one `amount(...)` child
+// - `"& account(...)?"` normalizes to a bundle containing one optional `account(...)` child
 // - `"amount(...) +"` and `"+ amount(...)"` both normalize to a frame containing one `amount(...)` payload
+// - `"amount(...) +&"` and `"+& amount(...)"` both normalize to a frame containing one `amount(...)` block
+// - `"+& account(...)?"` normalizes to a frame containing an optional `account(...)` block-stream tail
+// - `"amount(...)?"` normalizes to an optional amount block; `"amount(...)?[]"` is invalid
 // - canonical blocks are `amount(...)` for request amounts, `balance(...)` for state balances,
 //   `allocation(...)` for host-scoped provision requests, `allowance(...)` for host-scoped caps,
 //   `custody(...)` for host-scoped state,
@@ -102,6 +195,7 @@ pragma solidity ^0.8.33;
 /// These strings are the canonical source from which `Keys` constants are derived
 /// and are used when emitting schema descriptors in command events.
 library Schemas {
+    string constant Empty = "empty";
     string constant Node = "node(uint id)";
     string constant Account = "account(bytes32 account)";
     string constant Asset = "asset(bytes32 asset, bytes32 meta)";

package/blocks/Writers.sol

@@ -17,11 +17,6 @@ struct Writer {
     bytes dst;
 }
 
-// Fixed-point scaling denominator for output-count allocation.
-// A `scaledRatio` of `ALLOC_SCALE` means 1:1 (one output block per input block).
-// `2 * ALLOC_SCALE` means 2:1; non-integer ratios revert with `BadWriterRatio`.
-uint constant ALLOC_SCALE = 10_000;
-
 /// @title Writers
 /// @notice Response block stream builder for the rootzero protocol.
 /// Allocates a fixed-size memory buffer up front and writes binary-encoded
@@ -36,8 +31,6 @@ library Writers {
     error IncompleteWriter();
     /// @dev An alloc function received a zero count, or `finish` found no bytes written.
     error EmptyRequest();
-    /// @dev `scaledRatio * count` is not evenly divisible by `ALLOC_SCALE`.
-    error BadWriterRatio();
     /// @dev A fixed-width low-level writer received an invalid final-word keep length.
     error InvalidKeep();
 
@@ -58,21 +51,13 @@ library Writers {
     }
 
     /// @notice Core allocation routine used by all counted `alloc*` helpers.
-    /// Computes `(count * scaledRatio / ALLOC_SCALE) * blockLen` and allocates that many bytes.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output-to-input ratio in `ALLOC_SCALE` units.
+    /// Computes `count * blockLen` and allocates that many bytes.
+    /// @param count Number of output blocks.
     /// @param blockLen Logical byte size of each output block (including 8-byte header).
     /// @return writer Allocated writer.
-    function allocFromScaledCount(
-        uint count,
-        uint scaledRatio,
-        uint blockLen
-    ) internal pure returns (Writer memory writer) {
+    function allocFromCount(uint count, uint blockLen) internal pure returns (Writer memory writer) {
         if (count == 0) revert EmptyRequest();
-        uint scaledCount = count * scaledRatio;
-        if (scaledCount % ALLOC_SCALE != 0) revert BadWriterRatio();
-        uint len = (scaledCount / ALLOC_SCALE) * blockLen;
-        writer = alloc(len);
+        writer = alloc(count * blockLen);
     }
 
     /// @notice Allocate a writer sized for exactly `count` dynamic blocks with a shared payload length.
@@ -81,96 +66,42 @@ library Writers {
     /// @param payloadLen Payload byte length for each block.
     /// @return writer Allocated writer.
     function allocBytes(uint count, uint payloadLen) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.Header + payloadLen);
+        return allocFromCount(count, Sizes.Header + payloadLen);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` 32-byte-payload blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` 32-byte-payload blocks.
     /// @param count Number of blocks to allocate space for.
     /// @return writer Allocated writer.
     function alloc32s(uint count) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.B32);
+        return allocFromCount(count, Sizes.B32);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` 64-byte-payload blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` 64-byte-payload blocks.
     /// @param count Number of blocks to allocate space for.
     /// @return writer Allocated writer.
     function alloc64s(uint count) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.B64);
+        return allocFromCount(count, Sizes.B64);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` 96-byte-payload blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` 96-byte-payload blocks.
     /// @param count Number of blocks to allocate space for.
     /// @return writer Allocated writer.
     function alloc96s(uint count) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.B96);
+        return allocFromCount(count, Sizes.B96);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` 128-byte-payload blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` 128-byte-payload blocks.
     /// @param count Number of blocks to allocate space for.
     /// @return writer Allocated writer.
     function alloc128s(uint count) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.B128);
+        return allocFromCount(count, Sizes.B128);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` 160-byte-payload blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` 160-byte-payload blocks.
     /// @param count Number of blocks to allocate space for.
     /// @return writer Allocated writer.
     function alloc160s(uint count) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.B160);
-    }
-
-    /// @notice Allocate a writer for dynamic blocks with a shared payload length and custom output ratio.
-    /// Each block reserves `Sizes.Header + payloadLen` bytes.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @param payloadLen Payload byte length for each block.
-    /// @return writer Allocated writer.
-    function allocScaledBytes(
-        uint count,
-        uint scaledRatio,
-        uint payloadLen
-    ) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.Header + payloadLen);
-    }
-
-    /// @notice Allocate a writer for 32-byte-payload blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaled32s(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.B32);
-    }
-
-    /// @notice Allocate a writer for 64-byte-payload blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaled64s(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.B64);
-    }
-
-    /// @notice Allocate a writer for 96-byte-payload blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaled96s(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.B96);
-    }
-
-    /// @notice Allocate a writer for 128-byte-payload blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaled128s(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.B128);
-    }
-
-    /// @notice Allocate a writer for 160-byte-payload blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaled160s(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocFromScaledCount(count, scaledRatio, Sizes.B160);
+        return allocFromCount(count, Sizes.B160);
     }
 
     /// @notice Allocate a writer sized for exactly `count` STATUS form blocks.
@@ -180,83 +111,48 @@ library Writers {
         return alloc32s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` ASSET blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` ASSET blocks.
     /// @param count Number of asset blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocAssets(uint count) internal pure returns (Writer memory writer) {
         return alloc64s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` AMOUNT blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` AMOUNT blocks.
     /// @param count Number of amount blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocAmounts(uint count) internal pure returns (Writer memory writer) {
         return alloc96s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` BALANCE blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` BALANCE blocks.
     /// @param count Number of balance blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocBalances(uint count) internal pure returns (Writer memory writer) {
         return alloc96s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` ACCOUNT_AMOUNT form blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` ACCOUNT_AMOUNT form blocks.
     /// @param count Number of account amount blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocAccountAmounts(uint count) internal pure returns (Writer memory writer) {
         return alloc128s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` CUSTODY blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` CUSTODY blocks.
     /// @param count Number of custody blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocCustodies(uint count) internal pure returns (Writer memory writer) {
         return alloc128s(count);
     }
 
-    /// @notice Allocate a writer sized for exactly `count` TRANSACTION blocks (1:1 ratio).
+    /// @notice Allocate a writer sized for exactly `count` TRANSACTION blocks.
     /// @param count Number of transaction blocks to allocate space for.
     /// @return writer Allocated writer.
     function allocTransactions(uint count) internal pure returns (Writer memory writer) {
         return alloc160s(count);
     }
 
-    /// @notice Allocate a writer for ASSET blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units
-    ///        (e.g. `ALLOC_SCALE` = 1:1, `2 * ALLOC_SCALE` = 2:1).
-    /// @return writer Allocated writer.
-    function allocScaledAssets(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocScaled64s(count, scaledRatio);
-    }
-
-    /// @notice Allocate a writer for AMOUNT blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units
-    ///        (e.g. `ALLOC_SCALE` = 1:1, `2 * ALLOC_SCALE` = 2:1).
-    /// @return writer Allocated writer.
-    function allocScaledAmounts(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocScaled96s(count, scaledRatio);
-    }
-
-    /// @notice Allocate a writer for BALANCE blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units
-    ///        (e.g. `ALLOC_SCALE` = 1:1, `2 * ALLOC_SCALE` = 2:1).
-    /// @return writer Allocated writer.
-    function allocScaledBalances(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocScaled96s(count, scaledRatio);
-    }
-
-    /// @notice Allocate a writer for CUSTODY blocks with a custom output-to-input ratio.
-    /// @param count Number of input blocks.
-    /// @param scaledRatio Output count multiplier in `ALLOC_SCALE` units.
-    /// @return writer Allocated writer.
-    function allocScaledCustodies(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
-        return allocScaled128s(count, scaledRatio);
-    }
-
     // -------------------------------------------------------------------------
     // Fixed-width write helpers
     // -------------------------------------------------------------------------