@rootzero/contracts 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.3.0
+
+### Breaking Changes
+
+- Simplified `Cursors.init` to parse a single run from the start of a calldata slice. Callers that previously passed an offset must slice first or use `Cursors.open(source, i)`.
+- Tightened command, query, and peer request parsing around the single-run convention used by current protocol endpoints.
+
+### Added
+
+- Added `peerCreditTo` and `peerDebitFrom` peer endpoints for account-scoped `ACCOUNT_AMOUNT` batches.
+- Added same-file `IPeer*` interfaces for every peer endpoint and exported them from `Endpoints.sol`.
+- Added indexing documentation covering discovery, labels, access state, balance events, and flow-event conventions.
+
+## 1.2.0
+
+### Breaking Changes
+
+- Removed human-readable names from Command, Admin, Peer, Query, Guard, and Chain discovery events.
+- Added the Labeled event and default labels for commands, admin commands, peers, queries, guards, and examples.
+- Added LABEL and STRING block schemas, plus cursor helpers for decoding labels supplied by callers.
+- Added the admin label command for publishing mutable namespaced labels.
+- Removed version and namespace fields from host Introduction events and host constructor introductions.
+
 ## 1.1.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -29,17 +29,20 @@ import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
 import { Dismiss } from "./commands/admin/Dismiss.sol";
 import { ExecutePayable } from "./commands/admin/Execute.sol";
 import { Init, InitHook } from "./commands/admin/Init.sol";
+import { Label } from "./commands/admin/Label.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 
 // Peer endpoints
 import { PeerBase, encodePeerCall } from "./peer/Base.sol";
-import { PeerAllowAssets } from "./peer/AllowAssets.sol";
-import { PeerAllowance } from "./peer/Allowance.sol";
-import { PeerBalancePull, BalancePullHook } from "./peer/BalancePull.sol";
-import { PeerDenyAssets } from "./peer/DenyAssets.sol";
-import { PeerPipePayable } from "./peer/Pipe.sol";
-import { PeerDispatchPayable } from "./peer/Dispatch.sol";
-import { PeerSettle } from "./peer/Settle.sol";
+import { PeerAllowAssets, IPeerAllowAssets } from "./peer/AllowAssets.sol";
+import { PeerAllowance, IPeerAllowance } from "./peer/Allowance.sol";
+import { PeerBalancePull, BalancePullHook, IPeerBalancePull } from "./peer/BalancePull.sol";
+import { PeerCreditTo, IPeerCreditTo } from "./peer/Credit.sol";
+import { PeerDebitFrom, IPeerDebitFrom } from "./peer/Debit.sol";
+import { PeerDenyAssets, IPeerDenyAssets } from "./peer/DenyAssets.sol";
+import { PeerPipePayable, IPeerPipePayable } from "./peer/Pipe.sol";
+import { PeerDispatchPayable, IPeerDispatchPayable } from "./peer/Dispatch.sol";
+import { PeerSettle, IPeerSettle } from "./peer/Settle.sol";
 
 // Guard endpoints
 import { GuardBase, encodeGuardCall } from "./guards/Base.sol";

package/Events.sol

@@ -16,6 +16,7 @@ import { EventEmitter } from "./events/Emitter.sol";
 import { GuardEvent } from "./events/Guard.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";
+import { LabeledEvent } from "./events/Labeled.sol";
 import { LockedEvent } from "./events/Locked.sol";
 import { NodeEvent } from "./events/Node.sol";
 import { PeerEvent } from "./events/Peer.sol";

package/README.md

@@ -1,128 +1,349 @@
 # rootzero
 
-`rootzero` is the Solidity library for building hosts and commands for the rootzero protocol.
+rootzero is a protocol for building **hosts**: contracts that expose a uniform
+set of endpoints over accounts and assets — commands that change state,
+queries that read it, and peer links that connect hosts to each other, on the
+same chain or across chains.
 
-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.
+This repository is `@rootzero/contracts`, the Solidity library for the EVM port
+of the protocol: the base contracts, block codecs, and helpers that rootzero
+applications compose.
 
-## Main Entry Points
+Two decisions shape everything below. First, all data that crosses a host
+boundary is encoded in one binary block format, so a request means the same
+bytes on every chain. Second, every surface operates on *runs* of blocks rather
+than single values, so batching is the default, not a feature added later. This
+guide introduces the protocol bottom-up: blocks, then identities, then hosts
+and the endpoints built on top of them.
 
-Most consumers should start from the package root entry points:
+## Quick Start
 
