@rootzero/contracts 0.9.2 → 0.9.4

package/queries/Balances.sol

@@ -26,15 +26,15 @@ abstract contract GetBalances is QueryBase, GetBalancesHook {
     uint public immutable getBalancesId = queryId(NAME);
 
     constructor() {
-        emit Query(host, getBalancesId, NAME, Forms.AccountAsset, Forms.AccountAmount);
+        emit Query(host, getBalancesId, NAME, "1:1", Forms.AccountAsset, Forms.AccountAmount);
     }
 
     /// @notice Resolve balances for a run of requested `(account, asset, meta)` tuples.
     /// @param request Block-stream request consisting of `accountAsset(account, asset, meta)*`.
     /// @return Block-stream response containing one `accountAmount(account, asset, meta, amount)` block per request block.
     function getBalances(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory query, uint count, ) = cursor(request, 1);
-        Writer memory response = Writers.allocAccountAmounts(count);
+        (Cur memory query, uint groups) = cursor(request, 1);
+        Writer memory response = Writers.allocAccountAmounts(groups);
 
         while (query.i < query.bound) {
             (bytes32 account, bytes32 asset, bytes32 meta) = query.unpackAccountAsset();
@@ -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;
-        emit Query(host, getPositionId, NAME, Forms.AccountAsset, output);
+    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 count, ) = cursor(request, 1);
-        Writer memory response = Writers.allocBytes(count, positionResponseSize);
+        (Cur memory query, uint groups) = cursor(request, 1);
+        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, 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());
-    }
-}

package/docs/GETTING_STARTED.md

