@rootzero/contracts 0.2.0 → 0.5.0

package/README.md

@@ -1,30 +1,22 @@
 # rootzero
 
-`rootzero` is the Solidity library used to build hosts and commands for the RootZero protocol.
+`rootzero` is the Solidity library for building hosts and commands for the rootzero protocol.
 
-It contains the reusable contracts, utilities, and encoding helpers that RootZero applications compose on top of. If you are building a RootZero host, a command contract, or a small protocol extension that needs to speak RootZero's id, asset, and block formats, this repo is the shared foundation.
-
-## What You Build With It
-
-- `Host` contracts that register with RootZero discovery and expose trusted command endpoints
-- `Command` contracts that execute protocol actions such as transfer, deposit, withdraw, settlement, and admin flows
-- Shared request/response block parsing and writing logic
-- Shared id, asset, account, and event encoding used across the protocol
+It contains the reusable contracts, utilities, cursor parsers, and encoding helpers that rootzero applications compose on top of. If you are building a host, a command contract, or protocol tooling that needs to speak the protocol's ID, asset, account, and block formats, this repo is the shared foundation.
 
 ## Main Entry Points
 
-Most consumers should start from the package root entrypoints:
+Most consumers should start from the package root entry points:
 
-- `@rootzero/contracts/Core.sol`: core host and validation building blocks
-- `@rootzero/contracts/Commands.sol`: base command contract plus standard command mixins
-- `@rootzero/contracts/Blocks.sol`: block schema, readers, and writers
-- `@rootzero/contracts/Utils.sol`: ids, assets, accounts, layout, strings, and value helpers
-- `@rootzero/contracts/Events.sol`: reusable event emitters and event contracts
+- `@rootzero/contracts/Core.sol` — host, access control, balances, and validator building blocks
+- `@rootzero/contracts/Commands.sol` — command and peer base contracts plus all standard command mixins
+- `@rootzero/contracts/Cursors.sol` — cursor reader (`Cur`), block schemas, key constants, memory refs, and writers
+- `@rootzero/contracts/Utils.sol` — IDs, assets, accounts, state discriminants, layout, and value helpers
+- `@rootzero/contracts/Events.sol` — reusable event emitters and event contracts
 
 ## Start Here
 
-If you are new to RootZero, start with the getting started guide in the repository:
-https://github.com/lastqubit/rootzero-contracts/blob/main/docs/GETTING_STARTED.md
+If you are new to rootzero, read [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) first.
 
 It walks through:
 
@@ -35,17 +27,40 @@ It walks through:
 - a custom command example
 - simple TypeScript request encoding
 
+## Block Wire Format
+
+All request and response data is encoded as a binary block stream. Each block is:
+
+```
+[bytes4 key][bytes4 payloadLen][payload]
+```
+
+`key` is `bytes4(keccak256(schemaString))` — see `Keys` for the full set. `Cursors` parses calldata streams zero-copy via the `Cur` struct; `Writers` builds response streams into pre-allocated memory; `Mem` parses in-memory streams for composed responses.
+
+## State Discriminants
+
+Every command declares its input and output state shape using constants from the `State` library:
+
+| Constant             | Meaning                           |
+|----------------------|-----------------------------------|
+| `State.Empty`        | No state (empty stream)           |
+| `State.Steps`        | STEP blocks (sub-command pipeline)|
+| `State.Balances`     | BALANCE blocks                    |
+| `State.Transactions` | TRANSACTION blocks                |
+| `State.Custodies`    | CUSTODY blocks                    |
+| `State.Claims`       | Claim records                     |
+
 ## Typical Usage
 
 ### Build a Host
 
-Extend `Host` when you want a RootZero host contract with admin command support and optional discovery registration.
+Extend `Host` when you want a rootzero host contract with admin command support and optional discovery registration.
 
 ```solidity
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Host} from "@rootzero/contracts/Core.sol";
+import { Host } from "@rootzero/contracts/Core.sol";
 
 contract ExampleHost is Host {
     constructor(address rootzero)
@@ -54,82 +69,67 @@ contract ExampleHost is Host {
 }
 ```
 