-- `@rootzero/contracts/Core.sol` - host, access control, balances, and validator building blocks
-- `@rootzero/contracts/Endpoints.sol` - command, peer, guard, and query base contracts plus standard endpoint mixins
-- `@rootzero/contracts/Cursors.sol` - cursor reader (`Cur`), block schemas, key constants, typed block helpers, and writers
-- `@rootzero/contracts/Utils.sol` - IDs, assets, accounts, layout, and value helpers
-- `@rootzero/contracts/Events.sol` - reusable event emitters and event contracts
+Scaffold a ready-to-run Hardhat project, or add the library to an existing
+one:
 
-## Block Wire Format
+```bash
+npx create-rootzero@latest my-app
+# or
+npm install @rootzero/contracts
+```
+
+A minimal host composes the base `Host` with the endpoints it needs and
+implements their policy hooks:
 
-All request and response data is encoded as a binary block stream. Each block is:
+```solidity
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
 
+import { Host, Balances } from "@rootzero/contracts/Core.sol";
+import { Deposit } from "@rootzero/contracts/Endpoints.sol";
+import { Assets } from "@rootzero/contracts/Utils.sol";
+
+contract ExampleHost is Host, Balances, Deposit {
+    constructor(address rootzero) Host(rootzero) {}
+
+    function deposit(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal override {
+        uint balance = creditTo(account, Assets.slot(asset, meta), amount);
+        emit Balance(account, asset, meta, balance, int(amount), depositId);
+    }
+}
 ```
-[bytes4 key][bytes4 payloadLen][payload]
+
+Deploy it with your own address as commander and you can call its commands
+directly. A request is a run of binary blocks — here, a single `#amount` block
+asking to deposit an asset (the encoders are a few lines each; see
+[`test/helpers/blocks.ts`](test/helpers/blocks.ts) for reference
+implementations):
+
+```ts
+const host = await ethers.deployContract("ExampleHost", [deployer.address]);
+
+const account = encodeUserAccount(user.address); // receiving account
+const request = encodeAmountBlock(asset, meta, 100n); // what to deposit
+await host.deposit({ account, state: "0x", request }); // emits Balance
 ```
 
-`key` is `bytes4(keccak256("#name"))`; see `Keys` for the full set and [`docs/Schema.md`](docs/Schema.md) for the schema format. `Cursors` parses calldata streams zero-copy via the `Cur` struct; `Writers` builds response streams into pre-allocated memory.
+The rest of this guide explains the ideas this example leans on — blocks, IDs,
+hosts, commands — and the surfaces built on top of them.
 
-## Schemas, Forms, And State
+## Blocks
 
-Protocol blocks use schema strings and four-byte keys:
+Every request, response, and piece of in-flight state is a stream of typed
+blocks. A block is a four-byte key, a four-byte big-endian length, and a
+payload:
 
-- `Schemas` describes semantic protocol blocks such as `#amount`, `#balance`, `#custody`, and `#relay`.
-- `Forms` describes reusable structural blocks such as `#accountAsset` and `#accountAmount`, mostly used by queries.
-- `Keys` contains the runtime `bytes4` keys derived from block names.
+```txt
+[bytes4 key][uint32 payloadLen][payload]
+```
 
-Every command declares its input and output pipeline state with block keys in the `Command` event. Use `Keys.Empty` when a command expects or returns no state.
+The key is `bytes4(keccak256("#name"))`, and the payload layout is described by
+a schema string. For example, the block that requests a deposit:
 
-The active command pipeline state is intentionally narrow: `BALANCE` and `CUSTODY` blocks are live value owned by the active account while execution is in-flight. `TRANSACTION` remains a block type for settlement messages, but it is not command pipeline state.
+```txt
+#amount { bytes32 asset, bytes32 meta, uint amount }
+```
 