@@ -1,294 +0,0 @@
-# Getting Started With rootzero
-
-This guide is for developers who want to build on rootzero without reading the whole codebase first.
-
-If you remember only one thing, remember this:
-
-- A `Host` is your application contract.
-- A command is an entrypoint the rootzero runtime is allowed to call.
-- Requests and responses are passed around as typed byte blocks.
-
-## The Mental Model
-
-rootzero moves data through a small command context:
-
-```solidity
-struct CommandContext {
-    bytes32 account;
-    bytes state;
-    bytes request;
-}
-```
-
-In practice:
-
-- `account` is the user account the command is acting for.
-- `request` is the new input for this command.
-- `state` is live pipeline state produced by an earlier command.
-
-Most built-in commands follow a simple pattern:
-
-- read blocks from `request` or `state`
-- apply your host logic
-- return new blocks
-
-## Step 1: Start With A Host
-
-The smallest useful rootzero app is a host contract.
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.33;
-
-import {Host} from "@rootzero/contracts/Core.sol";
-
-contract ExampleHost is Host {
-    constructor(address rootzero)
-        Host(rootzero, 1, "example")
-    {}
-}
-```
-
-What the constructor arguments mean:
-
-- `rootzero`: the trusted rootzero runtime allowed to call commands
-- `1`: your host version
-- `"example"`: your host namespace
-
-If `rootzero` is a contract, the host announces itself there during deployment. If you pass `address(0)`, the host becomes self-managed and does not auto-register.
-
-## Step 2: Reuse A Built-In Command
-
-The easiest way to integrate is to inherit a built-in command module and implement its hook.
-
-This example adds `DebitAccount`, which turns `AMOUNT` blocks in `request` into `BALANCE` blocks in the response:
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.33;
-
-import {Host} from "@rootzero/contracts/Core.sol";
-import {DebitAccount} from "@rootzero/contracts/Commands.sol";
-import {Assets} from "@rootzero/contracts/Utils.sol";
-
-contract ExampleHost is Host, DebitAccount {
-    mapping(bytes32 account => mapping(bytes32 assetKey => uint amount)) internal balances;
-
-    constructor(address rootzero)
-        Host(rootzero, 1, "example")
-    {}
-
-    function debitAccount(
-        bytes32 account,
-        bytes32 asset,
-        bytes32 meta,
-        uint amount
-    ) internal override {
-        bytes32 key = Assets.slot(asset, meta);
-        balances[account][key] -= amount;
-    }
-}
-```
-
-Why this is a good first step:
-
-- you do not need to write block parsing yourself
-- you get the standard rootzero command surface
-- you only implement the business rule that is unique to your app
-
-## Step 3: Understand What Built-In Commands Consume
-
-The built-in commands are easiest to use when you know which blocks they expect.
-
-### Commands That Read `request`
-
-- `deposit`: reads `AMOUNT` blocks, returns `BALANCE`
-- `transfer`: reads `PAYOUT` blocks
-- `debitAccount`: reads `AMOUNT`, returns `BALANCE`
-- `provision`: reads `ALLOCATION`, returns `CUSTODY` state
-- `pipePayable`: reads `STEP` blocks and runs them in order
-
-### Commands That Read `state`
-
-- `withdraw`: reads `BALANCE`, optionally reads `ACCOUNT` from `request`
-- `creditAccount`: reads `BALANCE`, optionally reads `ACCOUNT` from `request`
-
-This is the main pattern to keep in mind:
-
-- use `request` for the command's direct input
-- use `state` for live value threaded through a pipeline, currently `BALANCE` and `CUSTODY`
-- use peer commands such as `peerSettle` for settlement messages such as `TRANSACTION`
-
-## Step 4: Send A Simple Request
-
-For a host that supports `deposit`, a request with one `AMOUNT` block is enough.
-
-TypeScript helper example:
-
-```ts
-import { ethers } from "ethers";
-import { encodeAmountBlock } from "../test/helpers/blocks.js";
-
-const asset = ethers.zeroPadValue("0x01", 32);
-const meta = ethers.ZeroHash;
-const amount = 100n;
-
-const ctx = {
-  account: "0x...", // 32-byte rootzero account id
-  state: "0x",
-  request: encodeAmountBlock(asset, meta, amount),
-};
-
-await host.deposit(ctx);
-```
-
-What happens:
-
-1. `deposit` reads the `AMOUNT` block from `ctx.request`.
-2. Your host applies its deposit logic.
-3. The command returns one `BALANCE` block for each deposited amount.
-
-## Step 5: Create A Custom Command
-
-When the built-in modules are not enough, add your own command entrypoint.
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.33;
-
-import {CommandBase, CommandContext, Keys} from "@rootzero/contracts/Commands.sol";
-import {Cursors, Cur, Schemas} from "@rootzero/contracts/Cursors.sol";
-
-using Cursors for Cur;
-
-string constant NAME = "myCommand";
-string constant ROUTE = "route(uint foo, uint bar)";
-string constant INPUT = string.concat(ROUTE, "&", Schemas.Amount);
-
-abstract contract MyCommand is CommandBase {
-    uint internal immutable myCommandId = commandId(NAME);
-
-    constructor() {
-        emit Command(host, myCommandId, NAME, INPUT, Keys.Empty, Keys.Balance, false);
-    }
-
-    function myCommand(
-        CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
-        Cur memory input = cursor(c.request);
-        uint next = input.bundle();
-
-        bytes calldata route = input.unpackRaw(Keys.Route);
-        (bytes32 asset, bytes32 meta, uint amount) = input.unpackAmount();
-        input.ensure(next);
-
-        route;
-        return Cursors.toBalanceBlock(asset, meta, amount);
-    }
-}
-```
-
-There are three important ideas here:
-
-- every custom command gets a deterministic command id
-- you announce it with the `Command` event
-- `onlyCommand(c.account)` ensures the caller is trusted and the calldata account matches `c.account`
-
-## Step 6: Read Input With A Cursor
-
-Cursor parsing is the nicest way to read structured command input.
-
-If your request contains a bundled input like:
-
-- `route(uint foo) & amount(bytes32 asset, bytes32 meta, uint amount)`
-
-your command can:
-
-- open it with `cursor(c.request)` or `Cursors.open(...)`
-- consume the route first
-- then consume the amount
-- keep parsing in bundle/member order without indexing helpers
-
-For simple projects, it is perfectly fine to:
-
-- publish the full input schema string in the `Command` event
-- encode bundled input blocks off-chain
-- decode them sequentially with cursor helpers inside the command
-
-## Step 7: Return State With Writers
-
-When your command needs to build response blocks manually, use `Writers`.
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.33;
-
-import {Writers, Writer} from "@rootzero/contracts/Cursors.sol";
-
-using Writers for Writer;
-
-function buildBalances() internal pure returns (bytes memory) {
-    Writer memory writer = Writers.allocBalances(2);
-    writer.appendBalance(bytes32(uint256(1)), bytes32(0), 50);
-    writer.appendBalance(bytes32(uint256(2)), bytes32(0), 75);
-    return writer.finish();
-}
-```
-
-Use this when your command needs to return:
-
-- balances
-- custody state
-
-If you are only consuming built-in commands, you often will not need to touch writers directly.
-
-## Query Forms
-
-Queries use reusable `Forms` as their input and output schema vocabulary. For example, `getBalances` accepts `Forms.AccountAsset` blocks and returns `Forms.AccountAmount` blocks:
-
-```solidity
-emit Query(host, NAME, Forms.AccountAsset, Forms.AccountAmount, getBalancesId);
-```
-
-This keeps query payloads structural: the query name describes what is being asked, while the form describes the fields carried by each block.
-
-## A Tiny End-To-End Example
-
-Imagine you want a host that keeps internal balances and lets rootzero debit them.
-
-1. Deploy a host that inherits `Host` and `DebitAccount`.
-2. Store balances in your own mapping.
-3. Implement `debitAccount(account, asset, meta, amount)`.
-4. Send `debitAccount` a request containing one or more `AMOUNT` blocks.
-5. rootzero returns `BALANCE` blocks representing the debited amounts.
-
-That is already a valid and useful integration.
-
-## Which Files To Open Next
-
-If you want to learn by example, these are the best files to read next:
-
-- `examples/1-Host.sol`: smallest host
-- `examples/2-Basic.sol`: host plus a built-in command hook
-- `examples/3-Command.sol`: custom command id and command event
-- `examples/4-Batch.sol`: batching request input and building balance output
-- `examples/5-Route.sol`: bundled route input plus protocol blocks
-- `test/commands.test.ts`: concrete request and response examples
-- `test/helpers/blocks.ts`: block encoders you can reuse in off-chain tooling
-
-## Common Mistakes
-
-- Passing data in `state` when the command expects it in `request`
-- Forgetting to emit a `Command` event for a custom command
-- Using an admin account with user-only command flows such as `pipePayable`
-- Trying to parse raw bytes manually when a built-in reader already exists
-- Starting with a custom command when a built-in module already matches the job
-
-## Recommended Learning Order
-
-1. Deploy a plain `Host`.
-2. Add one built-in command such as `DebitAccount` or `Deposit`.
-3. Use the TypeScript block helpers to build requests.
-4. Only then add a custom command with bundled input and cursor parsing.
-
-That path keeps the first integration small and easy to debug.

