@rootzero/contracts 0.9.3 → 0.9.4

package/docs/Schema.md

@@ -0,0 +1,194 @@
+# Schema
+
+Rootzero request and response data is encoded as a stream of typed blocks. A
+schema string describes payload layout for discovery events and tooling; the
+runtime block key is derived only from the block name.
+
+## Wire Format
+
+Every block uses the same header:
+
+```txt
+[bytes4 key][uint32 payloadLen][payload]
+```
+
+`payloadLen` is big-endian and counts only payload bytes. Child blocks and list
+items use the same header format.
+
+The block key is:
+
+```txt
+bytes4(keccak256("#name"))
+```
+
+For example, `#amount { bytes32 asset, bytes32 meta, uint amount }` uses the key
+derived from `#amount`. Blocks must not be overloaded: one block name should have
+one protocol meaning.
+
+## Block Syntax
+
+A block starts with `#`. Fixed fields are written in braces:
+
+```txt
+#amount { bytes32 asset, bytes32 meta, uint amount }
+#account { bytes32 account }
+```
+
+A block without braces has no payload:
+
+```txt
+#unit
+#bytes
+```
+
+Empty braces are invalid. A zero-payload block must omit braces.
+
+A schema is a comma-separated list of items. Order is significant.
+
+```txt
+#amount { bytes32 asset, bytes32 meta, uint amount },
+maybe #account { bytes32 account }
+```
+
+## Payload Layout
+
+A block payload has fixed fields first, followed by an optional child-block tail.
+Once a child block appears, no more fixed fields may follow.
+
+```txt
+#call { uint target, uint value, #bytes as payload }
+#context { bytes32 account, uint value, #bytes as state, #bytes as request }
+```
+
+The tail is embedded directly as child block bytes. There is no wrapper around a
+child-block tail.
+
+Raw dynamic bytes are represented with the reserved `#bytes` child block. Use an
+alias to give those bytes a presentation name:
+
+```txt
+#bytes as payload
+```
+
+## Modifiers
+
+Cardinality is expressed with prefix keywords:
+
+```txt
+#balance { bytes32 asset, bytes32 meta, uint amount }
+maybe #balance { bytes32 asset, bytes32 meta, uint amount }
+many #balance { bytes32 asset, bytes32 meta, uint amount }
+maybe many #balance { bytes32 asset, bytes32 meta, uint amount }
+```
+
+- no prefix: one required item
+- `maybe`: optional item
+- `many`: one `#list` block whose payload contains repeated items
+- `maybe many`: optional `#list` block
+
+`maybe` emits no placeholder when absent. `many` wraps repeated items in one
+generic list block; it does not repeat the item in place.
+
+## Prime Items
+
+The empty string `""` means no schema. Whitespace-only schemas are invalid.
+
+For a non-empty schema, the first top-level item is the prime item. Prime items
+may repeat at the top level for batching. Later top-level items are globals for
+the whole batch and are not counted as per-operation prime blocks.
+
+The prime item cannot be optional. If a command needs a per-operation marker with
+no payload, use a zero-payload block such as `#unit`.
+
+## Aliases
+
+Aliases are presentation metadata for tooling. They do not change payload layout
+or runtime keys.
+
+```txt
+maybe #account { bytes32 account } as recipient
+#call { uint target, uint value, #bytes as payload }
+```
+
+Aliases may be used on any block item, including child blocks and prime items.
+
+## Field Types
+
+Supported field types are chain-neutral:
+
+```txt
+uint, uint8, uint16, uint32, uint64, uint128, uint256
+int, int8, int16, int32, int64, int128, int256
+bool
+bytes1 through bytes32
+```
+
+`uint` means `uint256`; `int` means `int256`. Other integer widths, unsized
+`bytes`, `string`, and array syntax are not part of the core schema DSL.
+
+Integers are encoded big-endian. Signed integers use two's-complement encoding
+for their declared width. `bool` is one byte: `0x00` for false and `0x01` for
+true. `bytesN` values are encoded as exactly `N` bytes with no padding.
+
+## Identifiers
+
+Block names, field names, and aliases use lower camelCase ASCII identifiers:
+
+```txt
+[a-z][a-zA-Z0-9]*
+```
+
+Invalid examples:
+
+```txt
+Amount
+asset_meta
+asset-meta
+0account
+```
+
+Reserved words include `maybe`, `many`, `as`, all field type names, and the
+reserved block names `bytes`, `data`, and `list`.
+
+## Reserved Blocks
+
+- `#bytes`: raw dynamic bytes, written without a body
+- `#data`: generic/custom payload block
+- `#list`: generic list wrapper emitted by `many`
+
+Use `#data` when a local schema needs a stable generic key:
+
+```txt
+#data { uint foo, bytes32 tag }
+#data { #bytes as payload }
+```
+
+If a schema string starts with a fixed field type, it is shorthand for one
+top-level `#data` block:
+
+```txt
+uint foo, bytes32 tag
+```
+
+expands to:
+
+```txt
+#data { uint foo, bytes32 tag }
+```
+
+## Standard Blocks
+
+Common protocol schemas live in `contracts/blocks/Schema.sol`:
+
+```txt
+#amount { bytes32 asset, bytes32 meta, uint amount }
+#balance { bytes32 asset, bytes32 meta, uint amount }
+#custody { uint host, bytes32 asset, bytes32 meta, uint amount }
+#payout { bytes32 account, bytes32 asset, bytes32 meta, uint amount }
+#call { uint target, uint value, #bytes as payload }
+#step { uint target, uint value, #bytes as request }
+#context { bytes32 account, uint value, #bytes as state, #bytes as request }
+#auth { uint cid, uint deadline, #bytes as proof }
+```
+
+`Keys.sol` contains the corresponding runtime keys.