-## Typical Usage
+is 104 bytes on the wire: an 8-byte header followed by three big-endian 32-byte
+fields. There is no ABI encoding and no chain-specific type anywhere in the
+format — field types are chain-neutral integers, bytes, and booleans. A deposit
+request built for an EVM host is byte-for-byte the request a CosmWasm or Solana
+port would parse; what differs per chain is how a host *resolves* the
+identifiers inside, never how the bytes are laid out.
+
+Schemas can express more than flat fields: a block may end in nested child
+blocks (`#bytes as payload` names a run of raw dynamic bytes), items can be
+marked `maybe` (optional) or `many` (a list), and aliases and dotted field
+paths give off-chain tooling presentation names without changing a single byte
+on the wire. The full schema language is specified in
+[`docs/Schema.md`](docs/Schema.md). The standard block schemas live in
+`Schemas` and their runtime keys in `Keys` (both via
+`@rootzero/contracts/Cursors.sol`).
+
+## Batches
+
+A request is not a single struct; it is a run of blocks. One `#amount` block
+asks for one deposit, five blocks ask for five, and the code path is identical
+— every endpoint parses with a cursor and loops until the stream is exhausted.
+The first item of a schema (the *prime item*) is the one that may repeat;
+later top-level items, if any, apply to the whole batch.
+
+Off-chain, building a batch is concatenation. Using the reference encoders from
+[`test/helpers/blocks.ts`](test/helpers/blocks.ts):
+
+```ts
+import { concat } from "ethers";
+import { encodeAmountBlock } from "./helpers/blocks";
+
+const request = concat([
+  encodeAmountBlock(usdc, meta, 250_000_000n),
+  encodeAmountBlock(dai, meta, 250n * 10n ** 18n),
+]);
+// deposit(request) returns two #balance blocks, one per #amount
+```
 
-### Build a Host
+Everything downstream keeps this shape: commands loop over request blocks,
+settlement loops over transactions, pipelines loop over steps. Batching is
+never a special case.
 
-Extend `Host` when you want a rootzero host contract with admin command support and optional discovery registration.
+## IDs, Accounts, and Assets
 
-```solidity
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
+Everything the protocol touches — accounts, assets, chains, hosts, endpoints —
+is identified by a self-describing 256-bit ID:
 
-import { Host } from "@rootzero/contracts/Core.sol";
+```txt
+[uint32 type][uint32 chainid][192-bit payload]
+```
 
-contract ExampleHost is Host {
-    constructor(address rootzero)
-        Host(rootzero, 1, "example")
-    {}
-}
+where `type` packs `[vm][width][category][subtype]`. Any ID therefore announces
+what it is (an account, an asset, a node) and which chain it lives on, and the
+payload usually embeds the underlying address. User accounts are
+chain-agnostic; admin and guardian accounts are chain-local. Assets cover the
+native coin, ERC-20, ERC-721, and ERC-1155; wide identities carry a second
+`meta` word (an ERC-721 token id, for example). Nodes are hosts, commands,
+peers, queries, and guards.
+
+The `Utils.sol` entry point provides the constructors and inspectors:
+
+```solidity
+bytes32 account = Accounts.toUser(msg.sender); // chain-agnostic user account
+bytes32 asset = Assets.toErc20(tokenAddress);  // ERC-20 asset ID
+uint hostId = Ids.toHost(address(this));       // host node ID
 ```
 
-`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.
+## Hosts
 
-### Build a Command
+A host is one contract assembled from mixins. The base `Host` brings access
+control and the admin surface (authorize, unauthorize, appoint, dismiss,
+label, executePayable) plus the guardian `revoke` action; you add the
+endpoints you need and the policy hooks they require. Keeping a ledger is
+optional: the `Balances` mixin provides one, but a host can just as well
+implement commands that hold no persistent state in the host at all —
+forwarding funds elsewhere, or operating only on the state threaded through a
+pipeline.
 
-Extend `CommandBase` to define a command mixin that runs inside the protocol's trusted call model. Commands are abstract contracts mixed into a host.
+Trust is explicit and minimal. Each host has an immutable **commander**
+address fixed at construction, from which its **admin account** is derived.
+Other contracts become callers only when their node ID is authorized into the
+host's trusted set, and **guardians** are accounts allowed to take protective
+actions. At deployment, a host introduces itself to its commander, which is how
+host topology becomes discoverable.
 
-```solidity
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
+The `ExampleHost` in the quick start shows the resulting split, and it runs
+through the whole library: mixins implement the protocol mechanics (parsing,
+batching, discovery events), and small virtual hooks let the host decide
+policy — where funds come from, how the ledger is keyed, what gets emitted.
 
-import { CommandBase, CommandContext, Keys } from "@rootzero/contracts/Endpoints.sol";
-import { Cursors, Cur, Schemas, Writer, Writers } from "@rootzero/contracts/Cursors.sol";
+## Commands
 
-using Cursors for Cur;
-using Writers for Writer;
+Commands are the write endpoints. Every command receives the same context:
 
-string constant NAME = "myCommand";
+```solidity
+struct CommandContext {
+    bytes32 account; // acting account
+    bytes state;     // block stream produced by the previous command
+    bytes request;   // block stream for this invocation
+}
+```
 
-abstract contract ExampleCommand is CommandBase {
-    uint internal immutable myCommandId = commandId(NAME);
+The request carries instructions; the state carries live value. While a
+sequence of commands executes, `#balance` and `#custody` blocks in the state
+are the funds being moved — produced by one command, consumed by the next.
 
