@rootzero/contracts 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -8,6 +8,146 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.26.0
+
+### Breaking Changes
+
+- STEP blocks now encode `uint128 value` directly instead of a full-width
+  chain-specific `uint resources` word. The fixed STEP prefix is 16 bytes
+  smaller, and pipeline dispatch no longer truncates or interprets resource bits.
+- Commands now return `(bytes state, uint credit)` instead of separate state
+  and transaction block streams. Pipelines trust the scalar return and add it
+  to the shared value budget, allowing later commands to spend it before the
+  enclosing entrypoint settles the final budget once. Transaction blocks remain
+  available for explicit posting through ports.
+- Removed transaction writer metadata from endpoint descriptors and execution
+  writer lanes.
+- Removed descriptor checks, eager lane scans, group reconciliation, and the
+  expected batch argument from execution opening. State/input keys and strides
+  remain descriptor metadata; command decoding and loops define their runtime
+  semantics, while finalization rejects unread state or input bytes.
+- Removed the generic memory-backed `Reader` and `Readers` API from
+  `Codec.sol`. Fixed homogeneous memory streams now use absolute-position
+  `Memory` unpackers.
+- Removed `Decoders.wrap` and the scanning `Decoders.batch` constructor.
+  `Decoders.open` now wraps any calldata source without initial checks,
+  including empty sources; explicit decoding defines structure and cardinality.
+- Removed the unused `Cursors.pair`, `locate`, and `before` helpers. Cursor
+  pairs are packed directly where execution needs them.
+- Replaced the cross-chain-ambiguous `#budget` block with the command-specific
+  `#cashout { uint amount }` block.
+
+### Added
+
+- Added the standard
+  `#bootstrap { bytes32 asset, uint amount, uint budget }` input block and
+  `Bootstrap` command. It uses the standard `DebitAccountHook` for each initial
+  balance and a dedicated `BootstrapBudgetHook` for native-value contributions,
+  including zero contributions. `BootstrapInternal` provides direct local
+  pipeline dispatch without a self-call.
+- Added `Cashout`, its dedicated native-withdrawal hook, optimized
+  `CashoutInternal` dispatch, and the canonical `Actions.Cashout` annotation.
+  Added `Actions.Cashin` as its native-deposit counterpart.
+- Added `utils/Errors.sol` as the canonical declaration source for all
+  utility-layer errors, preserving their existing signatures and selectors.
+- Added hint-only `Blocks.runCount`, a minimal assembly scan that counts complete
+  consecutive keyed blocks without treating the result as structural validation.
+- Added `Executions.takeRawState` for forwarding an intact state lane while
+  marking it consumed.
+- Added symmetric `Executions.takeRawInput` for forwarding and consuming an
+  intact input lane.
+- Added `Decoders.close` to reject unread bytes explicitly. Execution `finish`
+  and `close` apply the same invariant automatically.
+- Added `Execution.close(extraCredit)` to combine trusted command-produced
+  credit with the execution's remaining value budget during finalization.
+- Added `Memory.bounds` and specialized `unpackBalance`, `unpackDebt`,
+  `unpackPosition`, and `unpackTransaction` helpers for fixed-stride memory
+  block streams.
+
+### Changed
+
+- Replaced the unused checked `Cursors.wrap(source, flags, tag)` with the
+  two-argument packed calldata wrapper used by generic decoders. Removed the
+  duplicate private execution `openDecoder` implementation.
+- Replaced the unused cursor item-count metadata with an optional one-byte
+  block stride. `Descriptors` now fully opens single or paired decoder cursors,
+  selects the active lane, derives the output allocation hint, and initializes
+  the writer cursor. Removed descriptor field accessors so packed layout
+  interpretation remains internal to the codec. Endpoint and command helpers
+  now construct `Execution` directly with the returned cursors and `msg.value`;
+  removed the descriptor-backed `Executions.open*` wrappers.
+- Execution output writers now derive their initial capacity from an optimized
+  hint-only scan of the selected low decoder lane and grow as needed. Output
+  strides and size hints no longer impose a hard precomputed batch capacity.
+- All buffers now grow beyond their initial capacity. Removed the `Growable`
+  cursor flag and the growth-policy booleans from buffer, writer, specification,
+  and descriptor allocation APIs.
+- `Execution` now stores its sole output writer as a direct untagged cursor;
+  output reservation and finalization no longer perform lane selection.
+- Execution traversal and unpack helpers now consume the active low decoder
+  lane without a lane argument. Mixed-lane commands select explicitly with
+  chainable `onstate()` and `oninput()` helpers. Paired executions use descriptor
+  metadata to place state low for state-only commands, which decode directly.
+  Relay commands select input explicitly before decoding their forwarded block.
+- `Execution.close()` now finalizes output and drains the remaining budget as
+  `(bytes output, uint credit)`; commands return it directly without the former
+  `CommandBase.closeCommand` wrapper. Budget draining is inlined in `close()`.
+- Internal debit processing now validates its fixed calldata stride once and
+  decodes each amount directly. Internal credit, settlement, repayment, and
+  pipeline transaction processing do the equivalent for memory streams.
+- Pipeline step value is now checked and deducted directly from the scalar
+  budget, avoiding the generic budget-helper call in the dispatch loop. The
+  loop now also traverses absolute calldata bounds and unpacks STEP blocks
+  directly without allocating a decoder cursor.
+- `Cursors` now performs packed construction, bounds, navigation, selection,
+  and consumption directly in each helper, avoiding nested internal-call
+  overhead across low-level decoding paths.
+- `Blocks.expectKey` and the specialized dynamic leaf unpackers now validate
+  their headers directly, reducing composite decoding overhead.
+- `Specs` and `Descriptors` now calculate hot-path counts and writer allocation
+  directly from their packed fields.
+- Buffer reservation/finalization, fixed-size writer reservation, and execution
+  opening/output paths now operate directly on validated packed cursors.
+
+## 1.25.0
+
+### Breaking Changes
+
+- Changed `Pipeline.pipe` to accept a scalar `uint` budget and return the
+  remaining scalar budget. The standalone mutable `Budget` type remains
+  available for other funded execution flows.
+- Split the pipeline hook from its standard implementation. `PipePayablePort`
+  now inherits only `PipeHook`; hosts that want the built-in pipeline must
+  compose `Pipeline` explicitly, while custom hosts may implement the hook
+  without inheriting the standard dispatch and posting implementation.
+- Changed `Decoders.open` to wrap the complete non-empty calldata source as an
+  ungrouped cursor. Code that needs the former counted first-homogeneous-run
+  behavior must use the new `Decoders.batch` helper.
+
+### Added
+
+- Added scalar `Budgets.useValue` and `Budgets.useResourceValue` overloads, and
+  `Executions.drainBudget` for transferring an execution budget as a `uint`.
+- Added `PipeHook` to the `Core.sol` and `Endpoints.sol` package barrels.
+- Added `Blocks.expectKey` and key-only `Decoders.consume` and
+  `Executions.consume` overloads for validating blocks whose payload shape is
+  established by specialized decoding logic.
+- Added `Blocks.require1`, `require2`, `require4`, `require8`, and `require16`,
+  completing the fixed-width validation family alongside `require32`.
+
+### Changed
+
+- Specialized built-in composite block unpackers to validate their known keys
+  directly instead of constructing and evaluating generic specifications.
+- Specialized fixed-width block validation, empty-block inspection, and
+  key-only `takeBlock` paths to avoid redundant specification and calldata
+  work.
+- Pipeline execution now validates the complete STEP source and rejects a
+  trailing block with a different key instead of silently stopping after the
+  first homogeneous run.
+- Simplified internal debit-account output allocation to use the fixed-width
+  input size directly.
+
 ## 1.24.0
 
 ### Breaking Changes

