@rootzero/contracts 1.29.0 → 1.30.0

package/CHANGELOG.md

@@ -8,6 +8,70 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.30.0
+
+### Breaking Changes
+
+- Replaced the obsolete second representation/width byte in every structured
+  ID with a trailing flags byte. The type prefix is now
+  `[uint8 representation][uint8 category][uint8 subtype][uint8 flags]`, changing
+  every structured account, asset, and node ID. Endpoint IDs copy the same flags
+  published in their descriptors.
+- Added the canonical handoff command flag. Relay commands now publish command
+  IDs carrying `Flags.Handoff`. `Pipeline.pipe` now wraps a flagged STEP's
+  ordinary input and untouched continuation in a RELAY block, calls the handoff
+  command once, and stops local execution of that continuation.
+  The internal RELAY block changed from `(portal, resources, input)` to two
+  nested byte streams: command-specific `input` and remaining `steps`. Relay
+  hooks now receive `account`, complete `state`, opaque command input, remaining
+  steps, and their value budget; each transport implementation decodes its own
+  command input.
+- Added `Flags.HandoffFunded` as the canonical combination used by funded
+  handoff commands, matching the existing `Flags.AdminFunded` convention.
+- Removed the free `rawCommandCall` API and moved its cursor-aware assembly path
+  into `Pipeline` as a private implementation detail. Pipeline's private `run`
+  path now owns local execution, trust, command unpacking, handoff selection,
+  invocation, and cursor advancement. `pipe` accepts the STEP stream as
+  calldata and packs its current position, end, command-input offset, and
+  command-input length into one private cursor. The invocation path uses those
+  fields directly for ordinary input or to wrap a handoff continuation in a
+  RELAY block.
+- Removed the free `unpackCommand` utility. Pipeline now privately validates
+  command IDs and extracts the target and direct handoff decision needed for
+  routing; the private invoker derives selector and target directly from the ID.
+- Aligned no-argument `raw` access across cursors, decoders, and executions to
+  return only the unread region from the current position. `rawState`,
+  `rawInput`, `takeRawState`, and `takeRawInput` now follow the same rule;
+  explicitly bounded `raw(from, to)` slices remain frame-relative.
+
+- Replaced the stateless `RawNodeCalls` inheritance contract with imported
+  `tryRawCall`, `rawCall`, and `rawQuery` free functions. Added overloads that
+  accept a selector and native target separately from selector-free ABI
+  arguments, without allocating a concatenated calldata buffer.
+- Changed `Host`, `CommandHost`, `CommanderAccess`, and `HostIntroduction`
+  constructors from an EVM `address` to a protocol-native `uint` commander host
+  ID. Nonzero commanders must be valid local host IDs; the EVM address is
+  extracted internally for caller checks and introductions, while zero retains
+  the self-commanded `Host` convention and remains invalid for `CommandHost`.
+- Removed `RequestAllowanceHook`. `RequestAllowancePort` now reuses the
+  authoritative `AllowanceHook` and scopes each allowance update to the
+  authenticated peer before calling `allowance(peer, asset, amount)`.
+- Changed `Cashout` from a `#cashout { uint amount }` input command into a
+  native-only `#balance` state consumer. Removed the CASHOUT block key, spec,
+  schema, codec helpers, and test encoder; cashout now reverts `InvalidAsset`
+  for non-native balance state.
+- Reordered `Settlement` hook inheritance to `PostHook`,
+  `DebitAccountHook`, `CreditAccountHook`, `SettleHook`, and `RepayHook`.
+  Downstream hosts combining `Settlement` with hook-bearing endpoints may need
+  to reorder their base contracts.
+
+### Changed
+
+- Reduced per-step pipeline overhead by replacing the general lane cursor with
+  a private four-field pipeline cursor, specializing STEP advancement around
+  decoder-established bounds, preparing handoff input once, and avoiding
+  command and flag work on paths that do not need it.
+
 ## 1.29.0
 
 ### Breaking Changes

package/Codec.sol

@@ -7,7 +7,8 @@ pragma solidity ^0.8.33;
 import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Debt, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