-    constructor() {
-        emit Command(host, myCommandId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false, false);
+The standard `Deposit` mixin shows the canonical shape — init a cursor, loop
+the batch, call the hook, write the output run:
+
+```solidity
+function deposit(CommandContext calldata c) external onlyCommand returns (bytes memory) {
+    (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+    Writer memory writer = Writers.allocBalances(groups);
+
+    while (request.i < request.len) {
+        (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
+        deposit(c.account, asset, meta, amount); // host policy hook
+        writer.appendBalance(asset, meta, amount);
     }
 
-    function myCommand(
-        CommandContext calldata c
-    ) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
-        Writer memory writer = Writers.allocBalances(groups);
+    request.complete();
+    return writer.finish();
+}
+```
+
+A command announces itself when the host is deployed. Its constructor emits a
+discovery event carrying the request schema, the expected and produced state
+block keys, and a shape string (`"1:0:1"` = one request block per operation, no
+input state, one output block per operation), plus a human-readable label:
 
-        while (request.i < request.len) {
-            (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
-            writer.appendBalance(asset, meta, amount);
-        }
+```solidity
+abstract contract MyCommand is CommandBase {
+    uint internal immutable myCommandId = commandId(this.myCommand.selector);
 
-        request.complete();
-        return writer.finish();
+    constructor() {
+        emit Command(host, myCommandId, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false);
+        emit Labeled(myCommandId, bytes32(0), "myCommand");
+    }
+
+    function myCommand(CommandContext calldata c) external onlyCommand returns (bytes memory) {
+        // parse c.request, loop, return the output state run
     }
 }
 ```
 
-## Repo Layout
+The standard commands cover the common ledger movements: `deposit` and
+`depositPayable` (external funds in), `withdraw` and `burn` (funds out),
+`debitAccount` and `creditAccount` (internal movements), `payout` (deliver
+state to other accounts), `provision` (allocate custody on another host), and
+`relayPayable` (hand a pipeline to another chain).
 
-- `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/guards` - guard action surfaces for delegated protection flows
-- `contracts/queries` - read-only query endpoints for protocol state
-- `contracts/blocks` - block stream schema (`Schema`), cursor parsing (`Cursors`), and writers (`Writers`)
-- `contracts/utils` - shared encoding helpers: IDs, assets, accounts, layout, ECDSA
-- `contracts/events` - protocol event contracts and emitters
-- `docs` - introductory documentation
+## Pipelines
 
-## Install and Compile
+A single command is rarely the whole story. A pipeline is a run of `#step`
+blocks executed in order within one transaction:
 
-```bash
-npm install @rootzero/contracts
-npm run compile
+```txt
+#step { uint target, uint resources, #bytes as request }
+```
+
+Each step names a target command, the resources it may spend, and its request.
+The state threads through: whatever one command returns becomes the input
+state of the next, and the final state must be empty — value cannot be left
+dangling at the end of a pipeline. This is the core of `Pipeline.pipe`:
+
+```solidity
+while (input.i < input.len) {
+    (uint target, uint resources, bytes calldata request) = input.unpackStep();
+    state = dispatch(target, account, state, request, useValue(budget, resources));
+}
+if (state.length != 0) revert UnexpectedState();
 ```
 
-## When To Use This Repo
+A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
+`#amount` request into `#balance` state, and `payout` consumes that state
+toward a recipient. Because a pipeline is just blocks, it is also the unit of
+command batching — and `resources` is a chain-typed word (on EVM, the low 128
+bits are native value in wei, drawn from a shared budget), so the same pipeline
+bytes are meaningful to every port.
+
+## Queries
 
-Use `rootzero` if you want to:
+Queries are the read endpoints: view functions that take a block-stream request
+and return a block-stream response, with the same batch shape as commands. The
+standard `getBalances` query takes a run of positions and answers each one in
+order:
 
-- 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
+```txt
+request:  #accountAsset { bytes32 account, bytes32 asset, bytes32 meta }
+response: #accountAmount { bytes32 account, bytes32 asset, bytes32 meta, uint amount }
+```
 
-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.
+Like commands, every query announces its request and response schemas at
+deployment, so tooling knows how to call it without artifacts.
+
+## Peers
+
+Peers are the host-to-host surfaces, callable only by trusted hosts. The two
+central ones are batches all the way down:
+
+- `peerSettle` consumes `#transaction { bytes32 from, bytes32 to, bytes32 asset,
+  bytes32 meta, uint amount }` blocks, debiting `from` and crediting `to` per
+  block — how two hosts record settlement between their ledgers.
+- `peerPipePayable` consumes `#pipe` blocks, each carrying an account, an
+  initial state, and a run of steps — a complete pipeline delivered by another
+  host, executed locally with its own resource budget.
+
+This is also the cross-chain mechanism. `relayPayable` (or `peerDispatchPayable`)
+wraps a pipe and addresses it to a chain; a bridge adapter moves the **raw
+bytes**; the destination host parses them with the same cursor rules and runs
+the same pipeline loop. Nothing in the payload is EVM-specific — step targets
+are destination-local node IDs, and only the adapter boundary (native
+transfers, address resolution, signatures) is chain-specific. The parity rule
+for ports is strict: every chain's implementation must parse the same input
+bytes and produce the same output bytes for every endpoint.
+
+## Guards and Admin
+
+Admin commands use the regular command shape but are gated to the host's admin
+account: trust management (`authorize`, `unauthorize`), guardian management
+(`appoint`, `dismiss`), naming (`label`), asset gating (`allowAssets`,
+`denyAssets`, `allowance`), lifecycle (`init`, `destroy`), and raw calls
+(`executePayable`). Guards go the other way: direct actions guardians can take
+without any command context — the default is `revoke`, which lets a guardian
+drop a trusted node immediately.
+
+## Events and Discovery
+
+Hosts are self-describing. At deployment a host emits the ABI of every event it
+uses (`EventAbi`), a discovery event per endpoint with its full schemas, and
+labels for human-readable names. State changes then follow evented
+conventions: `Balance` for every ledger change and flow events (`Transfer`,
+`Received`, `Spent`) for value movement, each tagged with the endpoint that
+caused it. An indexer can reconstruct the entire repository — endpoints,
+names, access sets, balances — from logs alone, with no artifact files.
+
+## Using the Library
+
+Import from the package entry points rather than deep paths:
+
+- `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
+  `Pipeline`, validator
+- `@rootzero/contracts/Endpoints.sol` — command, admin, peer, guard, and query
+  mixins and their hooks
+- `@rootzero/contracts/Cursors.sol` — `Cur` cursor reader, `Writers`, `Schemas`,
+  `Keys`
+- `@rootzero/contracts/Utils.sol` — `Ids`, `Assets`, `Accounts`, layout and
+  value helpers
+- `@rootzero/contracts/Events.sol` — protocol event contracts
+
+Repo layout:
+
+- `contracts/core` — host, access control, balances, pipeline, validation
+- `contracts/commands` — standard commands and admin commands
+- `contracts/peer` — peer surfaces for inter-host and cross-chain flows
+- `contracts/guards` — guardian direct actions
+- `contracts/queries` — read-only query endpoints
+- `contracts/blocks` — block schema, cursor parsing, writers
+- `contracts/utils` — IDs, assets, accounts, layout, ECDSA
+- `contracts/events` — event contracts and emitters
+- `docs` — [`Schema.md`](docs/Schema.md) (wire format and schema DSL)
+
+Use this library to create a new rootzero host, implement a command, or reuse
+the protocol's block format in tooling. It is the shared protocol foundation,
+not an end-user application.

package/blocks/Cursors.sol

@@ -70,41 +70,37 @@ library Cursors {
         return open(source[i:]);
     }
 
-    /// @notice Create a cursor over `source[i:]` and restrict it to its first grouped run.
-    /// Equivalent to `open(source, i)`, reading the current key, then `run(key, group)`.
-    /// @param source Calldata slice that forms the parent block stream.
-    /// @param i Start byte offset within `source`.
+    /// @notice Create a cursor over `source` and restrict it to its first grouped run.
+    /// Equivalent to `open(source)`, reading the current key, then `run(key, group)`.
+    /// @param source Calldata slice that forms the block stream.
     /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
-    /// @return cur Cursor with `len` truncated to the end of the first run in `source[i:]`.
+    /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
     /// @return groups Number of block groups in the run (`block count / group`).
     /// @return next Byte offset immediately after the run, relative to `source`.
     function init(
         bytes calldata source,
-        uint i,
         uint group
     ) internal pure returns (Cur memory cur, uint groups, uint next) {
-        cur = open(source, i);
+        cur = open(source);
         if (cur.i == cur.len) revert ZeroCursor();
         (bytes4 key, ) = cur.peek(cur.i);
         groups = cur.run(key, group);
-        next = i + cur.len;
+        next = cur.len;
     }
 
-    /// @notice Create a cursor over `source[i:]`, restrict it to its first grouped run, and require an exact group count.
-    /// @param source Calldata slice that forms the parent block stream.
-    /// @param i Start byte offset within `source`.
+    /// @notice Create a cursor over `source`, restrict it to its first grouped run, and require an exact group count.
+    /// @param source Calldata slice that forms the block stream.
     /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
     /// @param expectedGroups Required number of groups in the run.
-    /// @return cur Cursor with `len` truncated to the end of the first run in `source[i:]`.
+    /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
     /// @return next Byte offset immediately after the run, relative to `source`.
     function init(
         bytes calldata source,
-        uint i,
         uint group,
         uint expectedGroups
     ) internal pure returns (Cur memory cur, uint next) {
         uint groups;
-        (cur, groups, next) = init(source, i, group);
+        (cur, groups, next) = init(source, group);
         if (groups != expectedGroups) revert BadRatio();
     }
 
@@ -489,6 +485,13 @@ library Cursors {
         return createBlock(Keys.Bytes, data);
     }
 
+    /// @notice Encode a STRING block with a UTF-8 payload.
+    /// @param data String payload.
+    /// @return Encoded STRING block bytes.
+    function toStringBlock(string memory data) internal pure returns (bytes memory) {
+        return createBlock(Keys.String, bytes(data));
+    }
+
     /// @notice Encode a BOUNTY block.
     /// @param bounty Relayer reward amount.
     /// @param relayer Relayer account identifier.
@@ -610,6 +613,18 @@ library Cursors {
         cur.i += 4;
     }
 
+    /// @notice Read the next 8 bytes from the cursor and advance by 8 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 8 bytes.
+    /// @return value Loaded bytes8 value.
+    function read8(Cur memory cur) internal pure returns (bytes8 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 8;
+    }
+
     /// @notice Read the next 16 bytes from the cursor and advance by 16 bytes.
     /// @dev Performs no bounds, key, length, or cursor checks.
     /// @param cur Cursor whose current position is advanced by 16 bytes.
@@ -708,6 +723,26 @@ library Cursors {
         return unpackRaw(cur, Keys.Bytes);
     }
 
+    /// @notice Consume a reserved STRING block and return its UTF-8 payload.
+    /// @param cur Cursor; advanced past the STRING block.
+    /// @return data Decoded STRING payload.
+    function unpackString(Cur memory cur) internal pure returns (string memory data) {
+        return string(unpackRaw(cur, Keys.String));
+    }
+
+    /// @notice Consume a LABEL block and return its fields.
+    /// @param cur Cursor; advanced past the LABEL block.
+    /// @return id Node ID being labelled.
+    /// @return namespace Label namespace.
+    /// @return name Label value.
+    function unpackLabel(Cur memory cur) internal pure returns (uint id, bytes32 namespace, string memory name) {
+        uint end = cur.enter(Keys.Label, 64 + Sizes.Header, 0);
+        id = cur.readUint();
+        namespace = cur.read32();
+        name = cur.unpackString();
+        cur.exit(end);
+    }
+
     /// @notice Consume a dynamic block with a single bytes32 payload.
     /// @param cur Cursor; advanced past the block.
     /// @param key Expected dynamic block key.

package/blocks/Keys.sol

@@ -33,6 +33,8 @@ library Keys {
     bytes4 constant Evm = bytes4(keccak256("#evm"));
     /// @dev Reserved raw bytes child block.
     bytes4 constant Bytes = bytes4(keccak256("#bytes"));
+    /// @dev Reserved UTF-8 string child block.
+    bytes4 constant String = bytes4(keccak256("#string"));
     /// @dev Account identifier - (bytes32 account)
     bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)
@@ -57,6 +59,8 @@ library Keys {
     bytes4 constant Node = bytes4(keccak256("#node"));
     /// @dev Relayer bounty - (uint amount, bytes32 relayer)
     bytes4 constant Bounty = bytes4(keccak256("#bounty"));
+    /// @dev Mutable node label - (uint id, bytes32 namespace, #string as name)
+    bytes4 constant Label = bytes4(keccak256("#label"));
 
     /// @dev Structural status form - (uint code)
     bytes4 constant Status = bytes4(keccak256("#status"));