@rootzero/contracts 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -3,21 +3,89 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.14.0
+
+### Breaking Changes
+
+- Replaced `CommandContext` and the separate payable value lifecycle with the
+  unified `Execution` context. Endpoint and command implementations now open an
+  execution directly from calldata, use its packed decoder and writer lanes,
+  and finish through the shared `close` helpers.
+- Reworked the block codec around absolute-position `Blocks` primitives,
+  packed `Cursors`, cursor-backed `Decoders`, lazy `Buffers`, and thin
+  `Writers`. Several low-level cursor and writer APIs were renamed or removed.
+- Redefined block specs and endpoint descriptors. Specs now encode key, minimum,
+  maximum, allocation hint, stride, and optional LIST container metadata;
+  descriptors use normalized lane specs and include a transaction stride.
+- Replaced the `Cursors.sol` package entry point with `Codec.sol`, added the
+  command-authoring `Commands.sol` entry point, and reorganized exports across
+  the package barrels.
+- Endpoint selectors are now derived from endpoint names. The configured name
+  must match the implementing function name, and descriptor values are
+  represented as `uint` throughout.
+- Removed the AUTH and BOUNTY codec blocks, the obsolete `Payable`/`Values`
+  helpers, and superseded decoder, writer, schema, and descriptor overloads.
+
+### Added
+
+- Added packed output and transaction writer lanes to `Execution`, including
+  semantic output helpers, queued credit/debit transactions, budget refunds,
+  and direct transaction finalization.
+- Added detachable `Budget` values for pipeline-style consumers, shared lane
+  identifiers, spec-driven writer allocation, and optimized semantic block
+  readers, writers, and composite unpackers.
+- Added a transaction-output example, command and codec barrel import examples,
+  and expanded coverage for packed cursors, buffers, descriptors, budgets,
+  execution output, and command flows.
+
+### Changed
+
+- Standardized command, query, guard, and port implementations on the same
+  execution open/close lifecycle and renamed request terminology to input.
+- Expanded NatSpec across the new execution and codec APIs and refreshed the
+  protocol, schema, indexing, and multi-chain documentation.
+
+## 1.13.0
+
+### Breaking Changes
+
+- Replaced the virtual `Pipeline.settle(bytes transactions)` stream hook with
+  decoded settlement through `Settlement`. Pipeline implementations now provide
+  `debitAccount` and `creditAccount` hooks, while the pipeline decodes each
+  returned TRANSACTION block and settles it before dispatching the next step.
+- Moved `DebitAccountHook` and `CreditAccountHook` from their command modules to
+  `core/Settlement.sol`. They remain available from the `Core.sol` and
+  `Endpoints.sol` package entry points.
+
+### Added
+
+- Added the memory-backed `Reader` and `Readers` block-stream API with balance
+  and transaction unpackers, bounds and block validation, and positive
+  iteration through `more()`.
+- Added the shared `Settlement` core mixin used by pipelines and `PortSettle` to
+  debit transaction sources and credit destinations.
+
+### Changed
+
+- Unified pipeline and port transaction handling through `Settlement`,
+  including zero-account handling and zero-amount no-op settlement.
+
 ## 1.12.0
 
 ### Breaking Changes
 
-- Removed the generic `EndpointBase.schema(...)` helper. Use
-  `localSchema(...)` for context-local endpoint schemas or emit `Schema`
-  directly for custom/named keys.
+- Removed `Keys.Local` and replaced `EndpointBase.localSchema(...)` with the
+  explicit `EndpointBase.schema(uint32 key, string body)` helper for
+  context-local endpoint schemas.
+- Changed `Introduction` to emit the receiving `host` and introduced `peer`:
+  `Introduction(uint indexed host, uint peer, uint blocknum)`.
 - Replaced `isDebitAccount`, `isCreditAccount`, `isAuthorize`, and
   `isUnauthorize` helper predicates with internal command ID fields:
   `debitAccountId`, `creditAccountId`, `authorizeId`, and `unauthorizeId`.
 
 ### Added
 