package/events/Command.sol

@@ -14,8 +14,7 @@ abstract contract CommandEvent is EventEmitter {
     /// @param shape Per-operation prime block counts encoded as `request:state:output`.
     /// Blocks outside the prime runs are global batch blocks and are excluded
     /// from the counts.
-    /// @param request Schema DSL string describing the request shape; use `empty;...`
-    /// when the request has global blocks but no prime blocks.
+    /// @param request Schema string describing the request shape.
     /// @param state Block key expected for input state, or `Keys.Empty`.
     /// @param output Block key produced for output state, or `Keys.Empty`.
     /// @param acceptsValue Whether the command entrypoint accepts nonzero `msg.value`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",
@@ -9,7 +9,7 @@
     "**/*.sol",
     "README.md",
     "LICENSE",
-    "docs/GETTING_STARTED.md"
+    "docs/Schema.md"
   ],
   "publishConfig": {
     "access": "public"

package/peer/AllowAssets.sol

@@ -27,7 +27,7 @@ abstract contract PeerAllowAssets is PeerBase, AllowAssetsHook {
             allowAsset(asset, meta);
         }
 
-        assets.complete();
+        assets.close();
         return "";
     }
 }

package/peer/Allowance.sol

@@ -29,7 +29,7 @@ abstract contract PeerAllowance is PeerBase, AllowanceHook {
             allowance(peer, asset, meta, amount);
         }
 
-        amounts.complete();
+        amounts.close();
         return "";
     }
 }

package/peer/BalancePull.sol

@@ -37,7 +37,7 @@ abstract contract PeerBalancePull is PeerBase, BalancePullHook {
             balancePull(peer, asset, meta, amount);
         }
 
-        input.complete();
+        input.close();
         return "";
     }
 }

package/peer/DenyAssets.sol

@@ -27,7 +27,7 @@ abstract contract PeerDenyAssets is PeerBase, DenyAssetsHook {
             denyAsset(asset, meta);
         }
 
-        assets.complete();
+        assets.close();
         return "";
     }
 }

package/peer/Pipe.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {PeerBase} from "./Base.sol";
+import {Pipeline} from "../core/Pipeline.sol";
+import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Budget} from "../utils/Value.sol";
+
+using Cursors for Cur;
+
+/// @title PeerPipePayable
+/// @notice Peer that consumes CONTEXT blocks and executes each context request as a STEP stream.
+/// Each CONTEXT block carries an account, state, and request; the request is passed to the
+/// shared pipeline as the step stream.
+abstract contract PeerPipePayable is PeerBase, Pipeline {
+    string private constant NAME = "peerPipePayable";
+    uint internal immutable peerPipePayableId = peerId(NAME);
+
+    constructor() {
+        emit Peer(host, peerPipePayableId, NAME, "1:0", Schemas.Context, "", true);
+    }
+
+    /// @notice Execute peer-supplied contexts through the shared payable pipe.
+    /// @dev Each context receives its own explicit value sub-budget. Any top-level
+    ///      `msg.value` not assigned to a context remains on this host.
+    function peerPipePayable(bytes calldata request) external payable onlyPeer returns (bytes memory) {
+        (Cur memory input, ) = cursor(request, 1);
+        Budget memory budget = valueBudget();
+
+        while (input.i < input.bound) {
+            (bytes32 account, uint value, bytes calldata state, bytes calldata steps) = input.unpackContext();
+            pipe(account, state, steps, allocateValue(budget, value));
+        }
+
+        input.close();
+        return "";
+    }
+}