package/Codec.sol

@@ -11,8 +11,7 @@ import { Descriptors, Flags } 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 { Blocks, Memory } from "./codec/Blocks.sol";
 import { Buffers } from "./codec/Buffers.sol";
 import { Writer, Writers } from "./codec/Writers.sol";
 

package/Core.sol

@@ -14,7 +14,7 @@ import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Admins, CommandHost, Guardians, Host, HostIntroduction, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./core/Calls.sol";
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
-import { Pipeline } from "./core/Pipeline.sol";
+import { PipeHook, Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";
 import { CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";

package/Endpoints.sol

@@ -6,12 +6,15 @@ pragma solidity ^0.8.33;
 
 // Shared endpoint hooks
 import {Flags} from "./codec/Descriptors.sol";
+import {PipeHook} from "./core/Pipeline.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands
 import {CommandBase} from "./commands/Base.sol";
 import {Allocate, AllocateHook} from "./commands/Allocate.sol";
 import {Burn, BurnHook} from "./commands/Burn.sol";
+import {Bootstrap, BootstrapBudgetHook, BootstrapInternal} from "./commands/Bootstrap.sol";
+import {Cashout, CashoutHook, CashoutInternal} from "./commands/Cashout.sol";
 import {CreditAccount, CreditAccountInternal} from "./commands/Credit.sol";
 import {DebitAccount, DebitAccountInternal} from "./commands/Debit.sol";
 import {Deposit, DepositHook, DepositPayable, DepositPayableHook} from "./commands/Deposit.sol";

package/README.md

@@ -135,8 +135,8 @@ 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
-for batching. Readers interpret a zero group byte as group size 1 when the lane
-is non-empty.
+for batching. Descriptor decoding interprets a zero group byte as group size 1
+when the lane is non-empty.
 
 Off-chain, building a batch is concatenation. Using the reference encoders from
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts):
@@ -149,13 +149,12 @@ const input = concat([
   encodeAmountBlock(usdc, 250_000_000n),
   encodeAmountBlock(dai, 250n * 10n ** 18n),
 ]);
-// deposit(input) returns two #balance blocks in its state output and an
-// empty transaction output
+// deposit(input) returns two #balance blocks and zero native budget credit
 ```
 
 Everything downstream keeps this shape: commands loop over input blocks,
-posting loops over transactions, pipelines loop over steps. Batching is
-never a special case.
+posting ports loop over transactions, and pipelines loop over steps. Batching
+is never a special case.
 
 ## IDs, Accounts, Assets, and Nodes
 
@@ -254,17 +253,19 @@ 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 post outside the state lane. Either stream may be
-empty.
+Every command returns a `state` block stream and a trusted native `credit`.
+State is threaded into the next pipeline step, while credit replenishes the
+shared pipeline budget without validation against forwarded call value.
+Command trust is the authority boundary.
 
 State is linear, not optional ambient context. A command is responsible for
 the entire state stream it receives: it must validate and consume it, transform
 and return it, forward it intact, or revert. A command must never succeed while
-silently ignoring or dropping supplied state. Commands that declare
-`Specs.Empty` state therefore reject any non-empty state, while commands that
-accept state validate the complete stream against their declared state schema.
+silently ignoring or dropping supplied state. Descriptor schemas remain
+discovery metadata; the command's decoding and loop implementation defines its
+runtime lane semantics. A command that does not consume supplied state rejects
+it when closing, while `takeRawState` explicitly consumes an intact forwarded
+state lane.
 This is especially important for `#debt` and `#position`, because dropping
 either could silently discard an outstanding debt requirement.
 
@@ -285,22 +286,22 @@ claims, fees, netting, and other multi-step operations. Debt and position are
 transient representations and do not themselves create or erase an obligation
 recorded by an external system.
 
-The standard `Deposit` mixin shows the canonical shape: open and validate both
-command lanes, loop the batch, call the hook, and write the output run:
+The standard `Deposit` mixin shows the canonical shape: open the execution,
+decode its active input lane, call the hook, and write the output run:
 
 ```solidity
 function deposit(
     bytes calldata context
-) external onlyCommand returns (bytes memory, bytes memory) {
-    Execution memory exec = openCommand(context, descriptor, 0);
+) external onlyCommand returns (bytes memory, uint) {
+    Execution memory exec = openCommand(context, descriptor);
 
     while (exec.more()) {
-        (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+        (bytes32 asset, uint amount) = exec.unpackAmount();
         deposit(exec.account, asset, amount); // host policy hook
         exec.outputBalance(asset, amount);
     }
 
-    return closeCommand(exec);
+    return exec.close();
 }
 ```
 
@@ -313,19 +314,19 @@ abstract contract MyCommand is CommandBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, 0);
+        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0);
     }
 
     function myCommand(
         bytes calldata context
-    ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(context, descriptor, 0);
+    ) external onlyCommand returns (bytes memory, uint) {
+        Execution memory exec = openCommand(context, descriptor);
         while (exec.more()) {
-            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+            (bytes32 asset, uint amount) = exec.unpackAmount();
             // Apply command-specific behavior for this group.
             exec.outputBalance(asset, amount);
         }
-        return closeCommand(exec);
+        return exec.close();
     }
 }
 ```
@@ -336,7 +337,9 @@ or compose values such as `Flags.Funded`, `Flags.Admin`, and
 and 7 are reserved for endpoint-defined custom flags. Bits 2 through 5 remain
 reserved for future protocol flags.
 
-The standard commands cover the common ledger movements: `deposit` and
+The standard commands cover the common ledger movements: `bootstrap` (source
+an initial balance and native-value budget), `cashout` (withdraw a requested
+native-asset amount), `deposit` and
 `depositPayable` (external funds in), `settlePayable` (funded settlement),
 `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
