@rootzero/contracts 0.5.0 → 0.5.1

package/docs/GETTING_STARTED.md

@@ -0,0 +1,286 @@
+# 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 {
+    uint target;
+    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 data produced by an earlier command in a pipeline.
+- `target` is the command id you expect to receive, or `0`.
+
+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.key(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 `AMOUNT` plus `RECIPIENT`
+- `debitAccount`: reads `AMOUNT`, returns `BALANCE`
+- `provision`: reads `AMOUNT` plus `NODE`, returns `CUSTODY`
+- `pipe`: reads `STEP` blocks and runs them in order
+
+### Commands That Read `state`
+
+- `withdraw`: reads `BALANCE`, optionally reads `RECIPIENT` from `request`
+- `creditAccount`: reads `BALANCE`, optionally reads `RECIPIENT` from `request`
+- `settle`: reads `TX`
+- `provisionFromBalance`: reads `BALANCE` from `state` and `NODE` from `request`
+
+This is the main pattern to keep in mind:
+
+- use `request` for the command's direct input
+- use `state` when a previous command already produced the input
+
+## 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 = {
+  target: 0n,
+  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 {Host} from "@rootzero/contracts/Core.sol";
+import {CommandBase, CommandContext, Channels} from "@rootzero/contracts/Commands.sol";
+import {Cursors, Cursor, Schemas} from "@rootzero/contracts/Cursors.sol";
+
+using Cursors for Cursor;
+
+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, NAME, INPUT, myCommandId, Channels.Setup, Channels.Balances);
+    }
+
+    function myCommand(
+        CommandContext calldata c
+    ) external payable onlyCommand(myCommandId, c.target) returns (bytes memory) {
+        Cursor memory input = Cursors.openBlock(c.request, 0);
+        uint foo = input.unpackRouteUint();
+        (bytes32 asset, bytes32 meta, uint amount) = input.unpackAmount();
+        foo;
+        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(myCommandId, c.target)` ensures the trusted caller hit the right endpoint
+
+## 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 `Cursors.openBlock(...)`
+- 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.done();
+}
+```
+
+Use this when your command needs to return:
+
+- balances
+- custodies
+- transactions
+
+If you are only consuming built-in commands, you often will not need to touch writers directly.
+
+## 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 `debitAccountToBalance` 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 the wrong `target` value for `onlyCommand`
+- 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/package.json

@@ -1,33 +1,17 @@
-{
-  "name": "@rootzero/contracts",
-  "version": "0.5.0",
-  "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
-  "private": false,
-  "license": "GPL-3.0-only",
-  "type": "module",
-  "files": [
-    "*.sol",
-    "contracts/**/*.sol",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "compile": "hardhat compile",
-    "test": "hardhat test",
-    "prepublishOnly": "npm test",
-    "prepare:package": "node scripts/prepare-package.mjs",
-    "pack:package": "npm run prepare:package && npm pack ./dist/package",
-    "publish:package": "npm test && npm run prepare:package && npm publish ./dist/package --access public"
-  },
-  "devDependencies": {
-    "@nomicfoundation/hardhat-mocha": "^3.0.13",
-    "chai": "^6.2.2",
-    "ethers": "^6.16.0",
-    "hardhat": "^3.1.7",
-    "mocha": "^11.7.5",
-    "typescript": "~5.8.0"
-  }
-}
+{
+  "name": "@rootzero/contracts",
+  "version": "0.5.1",
+  "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
+  "private": false,
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "files": [
+    "**/*.sol",
+    "README.md",
+    "LICENSE",
+    "docs/GETTING_STARTED.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/contracts/test/TestBorrowHost.sol

@@ -1,72 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { Host } from "../core/Host.sol";
-import { BorrowAgainstCustodyToBalance } from "../commands/Borrow.sol";
-import { AssetAmount, HostAmount } from "../blocks/Schema.sol";
-import { Cur, Cursors, Keys } from "../Cursors.sol";
-import { Ids } from "../utils/Ids.sol";
-
-using Cursors for Cur;
-
-contract TestBorrowHost is Host, BorrowAgainstCustodyToBalance {
-    event BorrowCalled(bytes32 account, bytes32 asset, bytes32 meta, uint amount, bytes inputData);
-
-    bytes32 public returnAsset;
-    bytes32 public returnMeta;
-    uint public returnAmount;
-
-    constructor(address cmdr) Host(address(0), 1, "test") BorrowAgainstCustodyToBalance("") {
-        if (cmdr != address(0)) access(Ids.toHost(cmdr), true);
-    }
-
-    function setReturn(bytes32 asset, bytes32 meta, uint amount) external {
-        returnAsset = asset;
-        returnMeta = meta;
-        returnAmount = amount;
-    }
-
-    function borrowAgainstCustodyToBalance(
-        bytes32 account,
-        HostAmount memory custody,
-        Cur memory request
-    ) internal override returns (AssetAmount memory) {
-        if (request.i < request.len) {
-            bytes calldata inputData;
-            (bytes4 key, uint len) = request.peek(request.i);
-            if (key == Keys.Bundle) {
-                Cur memory bundle = request.bundle();
-                (key, len) = bundle.peek(bundle.i);
-                if (key == Keys.Route) {
-                    inputData = bundle.unpackRoute();
-                } else {
-                    uint next = bundle.i + 8 + len;
-                    inputData = msg.data[bundle.offset + bundle.i:bundle.offset + next];
-                    bundle.i = next;
-                }
-            } else if (key == Keys.Route) {
-                inputData = request.unpackRoute();
-            } else {
-                uint next = request.i + 8 + len;
-                inputData = msg.data[request.offset + request.i:request.offset + next];
-                request.i = next;
-            }
-            emit BorrowCalled(account, custody.asset, custody.meta, custody.amount, inputData);
-        } else {
-            emit BorrowCalled(account, custody.asset, custody.meta, custody.amount, "");
-        }
-        return AssetAmount({asset: returnAsset, meta: returnMeta, amount: returnAmount});
-    }
-
-    function getBorrowId() external view returns (uint) {
-        return borrowAgainstCustodyToBalanceId;
-    }
-
-    function getAdminAccount() external view returns (bytes32) {
-        return adminAccount;
-    }
-}
-
-
-
-

package/contracts/test/TestBurnHost.sol

@@ -1,31 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { Host } from "../core/Host.sol";
-import { Burn } from "../commands/Burn.sol";
-import { Ids } from "../utils/Ids.sol";
-
-contract TestBurnHost is Host, Burn {
-    event BurnCalled(bytes32 account, bytes32 asset, bytes32 meta, uint amount);
-
-    constructor(address cmdr)
-        Host(address(0), 1, "test")
-        Burn()
-    {
-        if (cmdr != address(0)) access(Ids.toHost(cmdr), true);
-    }
-
-    function burn(bytes32 account, bytes32 asset, bytes32 meta, uint amount)
-        internal override
-        returns (uint)
-    {
-        emit BurnCalled(account, asset, meta, amount);
-        return amount;
-    }
-
-    function getBurnId() external view returns (uint) { return burnId; }
-    function getAdminAccount() external view returns (bytes32) { return adminAccount; }
-}
-
-
-

package/contracts/test/TestCreateHost.sol

@@ -1,40 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { Host } from "../core/Host.sol";
-import { Create } from "../commands/Create.sol";
-import { Cursors, Cur, Keys } from "../Cursors.sol";
-import { Ids } from "../utils/Ids.sol";
-
-using Cursors for Cur;
-
-contract TestCreateHost is Host, Create {
-    event CreateCalled(bytes32 account, bytes inputData);
-
-    constructor(address cmdr)
-        Host(address(0), 1, "test")
-        Create("")
-    {
-        if (cmdr != address(0)) access(Ids.toHost(cmdr), true);
-    }
-
-    function create(bytes32 account, Cur memory input) internal override {
-        (bytes4 key, uint len) = input.peek(input.i);
-        bytes calldata inputData;
-        if (key == Keys.Route) {
-            inputData = input.unpackRoute();
-        } else {
-            uint next = input.i + 8 + len;
-            inputData = msg.data[input.offset + input.i:input.offset + next];
-            input.i = next;
-        }
-        emit CreateCalled(account, inputData);
-    }
-
-    function getCreateId() external view returns (uint) { return createId; }
-    function getAdminAccount() external view returns (bytes32) { return adminAccount; }
-}
-
-
-
-

package/contracts/test/TestCursorHelper.sol

@@ -1,191 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { Tx, Sizes } from "../blocks/Schema.sol";
-import { Cur, Cursors, Writer } from "../Cursors.sol";
-import { Writers } from "../blocks/Writers.sol";
-
-using Cursors for Cur;
-using Writers for Writer;
-
-contract TestCursorHelper {
-    function testBlockHeader(bytes4 key, uint len) external pure returns (uint) {
-        return Writers.toBlockHeader(key, len);
-    }
-
-    function testWriteBalanceBlock(bytes32 asset, bytes32 meta, uint amount) external pure returns (bytes memory) {
-        Writer memory w = Writers.alloc(Sizes.Balance);
-        w.appendBalance(asset, meta, amount);
-        return w.dst;
-    }
-
-    function testWriteCustodyBlock(
-        uint host_,
-        bytes32 asset,
-        bytes32 meta,
-        uint amount
-    ) external pure returns (bytes memory) {
-        Writer memory w = Writers.alloc(Sizes.Custody);
-        w.appendCustody(host_, asset, meta, amount);
-        return w.dst;
-    }
-
-    function testWriteTxBlock(
-        bytes32 from_,
-        bytes32 to_,
-        bytes32 asset,
-        bytes32 meta,
-        uint amount
-    ) external pure returns (bytes memory) {
-        Writer memory w = Writers.alloc(Sizes.Transaction);
-        w.appendTx(Tx({ from: from_, to: to_, asset: asset, meta: meta, amount: amount }));
-        return w.dst;
-    }
-
-    function testToBountyBlock(uint amount, bytes32 relayer) external pure returns (bytes memory) {
-        return Cursors.toBountyBlock(amount, relayer);
-    }
-
-    function testToBalanceBlock(bytes32 asset, bytes32 meta, uint amount) external pure returns (bytes memory) {
-        return Cursors.toBalanceBlock(asset, meta, amount);
-    }
-
-    function testToCustodyBlock(
-        uint host_,
-        bytes32 asset,
-        bytes32 meta,
-        uint amount
-    ) external pure returns (bytes memory) {
-        return Cursors.toCustodyBlock(host_, asset, meta, amount);
-    }
-
-    function testWriterFinishIncomplete() external pure returns (bytes memory) {
-        Writer memory w = Writers.alloc(Sizes.Balance);
-        return Writers.finish(w);
-    }
-
-    function testWriterFinish(bytes32 asset, bytes32 meta, uint amount) external pure returns (bytes memory) {
-        Writer memory w = Writers.alloc(Sizes.Balance * 2);
-        w.appendBalance(asset, meta, amount);
-        return Writers.finish(w);
-    }
-
-    function testUnpackBalance(bytes calldata source) external pure returns (bytes32 asset, bytes32 meta, uint amount) {
-        Cur memory cur = Cursors.open(source);
-        return cur.unpackBalance();
-    }
-
-    function testToTxValue(bytes calldata source) external pure returns (bytes32 from_, bytes32 to_, bytes32 asset, bytes32 meta, uint amount) {
-        Cur memory cur = Cursors.open(source);
-        Tx memory value = cur.unpackTxValue();
-        return (value.from, value.to, value.asset, value.meta, value.amount);
-    }
-
-    function testPrimeRun(bytes calldata source, uint group)
-        external
-        pure
-        returns (bytes4 key, uint count, uint quotient, uint offset, uint i, uint len, uint bound)
-    {
-        uint sourceOffset;
-        assembly ("memory-safe") {
-            sourceOffset := source.offset
-        }
-        Cur memory cur = Cursors.open(source);
-        (key, count, quotient) = cur.primeRun(group);
-        return (key, count, quotient, cur.offset - sourceOffset, cur.i, cur.len, cur.bound);
-    }
-
-    function testPeek(bytes calldata source, uint i) external pure returns (bytes4 key, uint len) {
-        Cur memory cur = Cursors.open(source);
-        return cur.peek(i);
-    }
-
-    function testCountRun(bytes calldata source, uint i, bytes4 key) external pure returns (uint total, uint next) {
-        Cur memory cur = Cursors.open(source);
-        return cur.countRun(i, key);
-    }
-
-    function testBundle(bytes calldata source) external pure returns (uint inputI, uint offset, uint len) {
-        uint sourceOffset;
-        assembly ("memory-safe") {
-            sourceOffset := source.offset
-        }
-        Cur memory cur = Cursors.open(source);
-        Cur memory out = cur.bundle();
-        return (cur.i, out.offset - sourceOffset, out.len);
-    }
-
-    function testUnpackStep(bytes calldata source) external pure returns (uint target, uint value, bytes calldata req, uint i) {
-        Cur memory cur = Cursors.open(source);
-        (target, value, req) = cur.unpackStep();
-        return (target, value, req, cur.i);
-    }
-
-    function testRequireAmount(
-        bytes calldata source,
-        bytes32 asset,
-        bytes32 meta
-    ) external pure returns (uint amount, uint i) {
-        Cur memory cur = Cursors.open(source);
-        amount = cur.requireAmount(asset, meta);
-        i = cur.i;
-    }
-
-    function testRequireAuth(bytes calldata source, uint cid) external pure returns (uint deadline, bytes calldata proof, uint i) {
-        Cur memory cur = Cursors.open(source);
-        (deadline, proof) = cur.requireAuth(cid);
-        return (deadline, proof, cur.i);
-    }
-
-    function testNodeAfter(bytes calldata source, uint group, uint backup) external pure returns (uint) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        return cur.nodeAfter(backup);
-    }
-
-    function testRecipientAfter(bytes calldata source, uint group, bytes32 backup) external pure returns (bytes32) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        return cur.recipientAfter(backup);
-    }
-
-    function testAuthLast(
-        bytes calldata source,
-        uint group,
-        uint cid
-    ) external pure returns (bytes32 hash, uint deadline, bytes calldata proof) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        return cur.authLast(cid);
-    }
-
-    function testCursorCompleteEmpty(bytes calldata source, uint group) external pure returns (bool) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        cur.complete();
-        return true;
-    }
-
-    function testCursorCompletePartial(bytes calldata source, uint group) external pure returns (bool) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        if (cur.bound > 0) {
-            (, uint len) = cur.peek(cur.i);
-            cur.i += 8 + len;
-        }
-        cur.complete();
-        return true;
-    }
-
-    function testCursorCompleteConsumed(bytes calldata source, uint group) external pure returns (bool) {
-        Cur memory cur = Cursors.open(source);
-        cur.primeRun(group);
-        while (cur.i < cur.bound) {
-            (, uint len) = cur.peek(cur.i);
-            cur.i += 8 + len;
-        }
-        cur.complete();
-        return true;
-    }
-
-}

package/contracts/test/TestDiscovery.sol

@@ -1,9 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { HostDiscovery } from "../core/Host.sol";
-
-contract TestDiscovery is HostDiscovery {}
-
-
-