-import { Descriptors, Flags } from "./codec/Descriptors.sol";
+import { Descriptors } from "./codec/Descriptors.sol";
+import { Flags } from "./utils/Flags.sol";
 import { Schemas } from "./codec/Schema.sol";
 import { Decoders } from "./codec/Decoders.sol";
 import { Cursors, Cur } from "./utils/Cursors.sol";

package/Commands.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file for both standard Execution-based commands and custom decoders.
 
 import {CommandBase} from "./commands/Base.sol";
-import {Flags} from "./codec/Descriptors.sol";
+import {Flags} from "./utils/Flags.sol";
 import {Execution, Executions} from "./execution/Execution.sol";
 import {Lanes} from "./utils/Lanes.sol";
 import {Blocks} from "./codec/Blocks.sol";

package/Core.sol

@@ -12,7 +12,7 @@ import { Balances, InsufficientFunds } from "./core/Balances.sol";
 import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Admins, CommandHost, Guardians, Host, HostIntroduction, IHostIntroduction } from "./core/Host.sol";
-import { FailedCall, NodeCalls, PortCalls, RawNodeCalls, rawCommandCall } from "./core/Calls.sol";
+import { FailedCall, NodeCalls, PortCalls, rawCall, rawQuery, tryRawCall } from "./core/Calls.sol";
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
 import { ExecuteHook, PipeHook, Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";

package/Endpoints.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
 // Shared endpoint hooks
-import {Flags} from "./codec/Descriptors.sol";
+import {Flags} from "./utils/Flags.sol";
 import {ExecuteHook, PipeHook} from "./core/Pipeline.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
@@ -48,7 +48,7 @@ import {Unauthorize} from "./commands/admin/Unauthorize.sol";
 // Port endpoints
 import {PortBase} from "./ports/Base.sol";
 import {AllowAssetsPort, DenyAssetsPort, RequestAssetPort, RequestAssetHook} from "./ports/Assets.sol";
-import {RequestAllowancePort, RequestAllowanceHook} from "./ports/Allowance.sol";
+import {RequestAllowancePort} from "./ports/Allowance.sol";
 import {RedeemBalancePort, RedeemBalanceHook} from "./ports/Redeem.sol";
 import {CreditAccountPort} from "./ports/Credit.sol";
 import {DebitAccountPort} from "./ports/Debit.sol";

package/README.md

@@ -38,7 +38,7 @@ import { CommandHost, Balances } from "@rootzero/contracts/Core.sol";
 import { Deposit } from "@rootzero/contracts/Endpoints.sol";
 
 contract ExampleHost is CommandHost, Balances, Deposit {
-    constructor(address commander) CommandHost(commander) {}
+    constructor(uint commander) CommandHost(commander) {}
 
     function deposit(bytes32 account, bytes32 asset, uint amount) internal override {
         uint balance = creditTo(account, asset, amount);
@@ -47,17 +47,17 @@ contract ExampleHost is CommandHost, Balances, Deposit {
 }
 ```
 
-`CommandHost` requires a nonzero commander and accepts command calls only from
-that address. It has no built-in admin commands, peer registry, guardians,
+`CommandHost` requires a nonzero local commander host ID and accepts command
+calls only from its embedded native caller. It has no built-in admin commands, peer registry, guardians,
 inbound introduction endpoint, generic execution command, or native-token
 receive function. Use `Host` instead when the application needs those advanced
 facilities; its commands accept the commander, the host itself, and explicitly
 authorized host callers.
 
-Both host types introduce themselves during deployment when the commander is a
-contract. That commander must implement `introduce(uint,uint)` and accept the
-call, otherwise deployment reverts. EOA commanders do not receive an
-introduction call.
+Both host types introduce themselves during deployment when the native target
+encoded by the commander host ID is a contract. That commander must implement
+`introduce(uint,uint)` and accept the call, otherwise deployment reverts. Host
+IDs encoding EOAs do not receive an introduction call.
 
 Host contracts are designed for fresh deployment rather than proxy upgrades.
 Releases may change inheritance storage layout, immutable configuration, and
@@ -68,16 +68,18 @@ Commands using trusted outbound `NodeCalls` also require a `TrustAccess`
 implementation. The advanced `Host` supplies one through its composed node access, while
 `CommandHost` deliberately does not. A minimal host can explicitly compose a
 custom trust policy, or a command that intentionally targets arbitrary nodes
-can inherit `RawNodeCalls` instead.
+can import the free raw-call helpers instead.
 
-Deploy it with your own address as commander and you can call its commands
+Deploy it with the local host ID encoding your native identity as commander and you can call its commands
 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/setup.ts`](test/helpers/setup.ts) and
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts) for reference
 implementations):
 
 ```ts
-const host = await ethers.deployContract("ExampleHost", [deployer.address]);
+const commander = await hostId(deployer.address);
+const host = await ethers.deployContract("ExampleHost", [commander]);
 
 const account = encodeUserAccount(user.address); // receiving account
 const input = encodeAmountBlock(asset, 100n); // what to deposit
@@ -188,7 +190,8 @@ Structured EVM IDs use:
 [uint32 type][uint32 chainid][192-bit payload]
 ```
 