@@ -354,48 +357,60 @@ 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 cmd, uint resources, #bytes as input }
+step { uint cmd, uint128 value, #bytes as input }
 ```
 
-Each step names a command, the resources it may spend, and its input.
+Each step names a command, the native value 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 posting implementation before
-running the next step. This is the core of `Pipeline.pipe`:
+empty. Each returned native credit replenishes the budget before running the
+next step, allowing one command to fund later commands. The standard
+`bootstrap` command consumes a stream of
+`#bootstrap { bytes32 asset, uint amount, uint budget }` requests and atomically
+debits each asset through the standard account hook, introduces matching
+`#balance` state, and sources summed trusted credit through its dedicated budget
+hook. This is the core of
+`Pipeline.pipe`:
 
 ```solidity
 while (cur.more()) {
-    (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
-    Reader memory transactions;
-    (state, transactions.source) = dispatch(
+    (uint cmd, uint128 value, bytes calldata input) = cur.unpackStep();
+    if (budget < value) revert InsufficientValue();
+    unchecked { budget -= value; }
+    uint credit;
+    (state, credit) = dispatch(
         cmd,
         account,
         state,
         input,
-        budget.useResourceValue(resources)
+        value
     );
-    while (transactions.more()) {
-        (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
-        post(from, to, asset, amount);
-    }
+    budget += credit;
 }
 if (state.length != 0) revert UnexpectedState();
 ```
 
+`Pipeline.pipe` takes the available native-value budget as a `uint` and returns
+the remaining budget after every step has executed. The enclosing entrypoint
+settles that final value once.
+
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
 `#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
-shared budget), so the same pipeline bytes are meaningful to every port.
-
-Hosts that implement a pipeline locally can inherit `DebitAccountInternal`,
-`CreditAccountInternal`, `SettleInternal`, and `RepayInternal` to advertise the
-canonical command endpoints while routing their local command IDs through
+command batching. A step's `uint128 value` is drawn directly from the shared
+native-value budget. Transport envelopes retain separate chain-specific
+`resources` fields for adapters that also need gas or runtime parameters.
+
+Hosts that implement a pipeline locally can inherit `BootstrapInternal`,
+`CashoutInternal`, `DebitAccountInternal`, `CreditAccountInternal`,
+`SettleInternal`, and
+`RepayInternal` to advertise the canonical command endpoints while routing
+their local command IDs through `executeBootstrap`, `executeCashout`,
 `executeDebitAccount`, `executeCreditAccount`, `executeSettle`, and
-`executeRepay`. These adapters consume the memory-backed pipeline state directly
-and avoid an external self-call. Pass the step value into each adapter; all four
-reject nonzero value because the commands are non-funded.
+`executeRepay`. The bootstrap, cashout, and debit adapters decode fixed-stride
+calldata input directly; the other three
+decode memory-backed pipeline state. All avoid an external self-call. Pass the
+step value into each adapter; all six reject nonzero value because the commands
+are non-funded.
 
 Positions also support backward-composed pipelines. In an exact-output route,
 the asset side can represent the desired result while the liability side
@@ -482,13 +497,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`,
-  `Settlement`, `Pipeline`, `Portal`, validator
+  `Settlement`, `PipeHook`, `Pipeline`, `Portal`, validator
 - `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, `Flags`,
   codec helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
-  mixins, their hooks, and `Flags`
+  mixins, their hooks (including `PipeHook`), and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
-  `Reader`/`Readers`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
+  `Memory`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
   `Specs`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers

package/Utils.sol

@@ -12,7 +12,8 @@ import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
 import { Layout } from "./utils/Layout.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, ensureContract, hash32, intToBytes32, InvalidContract, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow, ZeroAddress } from "./utils/Utils.sol";
+import { BadAmount, InsufficientValue, InvalidAccount, InvalidAsset, InvalidContract, InvalidId, InvalidPreimage, MissingCursor, NotDivisible, OutOfBounds, UnauthorizedAsset, UnconsumedData, UnexpectedPosition, ValueOverflow, ZeroAddress, ZeroAmount} from "./utils/Errors.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, ensureContract, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase } from "./utils/Utils.sol";