@rootzero/contracts 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 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
@@ -88,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.
@@ -163,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
@@ -223,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

@@ -10,12 +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,11 +4,7 @@ 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

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,15 +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 in its state output and an
+// 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.
 
@@ -242,7 +242,7 @@ function deposit(
         output.appendBalance(asset, amount);
     }
 
-    return (output.finish(), "");
+    return (end(output), "");
 }
 ```
 
@@ -252,16 +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
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        // parse c.input, loop, return the output state run and any transactions
+        // parse input, loop, return the output state run and any transactions
     }
 }
 ```
@@ -279,25 +281,25 @@ 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.
+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();
+while (cur.more()) {
+    (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
     Reader memory transactions;
     (state, transactions.source) = dispatch(
-        target,
+        cmd,
         account,
         state,
-        request,
-        useValue(budget, resources)
+        input,
+        budget.use(resources)
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
@@ -308,7 +310,7 @@ 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
@@ -316,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 }
 ```
 
@@ -345,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.
@@ -377,10 +379,12 @@ Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
   `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` — calldata `Cur`/`Cursors`, memory
-  `Reader`/`Readers`, `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";