-where `type` packs `[uint16 representation][uint8 category][uint8 subtype]`. A
+where `type` packs
+`[uint8 representation][uint8 category][uint8 subtype][uint8 flags]`. A
 structured ID 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, while admin accounts are chain-local. Guardians
@@ -229,8 +232,10 @@ which accepts `hostAsset { uint host, bytes32 asset }` entries and always applie
 a zero allowance. The full `Host` composes
 both, while smaller hosts can inherit either bundle separately.
 
-Trust is explicit and minimal. Each host has an immutable **commander**
-address fixed at construction, from which its **admin account** is derived.
+Trust is explicit and minimal. Each host receives an immutable **commander host
+ID** at construction. The EVM port validates that it is local, extracts its
+native address internally for caller checks, and derives the **admin account**
+from that native identity.
 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
@@ -341,13 +346,16 @@ abstract contract MyCommand is CommandBase {
 
 The final argument is a packed flags byte. Pass `0` for an ordinary endpoint,
 or compose values such as `Flags.Funded`, `Flags.Admin`, and
-`Flags.AdminFunded` from the command or endpoint package entry point. Bits 6
-and 7 are reserved for endpoint-defined custom flags. Bits 2 through 5 remain
-reserved for future protocol flags.
+`Flags.AdminFunded` from the command or endpoint package entry point.
+The same flags byte is copied into the endpoint ID, keeping runtime behavior and
+published descriptor metadata aligned. `Flags.Handoff` marks a command that
+takes ownership of the remaining pipeline, while `Flags.HandoffFunded` combines
+handoff behavior with native-value funding;
+bit 6 remains endpoint-defined, and bits 2 through 5 remain reserved.
 
 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
+an initial balance and native-value budget), `cashout` (withdraw native
+`#balance` state), `deposit` and
 `depositPayable` (external funds in), `settlePayable` (funded settlement),
 `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
@@ -383,23 +391,18 @@ metadata but is only executable through local pipeline execution. This is the co
 `Pipeline.pipe`:
 
 ```solidity