-`rootzero` is the trusted RootZero runtime. If it is a contract, the host also announces itself there during deployment. Use `address(0)` for a self-managed host that does not auto-register.
-
-`Host` already layers in the standard admin command flows used by RootZero hosts:
-
-- `Authorize`
-- `Unauthorize`
-- `Relocate`
+`rootzero` is the trusted runtime address. If it implements `IHostDiscovery`, the host announces itself there during deployment. Use `address(0)` for a self-managed host that does not auto-register.
 
 ### Build a Command
 
-Extend `CommandBase` when you want a RootZero command mixin that runs inside the protocol's trusted call model. Commands are abstract contracts mixed into a host or composed as a standalone module.
+Extend `CommandBase` to define a command mixin that runs inside the protocol's trusted call model. Commands are abstract contracts mixed into a host.
 
 ```solidity
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandBase, CommandContext} from "@rootzero/contracts/Commands.sol";
+import { CommandBase, CommandContext } from "@rootzero/contracts/Commands.sol";
+import { Cursors, Cur, Schemas } from "@rootzero/contracts/Cursors.sol";
+import { State } from "@rootzero/contracts/Utils.sol";
+
+using Cursors for Cur;
 
 string constant NAME = "myCommand";
-string constant ROUTE = "route(uint foo, uint bar)";
 
 abstract contract ExampleCommand is CommandBase {
     uint internal immutable myCommandId = commandId(NAME);
 
     constructor() {
-        emit Command(host, NAME, ROUTE, myCommandId, 0, 0);
+        emit Command(host, NAME, Schemas.Amount, myCommandId, State.Empty, State.Balances);
     }
 
     function myCommand(
         CommandContext calldata c
     ) external payable onlyCommand(myCommandId, c.target) returns (bytes memory) {
-        return "";
+        (Cur memory input, , ) = cursor(c.request, 1);
+        (bytes32 asset, bytes32 meta, uint amount) = input.unpackAmount();
+        input.complete();
+        return Cursors.toBalanceBlock(asset, meta, amount);
     }
 }
 ```
 
-`CommandBase` gives you the common RootZero command context:
-
-- trusted caller enforcement
-- admin checks
-- expiry checks
-- command-to-command or command-to-host calls through encoded RootZero node ids
-- shared command events
-
 ## Repo Layout
 
-- `contracts/core`: host, access control, balances, and validation primitives
-- `contracts/commands`: standard command building blocks and admin commands
-- `contracts/peer`: peer protocol surfaces for inter-host asset flows
-- `contracts/blocks`: request/response block encoding and decoding
-- `contracts/utils`: shared protocol encoding helpers
-- `contracts/events`: protocol event contracts and emitters
-- `contracts/interfaces`: discovery interfaces and shared external protocol surfaces
+- `contracts/core` — host, access control, balances, operation base, and signature validation
+- `contracts/commands` — standard command building blocks and admin commands
+- `contracts/peer` — peer protocol surfaces for inter-host asset flows and asset allow/deny
+- `contracts/blocks` — block stream schema (`Schema`), cursor parsing (`Cursors`), memory refs (`Mem`), and writers (`Writers`)
+- `contracts/utils` — shared encoding helpers: IDs, assets, accounts, state discriminants, layout, ECDSA
+- `contracts/events` — protocol event contracts and emitters
+- `contracts/interfaces` — discovery interfaces and shared external protocol surfaces
+- `docs` — introductory documentation
 
-## Install And Compile
+## Install and Compile
 
 ```bash
 npm install @rootzero/contracts
 npm run compile
 ```
 
-The stable import surface for consumers is:
-
-- `@rootzero/contracts/Core.sol`
-- `@rootzero/contracts/Commands.sol`
-- `@rootzero/contracts/Blocks.sol`
-- `@rootzero/contracts/Utils.sol`
-- `@rootzero/contracts/Events.sol`
-
 ## When To Use This Repo
 
 Use `rootzero` if you want to:
 