-- Added `Keys.Local` as the default context-local block key and added
-  `EndpointBase.localSchema(...)` helpers for publishing local endpoint
+- Added the `EndpointBase.schema(...)` helper for publishing local endpoint
   schemas.
 - Added the standard `#schema` block, `unpackSchema`, and an opt-in
   `publishSchema` admin command for emitting schema claims from `#schema`
@@ -62,7 +130,7 @@ breaking API changes. Breaking changes are called out explicitly.
 - Portal no longer emits `Recovered` when retrying an undelivered witness.
 - Renamed `Cursors.exit` to `ensureAt` and renamed its position argument to
   `pos`.
-- Removed the redundant `next` return value from both `Cursors.init` overloads;
+- Removed the redundant `next` return value from both `Decoders.init` overloads;
   callers should use the returned cursor's `len` as the run boundary.
 - Changed `Cursors.list` to require the expected current cursor position as
   `pos` before entering the LIST block.
@@ -137,7 +205,7 @@ breaking API changes. Breaking changes are called out explicitly.
   as the discovery/event surface for dispatch tracking.
 - Added `ContextRecovery` schema/cursor support and context schema aliases for
   reusable nested block schemas.
-- Added `Values.drain`, `Payable.openValue`, and `Payable.closeValue` to make
+- Added `Values.drain`, `Payable.openValue`, and `Payable.end` to make
   payable command budget lifecycles explicit.
 
 ## 1.6.0
@@ -197,7 +265,7 @@ breaking API changes. Breaking changes are called out explicitly.
 
 ### 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)`.
+- Simplified `Decoders.init` to parse a single run from the start of a calldata slice. Callers that previously passed an offset must slice first or use `Decoders.open(source, i)`.
 - Tightened command, query, and peer request parsing around the single-run convention used by current protocol endpoints.
 
 ### Added

package/Codec.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+// Aggregator: re-exports the complete block encoding and decoding surface.
+// Import this file for low-level codec extensions and direct stream processing.
+
+import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
+import { Keys } from "./codec/Keys.sol";
+import { Sizes, Specs } from "./codec/Specs.sol";
+import { Descriptors } from "./codec/Descriptors.sol";
+import { Schemas } from "./codec/Schema.sol";
+import { Decoders } from "./codec/Decoders.sol";
+import { Cursors, Cur } from "./utils/Cursors.sol";
+import { Readers, Reader } from "./codec/Readers.sol";
+import { Blocks } from "./codec/Blocks.sol";
+import { Buffers } from "./codec/Buffers.sol";
+import { Writer, Writers } from "./codec/Writers.sol";
+
+
+
+

package/Commands.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+// Aggregator: re-exports the types and helpers needed to author commands.
+// Import this file for both standard Execution-based commands and custom decoders.
+
+import {CommandBase} from "./commands/Base.sol";
+import {Execution, Executions} from "./execution/Execution.sol";
+import {Lanes} from "./utils/Lanes.sol";
+import {Blocks} from "./codec/Blocks.sol";
+import {Sizes, Specs} from "./codec/Specs.sol";
+import {Decoders} from "./codec/Decoders.sol";
+import {Cursors, Cur} from "./utils/Cursors.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx} from "./core/Types.sol";

package/Core.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports the core host, runtime, access, ledger, node-call, and validation layer.
+// Aggregator: re-exports the core host, runtime, access, ledger, settlement, pipeline, node-call, and validation layer.
 // Import this file to bring the full rootzero host base layer into scope.
 
 import { AccessControl } from "./core/Access.sol";
@@ -10,11 +10,11 @@ import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Host, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls } from "./core/Calls.sol";
-import { EndpointBase, Lane } from "./core/Endpoint.sol";
-import { Payable } from "./core/Payable.sol";
+import { EndpointBase } from "./core/Endpoint.sol";
 import { Pipeline } from "./core/Pipeline.sol";