package/peer/AssetPull.sol

@@ -1,43 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {PeerBase} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
-
-using Cursors for Cur;
-
-abstract contract AssetPullHook {
-    /// @notice Override to process one incoming amount-based asset pull request from a peer host.
-    /// @param peer Peer host node ID for this request.
-    /// @param asset Requested asset identifier.
-    /// @param meta Requested asset metadata slot.
-    /// @param amount Requested amount in the asset's native units.
-    function assetPull(uint peer, bytes32 asset, bytes32 meta, uint amount) internal virtual;
-}
-
-/// @title PeerAssetPull
-/// @notice Peer that pulls requested asset amounts from a peer host into this one.
-/// Each AMOUNT block in the request calls `assetPull(peer, asset, meta, amount)`.
-/// Restricted to trusted peers.
-abstract contract PeerAssetPull is PeerBase, AssetPullHook {
-    string private constant NAME = "peerAssetPull";
-    uint internal immutable peerAssetPullId = peerId(NAME);
-
-    constructor() {
-        emit Peer(host, peerAssetPullId, NAME, Schemas.Amount, false);
-    }
-
-    /// @notice Execute the asset-pull peer call.
-    function peerAssetPull(bytes calldata request) external onlyPeer returns (bytes memory) {
-        (Cur memory assets, , ) = cursor(request, 1);
-        uint peer = caller();
-
-        while (assets.i < assets.bound) {
-            (bytes32 asset, bytes32 meta, uint amount) = assets.unpackAmount();
-            assetPull(peer, asset, meta, amount);
-        }
-
-        assets.complete();
-        return "";
-    }
-}