-while (cur.more()) {
-    (uint cmd, uint value, bytes calldata input) = cur.unpackStep();
-    (bytes4 selector, address target) = unpackCommand(cmd);
-    if (budget < value) revert InsufficientValue();
+uint cursor;
+assembly ("memory-safe") {
+    cursor := or(steps.offset, shl(32, add(steps.offset, steps.length)))
+}
+while (uint32(cursor) < uint32(cursor >> 32)) {
+    uint cmd;
+    uint value;
+    (cmd, value, cursor) = takeStep(cursor);
+    if (value > budget) revert InsufficientValue();
     unchecked { budget -= value; }
-    bool handled;
-    bytes memory output;
-    uint credit;
-    if (target == address(this)) {
-        (handled, output, credit) = execute(cmd, account, state, input, value);
-    }
-    if (!handled) {
-        ensureTrusted(cmd);
-        (output, credit) = rawCommandCall(selector, target, value, account, state, input);
-    }
-    state = output;
-    budget += credit;
+    (state, value, cursor) = run(cmd, account, state, value, cursor);
+    budget += value;
 }
 if (state.length != 0) revert UnexpectedState();
 ```
@@ -408,6 +411,42 @@ if (state.length != 0) revert UnexpectedState();
 the remaining budget after every step has executed. The enclosing entrypoint
 settles that final value once.
 
+The EVM pipeline is deliberately coupled to the canonical wire layout for gas
+efficiency. It extracts command selectors, targets, and flags directly from
+command IDs and writes CONTEXT, BYTES, and RELAY blocks directly in assembly.
+Any change to those ID fields or block encodings must update `Pipeline` at the
+same time; the general node and block helpers are not used on this hot path.
+
+A handoff command retains the ordinary command subtype and carries
+`Flags.Handoff` in both its ID and descriptor. The reserved handoff envelope is:
+
+```txt
+relay { #bytes as input, #bytes as steps }
+```
+
+`input` is the handoff STEP's ordinary command input, while `steps` is the
+untouched remainder of the original pipeline. `Pipeline.pipe` constructs this
+envelope automatically for commands carrying `Flags.Handoff`, calls the command,
+and stops executing the transferred continuation locally. Pipeline authors
+therefore encode only the command's ordinary input in the handoff STEP.
+
+Handoff has four operational rules:
+
+- A host-local `execute` hook must return `handled = false` for handoff command
+  IDs. The hook sees only ordinary STEP input; delegation lets `Pipeline`
+  construct the RELAY envelope containing the continuation.
+- Handoff transfers STEP bytes, not the pipeline's complete native-value
+  budget. The handoff command receives its assigned STEP value. Returned credit
+  rejoins the source budget, and the enclosing source entrypoint settles the
+  final remainder normally.
+- The handoff command must consume or forward the current state and return empty
+  state. Because the continuation is no longer executed locally, returned
+  non-empty state fails pipeline finalization with `UnexpectedState`.
+- A transport that completes asynchronously should relinquish only state that
+  is safe before destination success is known. The standard relay commands are
+  intended for empty or balance state; debt, position, and similarly fallible
+  state must not be relayed this way.
+
 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
@@ -423,9 +462,9 @@ Hosts that implement a pipeline locally can inherit `Bootstrap`,
 `ExecuteRepay` to register canonical command metadata while executing
 their local command IDs through `executeBootstrap`, `executeCashout`,
 `executeDebitAccount`, `executeCreditAccount`, `executeSettle`, and
-`executeRepay`. The bootstrap, cashout, and debit adapters decode fixed-stride
-calldata input directly; the other three
-decode memory-backed pipeline state. All return `handled = true` and avoid an
+`executeRepay`. The bootstrap and debit adapters decode fixed-stride calldata
+input directly; cashout, credit, settle, and repay decode memory-backed pipeline
+state. All return `handled = true` and avoid an
 external self-call. The host's `execute` hook must authorize a command before
 returning true. Returning `handled = false` delegates a local command to its
 trusted normal external entrypoint. Pass the step value into each adapter.
@@ -467,8 +506,14 @@ the descriptor's lanes through the published block schemas.
 
 ## Ports
 
-Ports are the host-to-host surfaces, callable only by trusted peer hosts. The two
-central ones are batches all the way down:
+Ports are the host-to-host surfaces, callable only by trusted peer hosts. By
+default, trusting a peer means the host has verified that peer and permits it to
+use the functionality of every port the host exposes without another policy
+decision inside each port. A host that needs narrower capabilities can add
+per-port or per-operation checks in its hook implementations, or expose custom
+ports with a different access model.
+
+The central ports are batches all the way down:
 
 - `portPost` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
@@ -477,14 +522,16 @@ central ones are batches all the way down:
   passes the authenticated peer, asset, and amount to a host hook. The hook
   validates asset support and applies the host's request and transfer policy.
 - `portRequestAllowance` consumes the same amount blocks and lets the
-  authenticated peer request an asset allowance. The hook decides what
-  allowance, if any, to grant.
+  authenticated peer set its own asset allowance through the same authoritative
+  hook used by the admin allowance command.
 - `portPipePayable` consumes `context` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
   host, executed locally against the port call's shared value budget.
 
-This is also the cross-portal mechanism. `relayPayable`, `relayBalancePayable`,
-or `portDispatchPayable` wraps a pipe and addresses it to a portal, commonly the destination host ID;
+This is also the cross-portal mechanism. `relayPayable` and
+`relayBalancePayable` are handoff commands whose transport hooks decode their
+own destination and resource input, while `portDispatchPayable` dispatches an
+explicit portal payload. The adapter wraps and addresses the destination pipe;
 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 commands

package/Utils.sol

@@ -10,8 +10,9 @@ import { Actions } from "./utils/Actions.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
-import { Nodes, unpackCommand } from "./utils/Nodes.sol";
+import { Nodes } from "./utils/Nodes.sol";
 import { Layout } from "./utils/Layout.sol";
+import { Flags } from "./utils/Flags.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";
 

package/codec/Blocks.sol

@@ -380,20 +380,6 @@ library Blocks {
         }
     }
 
-    /// @notice Write a CASHOUT block at `i`.
-    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.Cashout` bytes first.
-    /// @param dst Destination buffer.
-    /// @param i Relative write position.
-    /// @param amount Native-asset amount to withdraw.
-    function writeCashout(bytes memory dst, uint i, uint amount) internal pure {
-        uint spec = Specs.Cashout;
-        assembly ("memory-safe") {
-            let p := add(add(dst, 0x20), i)
-            mstore(p, spec)
-            mstore(add(p, 0x08), amount)
-        }
-    }
-
     // Two-word payloads
 
     /// @notice Write an AMOUNT block at `i`.
@@ -808,23 +794,23 @@ library Blocks {
     /// block size and ensure the encoded payload length fits in uint32.
     /// @param dst Destination buffer.
     /// @param i Relative write position.
-    /// @param portal Destination portal.
-    /// @param resources Packed resources.
-    /// @param input Relay input.
-    function writeRelay(bytes memory dst, uint i, uint portal, uint resources, bytes memory input) internal pure {
-        uint len = 64 + Sizes.Header + input.length;
+    /// @param input Command-specific handoff input.
+    /// @param steps Remaining pipeline steps.
+    function writeRelay(bytes memory dst, uint i, bytes memory input, bytes memory steps) internal pure {
+        uint len = 2 * Sizes.Header + input.length + steps.length;
         uint key = uint32(Keys.Relay);
         uint byteskey = uint32(Keys.Bytes);
         assembly ("memory-safe") {
             let p := add(add(dst, 0x20), i)
             mstore(p, or(shl(224, key), shl(192, len)))
-            mstore(add(p, 0x08), portal)
-            mstore(add(p, 0x28), resources)
-
-            let q := add(p, 0x48)
+            let q := add(p, 0x08)
             let inputlen := mload(input)
             mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
             mcopy(add(q, 0x08), add(input, 0x20), inputlen)
+            q := add(add(q, 0x08), inputlen)
+            let stepslen := mload(steps)
+            mstore(q, or(shl(224, byteskey), shl(192, stepslen)))
+            mcopy(add(q, 0x08), add(steps, 0x20), stepslen)
         }
     }
 
@@ -1053,9 +1039,23 @@ library Blocks {
         copyComposite(dst, i, Keys.Call, target, resources, payload);
     }
 
-    /// @notice Encode a RELAY block at `i`, copying its nested input from calldata.
-    function copyRelay(bytes memory dst, uint i, uint portal, uint resources, bytes calldata input) internal pure {
-        copyComposite(dst, i, Keys.Relay, portal, resources, input);
+    /// @notice Encode a RELAY block at `i`, copying its nested streams from calldata.
+    function copyRelay(bytes memory dst, uint i, bytes calldata input, bytes calldata steps) internal pure {
+        uint len = 2 * Sizes.Header + input.length + steps.length;
+        uint key = uint32(Keys.Relay);
+        uint byteskey = uint32(Keys.Bytes);
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, or(shl(224, key), shl(192, len)))
+            let q := add(p, 0x08)
+            let inputlen := input.length
+            mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
+            calldatacopy(add(q, 0x08), input.offset, inputlen)
+            q := add(add(q, 0x08), inputlen)
+            let stepslen := steps.length
+            mstore(q, or(shl(224, byteskey), shl(192, stepslen)))
+            calldatacopy(add(q, 0x08), steps.offset, stepslen)
+        }
     }
 
     /// @notice Encode a DISPATCH block at `i`, copying its nested payload from calldata.
@@ -1458,18 +1458,6 @@ library Blocks {
         if (head >> 192 != Specs.Status >> 192) revert InvalidBlock();
     }
 
-    /// @notice Decode a low-level fixed-width CASHOUT block at `abs`.
-    /// @param abs Absolute block position.
-    /// @return amount Native-asset amount to withdraw.
-    function unpackCashout(uint abs) internal pure returns (uint amount) {
-        uint head;
-        assembly ("memory-safe") {
-            head := calldataload(abs)
-            amount := calldataload(add(abs, 0x08))
-        }
-        if (head >> 192 != Specs.Cashout >> 192) revert InvalidBlock();
-    }
-
     // Two-word payloads
 
     /// @notice Decode a low-level fixed-width AMOUNT block at `abs`.
@@ -1866,22 +1854,18 @@ library Blocks {
         if (end != limit) revert InvalidBlock();
     }
 
-    /// @notice Decode one RELAY block and its nested input.
+    /// @notice Decode one RELAY block and its nested input and continuation.
     /// @param abs Absolute block position.
-    /// @return portal Decoded destination portal.
-    /// @return resources Decoded packed resources.
-    /// @return input Decoded relay input.
+    /// @return input Decoded command-specific input.
+    /// @return steps Decoded remaining pipeline steps.
     /// @return end Absolute position after the block.
     function unpackRelay(
         uint abs
-    ) internal pure returns (uint portal, uint resources, bytes calldata input, uint end) {
+    ) internal pure returns (bytes calldata input, bytes calldata steps, uint end) {
         uint limit;
         (abs, limit) = expectKey(abs, Keys.Relay);
-        assembly ("memory-safe") {
-            portal := calldataload(abs)
-            resources := calldataload(add(abs, 0x20))
-        }
-        (input, end) = unpackBytes(abs + 64);
+        (input, abs) = unpackBytes(abs);
+        (steps, end) = unpackBytes(abs);
         if (end != limit) revert InvalidBlock();
     }
 
@@ -2119,14 +2103,6 @@ library Blocks {
         writeBootstrap(value, 0, asset, amount, budget);
     }
 
-    /// @notice Encode a CASHOUT block.
-    /// @param amount Native-asset amount to withdraw.
-    /// @return value Encoded CASHOUT block bytes.
-    function createCashout(uint amount) internal pure returns (bytes memory value) {
-        value = allocate(Sizes.Cashout);
-        writeCashout(value, 0, amount);
-    }
-
     /// @notice Encode an AMOUNT block.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
@@ -2235,22 +2211,20 @@ library Blocks {
     }
 
     /// @notice Encode a RELAY block.
-    /// @param portal Destination portal implementation's host ID, passed through
-    /// without semantic validation.
-    /// @param resources Chain-specific resources for the destination context.
-    /// @param input Nested input block stream.
+    /// @param input Nested command-specific input block stream.
+    /// @param steps Nested remaining STEP block stream.
     /// @return value Encoded RELAY block bytes.
-    function createRelay(uint portal, uint resources, bytes memory input) internal pure returns (bytes memory value) {
-        uint len = max32(Sizes.B64 + Sizes.Header + input.length);
+    function createRelay(bytes memory input, bytes memory steps) internal pure returns (bytes memory value) {
+        uint len = max32(3 * Sizes.Header + input.length + steps.length);
         value = allocate(len);
-        writeRelay(value, 0, portal, resources, input);
+        writeRelay(value, 0, input, steps);
     }
 
-    /// @notice Encode a RELAY block by copying its nested input from calldata.
-    function createRelayCopy(uint portal, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
-        uint len = max32(Sizes.B64 + Sizes.Header + input.length);
+    /// @notice Encode a RELAY block by copying its nested streams from calldata.
+    function createRelayCopy(bytes calldata input, bytes calldata steps) internal pure returns (bytes memory value) {
+        uint len = max32(3 * Sizes.Header + input.length + steps.length);
         value = allocate(len);
-        copyRelay(value, 0, portal, resources, input);
+        copyRelay(value, 0, input, steps);
     }
 
     /// @notice Encode a DISPATCH block.

package/codec/Decoders.sol

@@ -22,7 +22,7 @@ library Decoders {
     /// @param source Calldata region to open.
     /// @return cur Cursor spanning the complete source.
     function open(bytes calldata source) internal pure returns (Cur memory cur) {
-        cur.state = Cursors.wrap(source, 0);
+        cur.state = Cursors.wrap(source);
     }
 
     /// @notice Return whether `cur` has unread bytes.
@@ -138,13 +138,15 @@ library Decoders {
         out.state = cur.state.slice(from, to, 0);
     }
 
-    /// @notice Return the complete calldata region represented by `cur`.
+    /// @notice Return the unread calldata region represented by `cur`.
     /// @param cur Cursor whose calldata is returned.
-    /// @return Complete cursor region.
-    function raw(Cur memory cur) internal pure returns (bytes calldata) {
-        (uint abs, uint end) = cur.state.bounds();
-        if (end > msg.data.length) revert Blocks.MalformedBlocks();
-        return msg.data[abs:end];
+    /// @return data Unread cursor region from its current position.
+    function raw(Cur memory cur) internal pure returns (bytes calldata data) {
+        (uint i, uint offset, uint len) = cur.state.decode();
+        if (len > msg.data.length || offset > msg.data.length - len) {
+            revert Blocks.MalformedBlocks();
+        }
+        data = msg.data[offset + i:offset + len];
     }
 
     /// @notice Return relative calldata range `[from, to)` from `cur`.
@@ -376,15 +378,6 @@ library Decoders {
         node = Blocks.unpackNode(abs);
     }
 
-    /// @notice Decode and consume one CASHOUT block.
-    /// @param cur Cursor advanced past the block.
-    /// @return amount Native-asset amount to withdraw.
-    function unpackCashout(Cur memory cur) internal pure returns (uint amount) {
-        uint abs;
-        (cur.state, abs) = cur.state.consume(Sizes.Cashout);
-        amount = Blocks.unpackCashout(abs);
-    }
-
     /// @notice Decode and consume one BOOTSTRAP block.
     /// @param cur Cursor advanced past the block.
     /// @return asset Decoded asset identifier.
@@ -749,15 +742,14 @@ library Decoders {
 
     /// @notice Decode and consume one RELAY block.
     /// @param cur Cursor advanced past the block.
-    /// @return portal Decoded destination portal.
-    /// @return resources Decoded packed resources.
     /// @return input Decoded relay input.
+    /// @return steps Decoded remaining pipeline steps.
     function unpackRelay(
         Cur memory cur
-    ) internal pure returns (uint portal, uint resources, bytes calldata input) {
+    ) internal pure returns (bytes calldata input, bytes calldata steps) {
         uint abs = cur.state.absolute();
         uint end;
-        (portal, resources, input, end) = Blocks.unpackRelay(abs);
+        (input, steps, end) = Blocks.unpackRelay(abs);
         cur.state = cur.state.seekAbs(end);
     }
 

package/codec/Descriptors.sol

@@ -5,18 +5,7 @@ import {Blocks} from "./Blocks.sol";
 import {Buffers} from "./Buffers.sol";
 import {Sizes, Specs} from "./Specs.sol";
 import {Lanes} from "../utils/Lanes.sol";
-
-/// @title Flags
-/// @notice Packed endpoint behavior flags.
-/// @dev Bits 6 and 7 are reserved for endpoint-defined custom flags.
-library Flags {
-    /// @dev Endpoint accepts nonzero native value.
-    uint8 internal constant Funded = 1 << 0;
-    /// @dev Endpoint is restricted to the admin account.
-    uint8 internal constant Admin = 1 << 1;
-    /// @dev Endpoint accepts nonzero native value and is restricted to the admin account.
-    uint8 internal constant AdminFunded = Admin | Funded;
-}
+import {Flags} from "../utils/Flags.sol";
 
 /// @title Descriptors
 /// @notice Packing and lane metadata helpers for endpoint descriptors.
@@ -26,8 +15,8 @@ library Descriptors {
     /// `[input key:4][stride:1]`
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
     /// `[reserved:5]`
-    /// `[flags:1]`. Flag bits: funded = 0, admin = 1; bits 6 and 7 are
-    /// reserved for endpoint-defined custom flags.
+    /// `[flags:1]`. Flag bits: funded = 0, admin = 1, handoff = 7;
+    /// bit 6 is reserved for endpoint-defined custom behavior.
     /// @dev TODO: Add per-lane cardinality metadata so off-chain consumers can
     /// distinguish exactly-one lanes from batches. Command decoding must remain
     /// the runtime source of truth; this metadata should not restore eager scans.