-- create a new RootZero host
-- implement a new RootZero command
-- reuse RootZero's block format and wire encoding
-- share protocol-level Solidity code across multiple RootZero applications
+- create a new rootzero host
+- implement a new rootzero command
+- reuse the protocol's block format and wire encoding
+- share protocol-level Solidity code across multiple rootzero applications
 
 If you are looking for a full end-user app or deployment repo, this library is the lower-level protocol package rather than the full product surface.

package/contracts/Commands.sol

@@ -1,9 +1,11 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+// Aggregator: re-exports all command and peer abstractions.
+// Import this file to inherit from any command or peer base contract without managing individual paths.
+
 import { CommandBase, CommandContext } from "./commands/Base.sol";
-import { NoOperation } from "./core/Operation.sol";
-import { Channels } from "./utils/Channels.sol";
+import { State } from "./utils/State.sol";
 import { BorrowAgainstBalanceToBalance, BorrowAgainstCustodyToBalance } from "./commands/Borrow.sol";
 import { Burn } from "./commands/Burn.sol";
 import { Create } from "./commands/Create.sol";
@@ -39,3 +41,6 @@ import { PeerAllowAssets } from "./peer/AllowAssets.sol";
 import { PeerDenyAssets } from "./peer/DenyAssets.sol";
 import { PeerPull } from "./peer/Pull.sol";
 import { PeerPush } from "./peer/Push.sol";
+
+
+

package/contracts/Core.sol

@@ -1,10 +1,16 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+// Aggregator: re-exports all core protocol contracts (Access, Balances, Host, Operation, Validator).
+// Import this file to bring the full host base layer into scope.
+
 import { AccessControl } from "./core/Access.sol";
 import { Balances } from "./core/Balances.sol";
 import { Host } from "./core/Host.sol";
-import { FailedCall, NoOperation, OperationBase } from "./core/Operation.sol";
+import { FailedCall, OperationBase } from "./core/Operation.sol";
 import { Validator } from "./core/Validator.sol";
 import { HostDiscovery } from "./core/Host.sol";
 import { IHostDiscovery } from "./interfaces/IHostDiscovery.sol";
+
+
+

package/contracts/{Blocks.sol → Cursors.sol}

@@ -1,9 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+// Aggregator: re-exports all block stream primitives (Cursors, Writers, Schema, Keys).
+// Import this file to get access to the full block encoding/decoding surface in one import.
+
 import { HostAmount, UserAmount, HostAsset, Tx, AssetAmount } from "./blocks/Schema.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { Block, BlockPair, Blocks } from "./blocks/Blocks.sol";
-import { Mem, MemRef } from "./blocks/Mem.sol";
+import { Cursors, Cur } from "./blocks/Cursors.sol";
 import { Writer, Writers } from "./blocks/Writers.sol";
+
+
+
+

package/contracts/Events.sol

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
+// Aggregator: re-exports all event contracts.
+// Import this file to get access to every event emitter in one import.
+
 import { AccessEvent } from "./events/Access.sol";
 import { AssetEvent } from "./events/Asset.sol";
 import { BalanceEvent } from "./events/Balance.sol";
@@ -16,3 +19,6 @@ import { PeerEvent } from "./events/Peer.sol";
 import { QuoteEvent } from "./events/Quote.sol";
 import { RootZeroEvent } from "./events/RootZero.sol";
 import { WithdrawalEvent } from "./events/Withdraw.sol";
+
+
+

package/contracts/Utils.sol

@@ -1,12 +1,18 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { Channels } from "./utils/Channels.sol";
+// Aggregator: re-exports all utility libraries (State, Accounts, Assets, ECDSA, Ids, Layout, Utils, Value).
+// Import this file to access the full utility surface without managing individual paths.
+
+import { State } from "./utils/State.sol";
 import { Accounts } from "./utils/Accounts.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
 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, bytes32ToString, isFamily, isLocal, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToString, divisible, isFamily, isLocal, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
 import { Values } from "./utils/Value.sol";
+
+
+