+import { Budget, Budgets } from "./execution/Budget.sol";
+import { CreditAccountHook, DebitAccountHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
-import { RecoverHook } from "./commands/Recover.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 

package/Endpoints.sol

@@ -4,16 +4,14 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports command, admin, port, guard, and query endpoint abstractions.
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
-// Shared helpers
-import { Keys } from "./blocks/Keys.sol";
-import { CommandBase, CommandContext } from "./commands/Base.sol";
-import { EndpointBase, Lane } from "./core/Endpoint.sol";
-import { Payable } from "./core/Payable.sol";
+// Shared endpoint hooks
+import { CreditAccountHook, DebitAccountHook } from "./core/Settlement.sol";
 
 // Commands
+import { Allocate, AllocateHook } from "./commands/Allocate.sol";
 import { Burn, BurnHook } from "./commands/Burn.sol";
-import { CreditAccount, CreditAccountHook } from "./commands/Credit.sol";
-import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
+import { CreditAccount } from "./commands/Credit.sol";
+import { DebitAccount } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";

package/README.md

@@ -10,7 +10,7 @@ of the protocol: the base contracts, block codecs, and helpers that rootzero
 applications compose.
 
 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
+boundary is encoded in one binary block format, so a input 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
@@ -48,7 +48,7 @@ contract ExampleHost is Host, Balances, Deposit {
 ```
 
 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
+directly. A input 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):
@@ -57,8 +57,8 @@ implementations):
 const host = await ethers.deployContract("ExampleHost", [deployer.address]);
 
 const account = encodeUserAccount(user.address); // receiving account
-const request = encodeAmountBlock(asset, 100n); // what to deposit
-await host.deposit({ account, state: "0x", input: request }); // emits Balance
+const input = encodeAmountBlock(asset, 100n); // what to deposit
+await host.deposit({ account, state: "0x", input: input }); // emits Balance
 ```
 
 The rest of this guide explains the ideas this example leans on — blocks, IDs,
@@ -66,7 +66,7 @@ hosts, commands — and the surfaces built on top of them.
 
 ## Blocks
 
-Every request, response, and piece of in-flight state is a stream of typed
+Every input, 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:
 
@@ -85,7 +85,7 @@ amount { bytes32 asset, uint amount }
 is 72 bytes on the wire: an 8-byte header followed by two 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
+input built for an EVM host is byte-for-byte the input 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.
 
@@ -96,11 +96,11 @@ 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`).
+`@rootzero/contracts/Codec.sol`).
 
 ## Batches
 
-A request is not a single struct; it is a run of blocks. One `#amount` block
+A input 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 descriptor lane key is the prime item: it is the block type that may repeat
@@ -117,14 +117,15 @@ Off-chain, building a batch is concatenation. Using the reference encoders from
 import { concat } from "ethers";
 import { encodeAmountBlock } from "./helpers/blocks";
 
-const request = concat([
+const input = concat([
   encodeAmountBlock(usdc, 250_000_000n),
   encodeAmountBlock(dai, 250n * 10n ** 18n),
 ]);
-// deposit(request) returns two #balance blocks, one per #amount
+// deposit(input) returns two #balance blocks in its state output and an
+// empty transaction output
 ```
 
-Everything downstream keeps this shape: commands loop over request blocks,
+Everything downstream keeps this shape: commands loop over input blocks,
 settlement loops over transactions, pipelines loop over steps. Batching is
 never a special case.
 
@@ -216,6 +217,11 @@ struct CommandContext {
 }
 ```
 
+Every command returns two block streams: `state`, which is threaded into the
+next pipeline step, and `transactions`, which contains `#transaction` blocks
+for the pipeline host to settle outside the state lane. Either stream may be
+empty.
+
 The input 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.
@@ -224,7 +230,9 @@ The standard `Deposit` mixin shows the canonical shape — open the input,
 loop the batch, call the hook, write the output run:
 
 ```solidity
-function deposit(CommandContext calldata c) external onlyCommand returns (bytes memory) {
+function deposit(
+    CommandContext calldata c
+) external onlyCommand returns (bytes memory, bytes memory) {
     (Cur memory input, uint outputs) = openInput(c.input, descriptor);
     Writer memory output = Writers.allocBalances(outputs);
 
@@ -234,7 +242,7 @@ function deposit(CommandContext calldata c) external onlyCommand returns (bytes
         output.appendBalance(asset, amount);
     }
 
-    return output.finish();
+    return (end(output), "");
 }
 ```
 
@@ -244,14 +252,18 @@ lanes, derived group sizes, and flags, plus a human-readable label:
 
 ```solidity
 abstract contract MyCommand is CommandBase {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("myCommand", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
+        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
     }
 
-    function myCommand(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        // parse c.input, loop, return the output state run
+    function myCommand(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        // parse input, loop, return the output state run and any transactions
     }
 }
 ```
@@ -259,8 +271,9 @@ abstract contract MyCommand is CommandBase {
 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 portal).
+state to other accounts), `allocate` (turn balance state into custody),
+`provision` (provision custody from an external allocation), and `relayPayable`
+(hand a pipeline to another portal).
 
 ## Pipelines
 
@@ -268,24 +281,36 @@ A single command is rarely the whole story. A pipeline is a run of `#step`
 blocks executed in order within one transaction:
 
 ```txt
-step { uint target, uint resources, #bytes as request }
+step { uint cmd, uint resources, #bytes as input }
 ```
 
-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. This is the core of
-`Pipeline.pipe`:
+Each step names a command, the resources it may spend, and its input.
+The returned state threads into the next command and the final state must be
+empty. Returned transactions do not enter the state lane; the pipeline passes
+each decoded transaction to the shared settlement implementation before
+running the next step. 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));
+while (cur.more()) {
+    (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
+    Reader memory transactions;
+    (state, transactions.source) = dispatch(
+        cmd,
+        account,
+        state,
+        input,
+        budget.use(resources)
+    );
+    while (transactions.more()) {
+        (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
+        settle(from, to, asset, amount);
+    }
 }
 if (state.length != 0) revert UnexpectedState();
 ```
 
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
-`#amount` request into `#balance` state, and `payout` consumes that state
+`#amount` input 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-specific word interpreted by the
 portal adapter (on EVM, the low 128 bits are native value in wei, drawn from a
@@ -293,13 +318,13 @@ shared budget), so the same pipeline bytes are meaningful to every port.
 
 ## Queries
 
-Queries are the read endpoints: view functions that take a block-stream request
+Queries are the read endpoints: view functions that take a block-stream input
 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:
 
 ```txt
-request:  accountAsset { bytes32 account, bytes32 asset }
+input:  accountAsset { bytes32 account, bytes32 asset }
 response: accountAmount { bytes32 account, bytes32 asset, uint amount }
 ```
 
@@ -322,8 +347,8 @@ This is also the cross-portal mechanism. `relayPayable` (or `portDispatchPayable
 wraps a pipe and addresses it to a portal, commonly the destination host ID;
 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
+the same pipeline loop. Nothing in the payload is EVM-specific — step commands
+are destination-local command 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.
@@ -353,11 +378,13 @@ names, access sets, balances — from logs alone, with no artifact files.
 Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
-  `Pipeline`, `Portal`, validator
+  `Settlement`, `Pipeline`, `Portal`, validator
+- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, codec
+  helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
   mixins and their hooks
-- `@rootzero/contracts/Cursors.sol` — `Cur` cursor reader, `Writers`, `Schemas`,
-  `Keys`
+- `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
+  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`, and `Specs`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts

package/Utils.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Nodes, Selectors, Layout, Utils, Value).
+// Aggregator: re-exports protocol identifier, asset, account, cryptographic,
+// layout, and general-purpose utility helpers.
 // Import this file to access the full utility surface without managing individual paths.
 
-import { Keys } from "./blocks/Keys.sol";
 import { Accounts } from "./utils/Accounts.sol";
 import { Actions } from "./utils/Actions.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
@@ -13,9 +13,7 @@ import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
 import { Selectors } from "./utils/Selectors.sol";
 import { Layout } from "./utils/Layout.sol";
-import { Schemas } from "./blocks/Schema.sol";
 import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
-import { Budget, Values } from "./utils/Value.sol";