package/peer/Settle.sol

@@ -26,7 +26,7 @@ abstract contract PeerSettle is PeerBase, TransferHook {
             transfer(state.unpackTxValue());
         }
 
-        state.complete();
+        state.close();
         return "";
     }
 }

package/queries/Assets.sol

@@ -30,8 +30,8 @@ abstract contract IsAllowedAsset is QueryBase, IsAllowedAssetHook {
     }
 
     /// @notice Resolve allowlist status for a run of requested `(asset, meta)` tuples.
-    /// @param request Block-stream request consisting of `asset(asset, meta)*`.
-    /// @return Block-stream response containing one `status(ok)` per asset block.
+    /// @param request Block-stream request consisting of `#asset { bytes32 asset, bytes32 meta }` blocks.
+    /// @return Block-stream response containing one `#status { bool ok }` per asset block.
     function isAllowedAsset(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint groups) = cursor(request, 1);
         Writer memory response = Writers.allocStatuses(groups);
@@ -42,6 +42,7 @@ abstract contract IsAllowedAsset is QueryBase, IsAllowedAssetHook {
             response.appendStatus(allowed);
         }
 
-        return query.complete(response);
+        query.close();
+        return response.finish();
     }
 }

package/queries/Balances.sol

@@ -42,6 +42,7 @@ abstract contract GetBalances is QueryBase, GetBalancesHook {
             response.appendAccountAmount(account, asset, meta, amount);
         }
 
-        return query.complete(response);
+        query.close();
+        return response.finish();
     }
 }

package/queries/Positions.sol

@@ -6,11 +6,12 @@ import {Forms} from "../blocks/Schema.sol";
 import {QueryBase} from "./Base.sol";
 
 using Cursors for Cur;
