@rootzero/contracts 0.9.9 → 1.0.1

package/Endpoints.sol

@@ -16,6 +16,7 @@ import { DebitAccount, DebitAccountHook } 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";
+import { RelayPayable, RelayPayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -37,6 +38,7 @@ import { PeerAllowance } from "./peer/Allowance.sol";
 import { PeerBalancePull, BalancePullHook } from "./peer/BalancePull.sol";
 import { PeerDenyAssets } from "./peer/DenyAssets.sol";
 import { PeerPipePayable } from "./peer/Pipe.sol";
+import { PeerDispatchPayable } from "./peer/Dispatch.sol";
 import { PeerSettle } from "./peer/Settle.sol";
 
 // Guard endpoints

package/Events.sol

@@ -8,6 +8,7 @@ import { AdminEvent } from "./events/Admin.sol";
 import { AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
+import { ChainEvent } from "./events/Chain.sol";
 import { CommandEvent } from "./events/Command.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";

package/README.md

@@ -8,11 +8,11 @@ It contains the reusable contracts, utilities, cursor parsers, and encoding help
 
 Most consumers should start from the package root entry points:
 
-- `@rootzero/contracts/Core.sol` — host, access control, balances, and validator building blocks
-- `@rootzero/contracts/Endpoints.sol` — command, peer, guard, and query base contracts plus standard endpoint mixins
-- `@rootzero/contracts/Cursors.sol` — cursor reader (`Cur`), block schemas, key constants, typed block helpers, and writers
-- `@rootzero/contracts/Utils.sol` — IDs, assets, accounts, layout, and value helpers
-- `@rootzero/contracts/Events.sol` — reusable event emitters and event contracts
+- `@rootzero/contracts/Core.sol` - host, access control, balances, and validator building blocks
+- `@rootzero/contracts/Endpoints.sol` - command, peer, guard, and query base contracts plus standard endpoint mixins
+- `@rootzero/contracts/Cursors.sol` - cursor reader (`Cur`), block schemas, key constants, typed block helpers, and writers
+- `@rootzero/contracts/Utils.sol` - IDs, assets, accounts, layout, and value helpers
+- `@rootzero/contracts/Events.sol` - reusable event emitters and event contracts
 
 ## Block Wire Format
 
@@ -28,7 +28,7 @@ All request and response data is encoded as a binary block stream. Each block is
 
 Protocol blocks use schema strings and four-byte keys:
 
-- `Schemas` describes semantic protocol blocks such as `#amount`, `#balance`, `#custody`, and `#payout`.
+- `Schemas` describes semantic protocol blocks such as `#amount`, `#balance`, `#custody`, and `#relay`.
 - `Forms` describes reusable structural blocks such as `#accountAsset` and `#accountAmount`, mostly used by queries.
 - `Keys` contains the runtime `bytes4` keys derived from block names.
 
@@ -77,21 +77,21 @@ abstract contract ExampleCommand is CommandBase {
     uint internal immutable myCommandId = commandId(NAME);
 
     constructor() {
-        emit Command(host, myCommandId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false);
+        emit Command(host, myCommandId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false, false);
     }
 
     function myCommand(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = cursor(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
-        while (request.i < request.bound) {
+        while (request.i < request.len) {
             (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
             writer.appendBalance(asset, meta, amount);
         }
 
-        request.close();
+        request.complete();
         return writer.finish();
     }
 }
@@ -99,14 +99,15 @@ abstract contract ExampleCommand is CommandBase {
 
 ## Repo Layout
 
-- `contracts/core` — host, access control, balances, operation base, and signature validation
-- `contracts/commands` — standard command building blocks and admin commands
-- `contracts/peer` — peer protocol surfaces for inter-host asset flows and asset allow/deny
-- `contracts/blocks` — block stream schema (`Schema`), cursor parsing (`Cursors`), and writers (`Writers`)
-- `contracts/utils` — shared encoding helpers: IDs, assets, accounts, layout, ECDSA
-- `contracts/events` — protocol event contracts and emitters
-- `contracts/interfaces` — discovery interfaces and shared external protocol surfaces
-- `docs` — introductory documentation
+- `contracts/core` - host, access control, balances, operation base, and signature validation
+- `contracts/commands` - standard command building blocks and admin commands
+- `contracts/peer` - peer protocol surfaces for inter-host asset flows and asset allow/deny
+- `contracts/guards` - guard action surfaces for delegated protection flows
+- `contracts/queries` - read-only query endpoints for protocol state
+- `contracts/blocks` - block stream schema (`Schema`), cursor parsing (`Cursors`), and writers (`Writers`)
+- `contracts/utils` - shared encoding helpers: IDs, assets, accounts, layout, ECDSA
+- `contracts/events` - protocol event contracts and emitters
+- `docs` - introductory documentation
 
 ## Install and Compile
 

package/blocks/Cursors.sol

@@ -108,26 +108,6 @@ library Cursors {
         if (groups != expectedGroups) revert BadRatio();
     }
 
-    /// @notice Create a cursor over the first grouped run in `source`.
-    /// Equivalent to `init(source, 0, group)` without returning the next offset.
-    /// @param source Calldata slice that forms the block stream.
-    /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
-    /// @return cur Cursor with `len` truncated to the end of the first run.
-    /// @return groups Number of block groups in the run (`block count / group`).
-    function first(bytes calldata source, uint group) internal pure returns (Cur memory cur, uint groups) {
-        (cur, groups, ) = init(source, 0, group);
-    }
-
-    /// @notice Create a cursor over the first grouped run in `source` and require an exact group count.
-    /// Equivalent to `init(source, 0, group, expectedGroups)` without returning the next offset.
-    /// @param source Calldata slice that forms the block stream.
-    /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
-    /// @param expectedGroups Required number of groups in the run.
-    /// @return cur Cursor with `len` truncated to the end of the first run.
-    function first(bytes calldata source, uint group, uint expectedGroups) internal pure returns (Cur memory cur) {
-        (cur, ) = init(source, 0, group, expectedGroups);
-    }
-
     /// @notice Move the cursor to an absolute position within the source region.
     /// @param cur Cursor to update.
     /// @param i New read position (byte offset relative to source start).
@@ -571,16 +551,34 @@ library Cursors {
     /// @param value Native value assigned to the pipe.
     /// @param account Command account identifier.
     /// @param state Embedded state block stream.
-    /// @param request Embedded request block stream.
+    /// @param steps Embedded step block stream.
     /// @return Encoded PIPE block bytes.
     function toPipeBlock(
         uint value,
         bytes32 account,
         bytes memory state,
-        bytes memory request
+        bytes memory steps
     ) internal pure returns (bytes memory) {
-        return createBlock(Keys.Pipe, bytes.concat(bytes32(value), toContextBlock(account, state, request)));
-    }
+        return createBlock(Keys.Pipe, bytes.concat(bytes32(value), toContextBlock(account, state, steps)));
+    }
+
+    /// @notice Encode a RELAY block.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific resources for the destination pipe.
+    /// @param steps Nested step block stream.
+    /// @return Encoded RELAY block bytes.
+    function toRelayBlock(uint chain, uint resources, bytes memory steps) internal pure returns (bytes memory) {
+        return createBlock(Keys.Relay, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(steps)));
+    }
+
+    /// @notice Encode a DISPATCH block.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific resources for the destination dispatch.
+    /// @param payload Encoded cross-chain payload.
+    /// @return Encoded DISPATCH block bytes.
+    function toDispatchBlock(uint chain, uint resources, bytes memory payload) internal pure returns (bytes memory) {
+        return createBlock(Keys.Dispatch, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(payload)));
+    }
 
     // -------------------------------------------------------------------------
     // Raw calldata loaders
@@ -592,19 +590,31 @@ library Cursors {
     /// @param cur Cursor whose current position is advanced by `n` bytes.
     /// @param n Number of bytes to advance.
     /// @return value Loaded word.
-    function read(Cur memory cur, uint n) internal pure returns (bytes32 value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += n;
-    }
-
-    /// @notice Read the next 16 bytes from the cursor and advance by 16 bytes.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 16 bytes.
-    /// @return value Loaded bytes16 value.
-    function read16(Cur memory cur) internal pure returns (bytes16 value) {
+    function read(Cur memory cur, uint n) internal pure returns (bytes32 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += n;
+    }
+
+    /// @notice Read the next 4 bytes from the cursor and advance by 4 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 4 bytes.
+    /// @return value Loaded bytes4 value.
+    function read4(Cur memory cur) internal pure returns (bytes4 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 4;
+    }
+
+    /// @notice Read the next 16 bytes from the cursor and advance by 16 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 16 bytes.
+    /// @return value Loaded bytes16 value.
+    function read16(Cur memory cur) internal pure returns (bytes16 value) {
         uint abs = cur.offset + cur.i;
         assembly ("memory-safe") {
             value := calldataload(abs)
@@ -616,18 +626,30 @@ library Cursors {
     /// @dev Performs no bounds, key, length, or cursor checks.
     /// @param cur Cursor whose current position is advanced by 32 bytes.
     /// @return value Loaded word.
-    function read32(Cur memory cur) internal pure returns (bytes32 value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += 32;
-    }
-
-    /// @notice Read the next two 32-byte words from the cursor and advance by 64 bytes.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 64 bytes.
-    /// @return a First loaded word.
+    function read32(Cur memory cur) internal pure returns (bytes32 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 32;
+    }
+
+    /// @notice Read the next uint from the cursor and advance by one word.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 32 bytes.
+    /// @return value Loaded uint value.
+    function readUint(Cur memory cur) internal pure returns (uint value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 32;
+    }
+
+    /// @notice Read the next two 32-byte words from the cursor and advance by 64 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 64 bytes.
+    /// @return a First loaded word.
     /// @return b Second loaded word.
     function read64(Cur memory cur) internal pure returns (bytes32 a, bytes32 b) {
         uint abs = cur.offset + cur.i;
@@ -1102,16 +1124,46 @@ library Cursors {
     /// @return value Native value assigned to the pipe.
     /// @return account Command account identifier.
     /// @return state Embedded state block stream.
-    /// @return request Embedded request block stream.
+    /// @return steps Embedded step block stream.
     function unpackPipe(
         Cur memory cur
-    ) internal pure returns (uint value, bytes32 account, bytes calldata state, bytes calldata request) {
+    ) internal pure returns (uint value, bytes32 account, bytes calldata state, bytes calldata steps) {
         uint end = cur.enter(Keys.Pipe, 32 + Sizes.Header + 32 + 2 * Sizes.Header, 0);
         value = uint(cur.read32());
-        (account, state, request) = cur.unpackContext();
+        (account, state, steps) = cur.unpackContext();
         cur.exit(end);
     }
 
+    /// @notice Consume a RELAY block and return its destination chain, resources, and step stream.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return resources Chain-adapter-specific resources for the destination pipe.
+    /// @return steps Embedded step block stream.
+    function unpackRelay(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint resources, bytes calldata steps) {
+        uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
+        chain = cur.readUint();
+        resources = cur.readUint();
+        steps = cur.unpackBytes();
+        cur.exit(end);
+    }
+
+    /// @notice Consume a DISPATCH block and return its destination chain, resources, and payload.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return resources Chain-adapter-specific resources for the destination dispatch.
+    /// @return payload Encoded cross-chain payload.
+    function unpackDispatch(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint resources, bytes calldata payload) {
+        uint end = cur.enter(Keys.Dispatch, 64 + Sizes.Header, 0);
+        chain = cur.readUint();
+        resources = cur.readUint();
+        payload = cur.unpackBytes();
+        cur.exit(end);
+    }
+
     // Type-specific validators
 
     /// @notice Validate an AUTH block at position `i` and extract deadline and proof.

package/blocks/Keys.sol

@@ -7,6 +7,8 @@ pragma solidity ^0.8.33;
 library Keys {
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
+    /// @dev Wildcard key used in discovery when any block stream is accepted.
+    bytes4 constant Any = 0xffffffff;
     /// @dev Input amount - (bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, bytes32 meta, uint amount)
@@ -37,6 +39,10 @@ library Keys {
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
     /// @dev Sub-command invocation - (uint target, uint value, #bytes as request)
     bytes4 constant Step = bytes4(keccak256("#step"));
+    /// @dev Cross-chain pipe relay - (uint chain, uint resources, #bytes as steps)
+    bytes4 constant Relay = bytes4(keccak256("#relay"));
+    /// @dev Cross-chain encoded payload dispatch - (uint chain, uint resources, #bytes as payload)
+    bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
     /// @dev Raw external call - (uint target, uint value, #bytes as payload)
     bytes4 constant Call = bytes4(keccak256("#call"));
     /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)

package/blocks/Schema.sol

@@ -12,7 +12,7 @@ pragma solidity ^0.8.33;
 // - commas separate siblings at every level
 // - braces define parent-child boundaries
 // - command requests start with the input run when the request schema is non-empty
-// - checked command requests include a constraint run after the input run; if the
+// - postcheck command requests include a constraint run after the input run; if the
 //   request schema is empty, the constraint run starts the request
 // - command state starts with the active state run; trailing state globals may follow
 // - run items may repeat at top level for batching
@@ -62,9 +62,11 @@ library Schemas {
     string constant Allowance = "#allowance { uint host, bytes32 asset, bytes32 meta, uint amount }";
     string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount }";
     string constant Context = "#context { bytes32 account, #bytes as state, #bytes as request }";
-    string constant Pipe = "#pipe { uint value, #context { bytes32 account, #bytes as state, #bytes as request } }";
+    string constant Pipe = "#pipe { uint value, #context { bytes32 account, #bytes as state, #bytes as steps } }";
     string constant Call = "#call { uint target, uint value, #bytes as payload }";
     string constant Step = "#step { uint target, uint value, #bytes as request }";
+    string constant Relay = "#relay { uint chain, uint resources, #bytes as steps }";
+    string constant Dispatch = "#dispatch { uint chain, uint resources, #bytes as payload }";
     string constant Bounty = "#bounty { uint amount, bytes32 relayer }";
     string constant Fee = "#fee { uint amount }";
     string constant Auth = "#auth { uint cid, uint deadline, #bytes as proof }";

package/blocks/Writers.sol

@@ -894,16 +894,16 @@ library Writers {
     /// @param value Native value assigned to the pipe.
     /// @param account Command account identifier.
     /// @param state Raw nested state payload.
-    /// @param request Raw nested request payload.
+    /// @param steps Raw nested step payload.
     function appendPipe(
         Writer memory writer,
         uint value,
         bytes32 account,
         bytes memory state,
-        bytes memory request
+        bytes memory steps
     ) internal pure {
         uint i = writer.i;
-        uint len = 64 + 3 * Sizes.Header + state.length + request.length;
+        uint len = 64 + 3 * Sizes.Header + state.length + steps.length;
         uint next = i + Sizes.Header + len;
         i = reserve(writer, next, next);
 
@@ -912,7 +912,7 @@ library Writers {
             mstore(add(p, 0x08), value)
         }
 
-        writeBlock32BytesBytes(writer.dst, i + Sizes.Header + 32, Keys.Context, account, state, request);
+        writeBlock32BytesBytes(writer.dst, i + Sizes.Header + 32, Keys.Context, account, state, steps);
     }
 
     /// @notice Append a STATUS form block.

package/commands/Burn.sol

@@ -28,8 +28,11 @@ abstract contract Burn is CommandBase, BurnHook {
         emit Command(host, burnId, NAME, "0:1:0", "", Keys.Balance, Keys.Empty, false, false);
     }
 
+    /// @notice Burn each BALANCE block from the command state.
+    /// @param c Command context; `c.state` must contain BALANCE blocks.
+    /// @return Empty output state.
     function burn(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory state, ) = Cursors.first(c.state, 1);
+        (Cur memory state, , ) = Cursors.init(c.state, 0, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();

package/commands/Credit.sol

@@ -28,10 +28,13 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
         emit Command(host, creditAccountId, NAME, "0:1:0", "", Keys.Balance, Keys.Empty, false, false);
     }
 
+    /// @notice Credit each BALANCE block from the command state to the command account.
+    /// @param c Command context; `c.state` must contain BALANCE blocks.
+    /// @return Empty output state.
     function creditAccount(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory state, ) = Cursors.first(c.state, 1);
+        (Cur memory state, , ) = Cursors.init(c.state, 0, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();

package/commands/Debit.sol

@@ -34,7 +34,7 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     /// The default implementation iterates AMOUNT blocks, calls
     /// `debitAccount`, and emits matching BALANCE blocks.
     function debitAccount(bytes32 account, bytes calldata request) internal virtual returns (bytes memory) {
-        (Cur memory input, uint groups) = Cursors.first(request, 1);
+        (Cur memory input, uint groups, ) = Cursors.init(request, 0, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
         while (input.i < input.len) {
@@ -47,6 +47,9 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
         return writer.finish();
     }
 
+    /// @notice Debit AMOUNT request blocks from the command account and output matching BALANCE blocks.
+    /// @param c Command context; `c.request` must contain AMOUNT blocks.
+    /// @return BALANCE block stream matching the debited amounts.
     function debitAccount(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {

package/commands/Deposit.sol

@@ -45,10 +45,13 @@ abstract contract Deposit is CommandBase, DepositHook {
         emit Command(host, depositId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false, false);
     }
 
+    /// @notice Deposit AMOUNT request blocks into the command account and output matching BALANCE blocks.
+    /// @param c Command context; `c.request` must contain AMOUNT blocks.
+    /// @return BALANCE block stream matching the deposited amounts.
     function deposit(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = Cursors.first(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
         while (request.i < request.len) {
@@ -74,10 +77,13 @@ abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
         emit Command(host, depositPayableId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false, true);
     }
 
+    /// @notice Deposit AMOUNT request blocks with access to a mutable native-value budget.
+    /// @param c Command context; `c.request` must contain AMOUNT blocks.
+    /// @return BALANCE block stream matching the deposited amounts.
     function depositPayable(
         CommandContext calldata c
     ) external payable onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = Cursors.first(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocBalances(groups);
         Budget memory budget = valueBudget();
 

package/commands/Payout.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.33;
 
 import {CommandContext, CommandBase, Keys} from "./Base.sol";
 import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Accounts} from "../utils/Accounts.sol";
 
 using Cursors for Cur;
 
@@ -29,13 +30,16 @@ abstract contract Payout is CommandBase, PayoutHook {
         emit Command(host, payoutId, NAME, "1:1:0", Schemas.Account, Keys.Balance, Keys.Empty, false, false);
     }
 
+    /// @notice Pay out BALANCE state blocks to matching ACCOUNT request blocks.
+    /// @param c Command context; `c.state` must contain BALANCE blocks and `c.request` matching ACCOUNT blocks.
+    /// @return Empty output state.
     function payout(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory state, uint groups) = Cursors.first(c.state, 1);
-        Cur memory request = Cursors.first(c.request, 1, groups);
+        (Cur memory state, uint groups, ) = Cursors.init(c.state, 0, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 0, 1, groups);
 
         while (state.i < state.len) {
             (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();
-            bytes32 to = request.unpackAccount();
+            bytes32 to = Accounts.ensure(request.unpackAccount());
             payout(c.account, to, asset, meta, amount);
         }
 

package/commands/Provision.sol

@@ -41,8 +41,11 @@ abstract contract Provision is CommandBase, ProvisionHook {
         emit Command(host, provisionId, NAME, "1:0:1", Schemas.Allocation, Keys.Empty, Keys.Custody, false, false);
     }
 
+    /// @notice Provision ALLOCATION request blocks and output matching CUSTODY state blocks.
+    /// @param c Command context; `c.request` must contain ALLOCATION blocks.
+    /// @return CUSTODY block stream matching the provisioned allocations.
     function provision(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = Cursors.first(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocCustodies(groups);
 
         while (request.i < request.len) {
@@ -69,10 +72,13 @@ abstract contract ProvisionPayable is CommandBase, Payable, ProvisionPayableHook
         emit Command(host, provisionPayableId, NAME, "1:0:1", Schemas.Allocation, Keys.Empty, Keys.Custody, false, true);
     }
 
+    /// @notice Provision ALLOCATION request blocks with access to a mutable native-value budget.
+    /// @param c Command context; `c.request` must contain ALLOCATION blocks.
+    /// @return CUSTODY block stream matching the provisioned allocations.
     function provisionPayable(
         CommandContext calldata c
     ) external payable onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = Cursors.first(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocCustodies(groups);
         Budget memory budget = valueBudget();
 

package/commands/Relay.sol

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandBase, CommandContext, Keys} from "./Base.sol";
+import {Payable} from "../core/Payable.sol";
+import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Budget} from "../utils/Value.sol";
+
+using Cursors for Cur;
+
+abstract contract RelayPayableHook {
+    /// @notice Override to relay `steps` to `chain` with the current account and state.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific destination resources. EVM adapters
+    /// may interpret this as packed execution gas and destination value.
+    /// @param account Command account identifier.
+    /// @param state Current command state block stream.
+    /// @param steps Embedded destination step block stream.
+    /// @param budget Source-chain native-value budget available for transport
+    /// fees and destination resource funding.
+    function relay(
+        uint chain,
+        uint resources,
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata steps,
+        Budget memory budget
+    ) internal virtual;
+}
+
+/// @title RelayPayable
+/// @notice Command that forwards one RELAY block to a host-defined relay hook.
+/// Reverts unless the request contains exactly one RELAY block, preventing
+/// the same state from being duplicated across multiple relays.
+/// Produces no output state.
+abstract contract RelayPayable is CommandBase, Payable, RelayPayableHook {
+    string private constant NAME = "relayPayable";
+
+    uint internal immutable relayPayableId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, relayPayableId, NAME, "1:0:0", Schemas.Relay, Keys.Any, Keys.Empty, false, true);
+    }
+
+    /// @notice Relay one RELAY request block with the command account and current state.
+    /// @param c Command context; `c.request` must contain exactly one RELAY block.
+    /// @return output Empty output state.
+    function relayPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory output) {
+        (Cur memory request, ) = Cursors.init(c.request, 0, 1, 1);
+        Budget memory budget = valueBudget();
+
+        (uint chain, uint resources, bytes calldata steps) = request.unpackRelay();
+        relay(chain, resources, c.account, c.state, steps, budget);
+        request.complete();
+        return "";
+    }
+}

package/commands/Withdraw.sol

@@ -28,10 +28,13 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
         emit Command(host, withdrawId, NAME, "0:1:0", "", Keys.Balance, Keys.Empty, false, false);
     }
 
+    /// @notice Withdraw each BALANCE block from the command state to the command account.
+    /// @param c Command context; `c.state` must contain BALANCE blocks.
+    /// @return Empty output state.
     function withdraw(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory state, ) = Cursors.first(c.state, 1);
+        (Cur memory state, , ) = Cursors.init(c.state, 0, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();

package/commands/admin/AllowAssets.sol

@@ -9,6 +9,8 @@ using Cursors for Cur;
 abstract contract AllowAssetsHook {
     /// @dev Override to allow a single asset/meta pair.
     /// Called once per ASSET block in the request.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
     function allowAsset(bytes32 asset, bytes32 meta) internal virtual;
 }
 
@@ -24,10 +26,13 @@ abstract contract AllowAssets is CommandBase, AdminEvent, AllowAssetsHook {
         emit Admin(host, allowAssetsId, NAME, "1:0:0", Schemas.Asset, Keys.Empty, Keys.Empty, false, false);
     }
 
+    /// @notice Allow each ASSET block in the admin request.
+    /// @param c Admin command context; `c.request` must contain ASSET blocks.
+    /// @return Empty output state.
     function allowAssets(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, ) = Cursors.first(c.request, 1);
+        (Cur memory request, , ) = Cursors.init(c.request, 0, 1);
 
         while (request.i < request.len) {
             (bytes32 asset, bytes32 meta) = request.unpackAsset();

package/commands/admin/Allowance.sol

@@ -29,8 +29,11 @@ abstract contract Allowance is CommandBase, AdminEvent, AllowanceHook {
         emit Admin(host, allowanceId, NAME, "1:0:0", Schemas.Allowance, Keys.Empty, Keys.Empty, false, false);
     }
 
+    /// @notice Apply each ALLOWANCE block in the admin request.
+    /// @param c Admin command context; `c.request` must contain ALLOWANCE blocks.
+    /// @return Empty output state.
     function allowance(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, ) = Cursors.first(c.request, 1);
+        (Cur memory request, , ) = Cursors.init(c.request, 0, 1);
 
         while (request.i < request.len) {
             (uint peer, bytes32 asset, bytes32 meta, uint amount) = request.unpackAllowance();

package/commands/admin/Appoint.sol

@@ -19,10 +19,13 @@ abstract contract Appoint is CommandBase, AdminEvent {
         emit Admin(host, appointId, NAME, "1:0:0", Schemas.Account, Keys.Empty, Keys.Empty, false, false);
     }
 
+    /// @notice Appoint each ACCOUNT block in the admin request as a guardian.
+    /// @param c Admin command context; `c.request` must contain ACCOUNT blocks.
+    /// @return Empty output state.
     function appoint(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, ) = Cursors.first(c.request, 1);
+        (Cur memory request, , ) = Cursors.init(c.request, 0, 1);
 
         while (request.i < request.len) {
             bytes32 account = request.unpackAccount();