+using Writers for Writer;
 
 abstract contract GetPositionHook {
-    /// @notice Resolve the position payload for one requested position.
-    /// Concrete implementations must append exactly one `RESPONSE` block whose payload
-    /// length matches `positionResponseSize`.
+    /// @notice Append the position response for one requested position.
+    /// Concrete implementations must append exactly one response block matching
+    /// the query output schema.
     /// @param account Requested account identifier.
     /// @param asset Requested asset identifier.
     /// @param meta Requested asset metadata slot.
@@ -26,31 +27,30 @@ abstract contract GetPositionHook {
 /// @title GetPosition
 /// @notice Rootzero query that resolves one dynamic position response for each requested position.
 /// The request is a run of `ACCOUNT_ASSET` form blocks.
-/// The response returns one dynamic `RESPONSE` block per position entry, preserving request order.
+/// The response returns one output-schema block per position entry, preserving request order.
 abstract contract GetPosition is QueryBase, GetPositionHook {
     string private constant NAME = "getPosition";
+
     uint public immutable getPositionId = queryId(NAME);
-    uint internal immutable positionResponseSize;
 
-    constructor(string memory output, uint responseSize) {
-        positionResponseSize = responseSize;
+    constructor(string memory output) {
         emit Query(host, getPositionId, NAME, "1:1", Forms.AccountAsset, output);
     }
 
     /// @notice Resolve positions for a run of requested `(account, asset, meta)` tuples.
-    /// @dev Allocates from the configured fixed response payload length so each hook call
-    ///      can append one `RESPONSE` block directly into the output stream.
+    /// @dev Allocates from a per-block capacity hint and grows when position outputs exceed it.
     /// @param request Block-stream request consisting of `accountAsset(account, asset, meta)*`.
-    /// @return Block-stream response containing one `response(bytes data)` block per position block.
+    /// @return Block-stream response containing one output-schema block per position block.
     function getPosition(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint groups) = cursor(request, 1);
-        Writer memory response = Writers.allocBytes(groups, positionResponseSize);
+        Writer memory response = Writers.allocAny(groups);
 
         while (query.i < query.bound) {
             (bytes32 account, bytes32 asset, bytes32 meta) = query.unpackAccountAsset();
             appendPosition(account, asset, meta, response);
         }
 
-        return query.complete(response);
+        query.close();
+        return response.finish();
     }
 }

package/utils/Value.sol

@@ -8,17 +8,11 @@ struct Budget {
 }
 
 /// @title Values
-/// @notice Native-value (ETH) budget tracking for commands that accept `msg.value`.
+/// @notice Native-value budget mutation helpers.
 library Values {
     /// @dev Thrown when a call attempts to spend more native value than remains in the budget.
     error InsufficientValue();
 
-    /// @notice Create a budget from the current call's `msg.value`.
-    /// @return Budget initialised with the full `msg.value`.
-    function fromMsg() internal view returns (Budget memory) {
-        return Budget({remaining: msg.value});
-    }
-
     /// @notice Deduct `amount` from the budget and return it.
     /// Reverts if `amount` exceeds `budget.remaining`.
     /// @param budget Mutable budget to deduct from.
@@ -30,12 +24,12 @@ library Values {
         return amount;
     }
 
-    /// @notice Deduct all remaining native value from the budget and return it.
-    /// @param budget Mutable budget to drain.
-    /// @return Remaining native value before the budget was emptied.
-    function drain(Budget memory budget) internal pure returns (uint) {
-        uint amount = budget.remaining;
-        budget.remaining = 0;
-        return amount;
+    /// @notice Deduct `amount` from the budget and return it as a new sub-budget.
+    /// Reverts if `amount` exceeds `budget.remaining`.
+    /// @param budget Mutable parent budget to deduct from.
+    /// @param amount Native value to assign to the sub-budget, in wei.
+    /// @return A new budget with `amount` remaining.
+    function allocate(Budget memory budget, uint amount) internal pure returns (Budget memory) {
+        return Budget({remaining: use(budget, amount)});
     }
 }

package/commands/Pipe.sol

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {CommandBase, CommandContext, CommandPayable, Keys} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
-import {Accounts} from "../utils/Accounts.sol";
-import {Budget, Values} from "../utils/Value.sol";
-
-using Cursors for Cur;
-
-abstract contract PipePayableHook {
-    /// @notice Override to dispatch one piped command step.
-    /// Called once per STEP block. The returned bytes become the state passed to
-    /// the next step.
-    /// @param id Command node ID to invoke or handle.
-    /// @param account Account identifier for the piped command context.
-    /// @param state Current threaded state block stream.
-    /// @param request Step request block stream.
-    /// @param value Native value assigned to this step.
-    /// @return Updated state block stream for the next step.
-    function dispatchCommand(
-        uint id,
-        bytes32 account,
-        bytes memory state,
-        bytes calldata request,
-        uint value
-    ) internal virtual returns (bytes memory);
-}
-
-/// @title PipePayable
-/// @notice Command that sequences multiple sub-command STEP invocations in a single transaction.
-/// Each STEP block carries a command node, native value to forward, and an embedded request.
-/// State threads through the steps: each step's output becomes the next step's state.
-/// Admin accounts are not permitted to use `pipePayable`.
-abstract contract PipePayable is CommandPayable, PipePayableHook {
-    string private constant NAME = "pipePayable";
-
-    uint internal immutable pipePayableId = commandId(NAME);
-
-    constructor() {
-        emit Command(host, pipePayableId, NAME, "1:0:0", Schemas.Step, Keys.Empty, Keys.Empty, true);
-    }
-
-    function pipe(
-        bytes32 account,
-        bytes memory state,
-        bytes calldata steps,
-        Budget memory budget
-    ) internal returns (bytes memory) {
-        (Cur memory input, ) = cursor(steps, 1);
-
-        while (input.i < input.bound) {
-            (uint target, uint value, bytes calldata request) = input.unpackStep();
-            uint spend = Values.use(budget, value);
-            state = dispatchCommand(target, account, state, request, spend);
-        }
-
-        settleValue(account, budget);
-        input.complete();
-        return state;
-    }
-
-    /// @notice Execute the pipePayable command.
-    function pipePayable(CommandContext calldata c) external payable onlyCommand(c.account) returns (bytes memory) {
-        return pipe(Accounts.ensureNotAdmin(c.account), c.state, c.request, Values.fromMsg());
-    }
-}