@rootzero/contracts 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -3,21 +3,47 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.13.0
+
+### Breaking Changes
+
+- Replaced the virtual `Pipeline.settle(bytes transactions)` stream hook with
+  decoded settlement through `Settlement`. Pipeline implementations now provide
+  `debitAccount` and `creditAccount` hooks, while the pipeline decodes each
+  returned TRANSACTION block and settles it before dispatching the next step.
+- Moved `DebitAccountHook` and `CreditAccountHook` from their command modules to
+  `core/Settlement.sol`. They remain available from the `Core.sol` and
+  `Endpoints.sol` package entry points.
+
+### Added
+
+- Added the memory-backed `Reader` and `Readers` block-stream API with balance
+  and transaction unpackers, bounds and block validation, and positive
+  iteration through `more()`.
+- Added the shared `Settlement` core mixin used by pipelines and `PortSettle` to
+  debit transaction sources and credit destinations.
+
+### Changed
+
+- Unified pipeline and port transaction handling through `Settlement`,
+  including zero-account handling and zero-amount no-op settlement.
+
 ## 1.12.0
 
 ### Breaking Changes
 
-- Removed the generic `EndpointBase.schema(...)` helper. Use
-  `localSchema(...)` for context-local endpoint schemas or emit `Schema`
-  directly for custom/named keys.
+- Removed `Keys.Local` and replaced `EndpointBase.localSchema(...)` with the
+  explicit `EndpointBase.schema(uint32 key, string body)` helper for
+  context-local endpoint schemas.
+- Changed `Introduction` to emit the receiving `host` and introduced `peer`:
+  `Introduction(uint indexed host, uint peer, uint blocknum)`.
 - Replaced `isDebitAccount`, `isCreditAccount`, `isAuthorize`, and
   `isUnauthorize` helper predicates with internal command ID fields:
   `debitAccountId`, `creditAccountId`, `authorizeId`, and `unauthorizeId`.
 
 ### Added
 
-- Added `Keys.Local` as the default context-local block key and added
-  `EndpointBase.localSchema(...)` helpers for publishing local endpoint
+- Added the `EndpointBase.schema(...)` helper for publishing local endpoint
   schemas.
 - Added the standard `#schema` block, `unpackSchema`, and an opt-in
   `publishSchema` admin command for emitting schema claims from `#schema`

package/Core.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports the core host, runtime, access, ledger, node-call, and validation layer.
+// Aggregator: re-exports the core host, runtime, access, ledger, settlement, pipeline, node-call, and validation layer.
 // Import this file to bring the full rootzero host base layer into scope.
 
 import { AccessControl } from "./core/Access.sol";
@@ -13,6 +13,7 @@ import { CommandCalls, FailedCall, NodeCalls, PortCalls } from "./core/Calls.sol
 import { EndpointBase, Lane } from "./core/Endpoint.sol";
 import { Payable } from "./core/Payable.sol";
 import { Pipeline } from "./core/Pipeline.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";

package/Cursors.sol

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all block stream primitives (Cursors, Writers, Schema, Keys, Sizes).
+// Aggregator: re-exports all block stream primitives (Cursors, Readers, Writers, Schema, Keys, Sizes).
 // Import this file to get access to the full block encoding/decoding surface in one import.
 
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Forms, Sizes } from "./blocks/Schema.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { Cursors, Cur } from "./blocks/Cursors.sol";
+import { Cursors, Cur, Readers, Reader } from "./blocks/Cursors.sol";
 import { Writer, Writers, Hints } from "./blocks/Writers.sol";
 
 

package/Endpoints.sol

@@ -9,11 +9,13 @@ 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";
+import { CreditAccountHook, DebitAccountHook } from "./core/Settlement.sol";
 
 // Commands
+import { Allocate, AllocateHook } from "./commands/Allocate.sol";
 import { Burn, BurnHook } from "./commands/Burn.sol";
-import { CreditAccount, CreditAccountHook } from "./commands/Credit.sol";
-import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
+import { CreditAccount } from "./commands/Credit.sol";
+import { DebitAccount } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";

package/README.md

@@ -121,7 +121,8 @@ const request = concat([
   encodeAmountBlock(usdc, 250_000_000n),
   encodeAmountBlock(dai, 250n * 10n ** 18n),
 ]);
-// deposit(request) returns two #balance blocks, one per #amount
+// deposit(request) returns two #balance blocks in its state output and an
+// empty transaction output
 ```
 
 Everything downstream keeps this shape: commands loop over request blocks,
@@ -216,6 +217,11 @@ struct CommandContext {
 }
 ```
 
+Every command returns two block streams: `state`, which is threaded into the
+next pipeline step, and `transactions`, which contains `#transaction` blocks
+for the pipeline host to settle outside the state lane. Either stream may be
+empty.
+
 The input carries instructions; the state carries live value. While a
 sequence of commands executes, `#balance` and `#custody` blocks in the state
 are the funds being moved — produced by one command, consumed by the next.
@@ -224,7 +230,9 @@ The standard `Deposit` mixin shows the canonical shape — open the input,
 loop the batch, call the hook, write the output run:
 
 ```solidity
-function deposit(CommandContext calldata c) external onlyCommand returns (bytes memory) {
+function deposit(
+    CommandContext calldata c
+) external onlyCommand returns (bytes memory, bytes memory) {
     (Cur memory input, uint outputs) = openInput(c.input, descriptor);
     Writer memory output = Writers.allocBalances(outputs);
 
@@ -234,7 +242,7 @@ function deposit(CommandContext calldata c) external onlyCommand returns (bytes
         output.appendBalance(asset, amount);
     }
 
-    return output.finish();
+    return (output.finish(), "");
 }
 ```
 
@@ -250,8 +258,10 @@ abstract contract MyCommand is CommandBase {
         (, descriptor) = command("myCommand", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
     }
 
-    function myCommand(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        // parse c.input, loop, return the output state run
+    function myCommand(
+        CommandContext calldata c
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        // parse c.input, loop, return the output state run and any transactions
     }
 }
 ```
@@ -259,8 +269,9 @@ abstract contract MyCommand is CommandBase {
 The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
-state to other accounts), `provision` (allocate custody on another host), and
-`relayPayable` (hand a pipeline to another portal).
+state to other accounts), `allocate` (turn balance state into custody),
+`provision` (provision custody from an external allocation), and `relayPayable`
+(hand a pipeline to another portal).
 
 ## Pipelines
 
@@ -272,14 +283,26 @@ step { uint target, uint resources, #bytes as request }
 ```
 
 Each step names a target command, the resources it may spend, and its request.
-The state threads through: whatever one command returns becomes the input
-state of the next, and the final state must be empty. This is the core of
-`Pipeline.pipe`:
+The returned state threads into the next command and the final state must be
+empty. Returned transactions do not enter the state lane; the pipeline passes
+each decoded transaction to the shared settlement implementation before
+running the next step. This is the core of `Pipeline.pipe`:
 
 ```solidity
 while (input.i < input.len) {
     (uint target, uint resources, bytes calldata request) = input.unpackStep();
-    state = dispatch(target, account, state, request, useValue(budget, resources));
+    Reader memory transactions;
+    (state, transactions.source) = dispatch(
+        target,
+        account,
+        state,
+        request,
+        useValue(budget, resources)
+    );
+    while (transactions.more()) {
+        (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
+        settle(from, to, asset, amount);
+    }
 }
 if (state.length != 0) revert UnexpectedState();
 ```
@@ -353,11 +376,11 @@ names, access sets, balances — from logs alone, with no artifact files.
 Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
-  `Pipeline`, `Portal`, validator
+  `Settlement`, `Pipeline`, `Portal`, validator
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
   mixins and their hooks
-- `@rootzero/contracts/Cursors.sol` — `Cur` cursor reader, `Writers`, `Schemas`,
-  `Keys`
+- `@rootzero/contracts/Cursors.sol` — calldata `Cur`/`Cursors`, memory
+  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts

package/blocks/Cursors.sol

@@ -17,7 +17,109 @@ struct Cur {
     uint len;
 }
 
+/// @notice Mutable reader over a block stream stored in memory.
+/// All positions (`i`) are byte offsets relative to the start of `source`.
+struct Reader {
+    /// @dev Current read position, relative to the source start.
+    uint i;
+    /// @dev Memory bytes containing the complete source region.
+    bytes source;
+}
+
 using Cursors for Cur;
+using Readers for Reader;
+
+/// @title Readers
+/// @notice Memory block stream parser for the rootzero protocol.
+/// A `Reader` advances through an existing `bytes memory` source without copying its contents.
+/// Blocks are encoded as `[bytes4 key][bytes4 payloadLen][payload]`.
+library Readers {
+    /// @dev The current block has a truncated header or payload, an unexpected key,
+    ///      or a payload size outside the accepted range.
+    error InvalidBlock();
+
+    /// @notice Create a reader backed by a memory byte array.
+    /// @param source Memory bytes containing the block stream.
+    /// @return cur Reader positioned at the beginning of `source`.
+    function open(bytes memory source) internal pure returns (Reader memory cur) {
+        cur.source = source;
+    }
+
+    /// @notice Return whether the reader has consumed its entire source.
+    /// @param cur Reader whose position should be checked.
+    /// @return Whether `cur.i` equals the source length.
+    function done(Reader memory cur) internal pure returns (bool) {
+        return cur.i == cur.source.length;
+    }
+
+    /// @notice Return whether the reader has bytes left to consume.
+    /// @param cur Reader whose position should be checked.
+    /// @return Whether `cur.i` differs from the source length.
+    function more(Reader memory cur) internal pure returns (bool) {
+        return cur.i != cur.source.length;
+    }
+
+    /// @notice Validate and consume the current block, advancing `cur.i` past it.
+    /// @param cur Reader to advance.
+    /// @param key Expected block key.
+    /// @param min Minimum payload length.
+    /// @param max Maximum payload length; zero means unbounded.
+    /// @return abs Absolute memory address of the payload start.
+    function consume(
+        Reader memory cur,
+        bytes4 key,
+        uint min,
+        uint max
+    ) internal pure returns (uint abs) {
+        bytes memory source = cur.source;
+        uint i = cur.i;
+
+        if (i > source.length || source.length - i < Sizes.Header) revert InvalidBlock();
+
+        bytes4 current;
+        uint len;
+        assembly ("memory-safe") {
+            let header := mload(add(add(source, 0x20), i))
+            current := header
+            len := and(shr(192, header), 0xffffffff)
+            abs := add(add(source, 0x28), i)
+        }
+
+        if (current != key || len < min || (max != 0 && len > max)) revert InvalidBlock();
+        if (len > source.length - i - Sizes.Header) revert InvalidBlock();
+        cur.i = i + Sizes.Header + len;
+    }
+
+    /// @notice Consume a BALANCE block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return asset Asset identifier.
+    /// @return amount Token amount.
+    function unpackBalance(Reader memory cur) internal pure returns (bytes32 asset, uint amount) {
+        uint abs = consume(cur, Keys.Balance, 64, 64);
+        assembly ("memory-safe") {
+            asset := mload(abs)
+            amount := mload(add(abs, 0x20))
+        }
+    }
+
+    /// @notice Consume a TRANSACTION block and return its fields.
+    /// @param cur Reader; advanced past the block.
+    /// @return from Source account identifier.
+    /// @return to Destination account identifier.
+    /// @return asset Asset identifier.
+    /// @return amount Token amount.
+    function unpackTransaction(
+        Reader memory cur
+    ) internal pure returns (bytes32 from, bytes32 to, bytes32 asset, uint amount) {
+        uint abs = consume(cur, Keys.Transaction, 128, 128);
+        assembly ("memory-safe") {
+            from := mload(abs)
+            to := mload(add(abs, 0x20))
+            asset := mload(add(abs, 0x40))
+            amount := mload(add(abs, 0x60))
+        }
+    }
+}
 
 /// @title Cursors
 /// @notice Calldata block stream parser for the rootzero protocol.
@@ -493,6 +595,21 @@ library Cursors {
         return createBlock96(Keys.Custody, bytes32(host), asset, bytes32(amount));
     }
 
+    /// @notice Encode a TRANSACTION block.
+    /// @param from Source account identifier.
+    /// @param to Destination account identifier.
+    /// @param asset Asset identifier.
+    /// @param amount Transfer amount.
+    /// @return Encoded TRANSACTION block bytes.
+    function toTransactionBlock(
+        bytes32 from,
+        bytes32 to,
+        bytes32 asset,
+        uint amount
+    ) internal pure returns (bytes memory) {
+        return createBlock128(Keys.Transaction, from, to, asset, bytes32(amount));
+    }
+
     /// @notice Encode a STEP block.
     /// @param target Command target identifier.
     /// @param resources Packed resources assigned to the step.
@@ -1339,6 +1456,18 @@ library Cursors {
     // Transform helpers
     // -------------------------------------------------------------------------
 
+    /// @notice Consume a BALANCE block and scope its amount to a host.
+    /// @param cur Cursor; advanced past the BALANCE block.
+    /// @param host Host node ID to attach to the decoded balance.
+    /// @return value Host-scoped balance amount.
+    function unpackBalanceForHost(
+        Cur memory cur,
+        uint host
+    ) internal pure returns (HostAmount memory value) {
+        value.host = host;
+        (value.asset, value.amount) = cur.unpackBalance();
+    }
+
     /// @notice Consume a RELAY block and encode its destination context payload.
     /// @param cur Cursor; advanced past the RELAY block.
     /// @param account Account identifier to embed in the destination context.

package/blocks/Keys.sol

@@ -7,22 +7,10 @@ pragma solidity ^0.8.33;
 /// Custom block keys only need to be unique in the context where they are used;
 /// hosts may publish custom key meanings with the `Schema` event.
 library Keys {
-    /// @notice Create a context-local block key.
-    /// @dev Local keys are opaque tags for host- or endpoint-specific schemas.
-    /// The caller is responsible for choosing values that are unique in the
-    /// context where they are used and publishing their meaning with `Schema`.
-    /// @param value Opaque local key value.
-    /// @return Context-local block key.
-    function local(uint32 value) internal pure returns (bytes4) {
-        return bytes4(value);
-    }
-
     /// @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 Default context-local block key for hosts/endpoints that need one custom schema.
-    bytes4 constant Local = bytes4(uint32(1));
     /// @dev Input amount - (bytes32 asset, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)

package/blocks/Writers.sol

@@ -993,19 +993,27 @@ library Writers {
         appendCustody(writer, value.host, value.asset, value.amount);
     }
 
+    /// @notice Append a TRANSACTION block using separate field values.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Transaction`.
+    /// @param from Source account identifier.
+    /// @param to Destination account identifier.
+    /// @param asset Asset identifier.
+    /// @param amount Transfer amount.
+    function appendTransaction(
+        Writer memory writer,
+        bytes32 from,
+        bytes32 to,
+        bytes32 asset,
+        uint amount
+    ) internal pure {
+        appendBlock128(writer, Keys.Transaction, from, to, asset, bytes32(amount), 32);
+    }
+
     /// @notice Append a TRANSACTION block from a struct.
     /// @param writer Destination writer; `i` is advanced by `Sizes.Transaction`.
     /// @param value Transfer record fields to encode.
     function appendTransaction(Writer memory writer, Tx memory value) internal pure {
-        appendBlock128(
-            writer,
-            Keys.Transaction,
-            bytes32(value.from),
-            bytes32(value.to),
-            value.asset,
-            bytes32(value.amount),
-            32
-        );
+        appendTransaction(writer, value.from, value.to, value.asset, value.amount);
     }
 
     // -------------------------------------------------------------------------

package/commands/Allocate.sol

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandContext, CommandBase, Keys} from "./Base.sol";
+import {HostAmount, Cursors, Cur, Writer, Writers} from "../Cursors.sol";
+
+using Cursors for Cur;
+using Writers for Writer;
+
+/// @notice Shared allocation hook used by `Allocate`.
+abstract contract AllocateHook {
+    /// @notice Override to allocate a live balance into custody on a host.
+    /// Called once per paired BALANCE state block and NODE request block.
+    /// Implementations should perform only the custody side effect; output
+    /// blocks are written by the caller.
+    /// @param account Caller's account identifier.
+    /// @param custody Host-scoped amount to allocate into custody.
+    function allocate(bytes32 account, HostAmount memory custody) internal virtual;
+}
+
+/// @title Allocate
+/// @notice Command that allocates BALANCE state to custody on requested hosts.
+/// Each BALANCE state block is paired with one NODE request block at the same
+/// position; the output is a matching CUSTODY state stream.
+abstract contract Allocate is CommandBase, AllocateHook {
+    bytes32 private immutable descriptor;
+
+    constructor() {
+        (, descriptor) = command("allocate", Keys.Balance, Keys.Node, Keys.Custody, 0, false, false);
+    }
+
+    /// @notice Allocate BALANCE state blocks to matching NODE request blocks.
+    /// @param c Command context; `c.state` must contain BALANCE blocks and
+    /// `c.input` must contain the same number of NODE blocks.
+    /// @return CUSTODY block stream matching the allocated balances.
+    /// @return Empty transaction stream.
+    function allocate(CommandContext calldata c) external onlyCommand returns (bytes memory, bytes memory) {
+        (Cur memory input, Cur memory state, uint outputs) = openCommand(c, descriptor);
+        Writer memory output = Writers.allocCustodies(outputs);
+
+        while (state.i < state.len) {
+            HostAmount memory custody = state.unpackBalanceForHost(input.unpackNode());
+            allocate(c.account, custody);
+            output.appendCustody(custody);
+        }
+
+        return (output.finish(), "");
+    }
+}

package/commands/Burn.sol

@@ -28,14 +28,15 @@ abstract contract Burn is CommandBase, BurnHook {
     /// @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) {
+    /// @return Empty transaction stream.
+    function burn(CommandContext calldata c) external onlyCommand returns (bytes memory, bytes memory) {
         (Cur memory state, ) = openState(c.state, descriptor);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();
             burn(c.account, asset, amount);
         }
-        return "";
+        return ("", "");
     }
 }
 

package/commands/Credit.sol

@@ -3,18 +3,10 @@ pragma solidity ^0.8.33;
 
 import { CommandBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur } from "../Cursors.sol";
+import { CreditAccountHook } from "../core/Settlement.sol";
 
 using Cursors for Cur;
 
-abstract contract CreditAccountHook {
-    /// @notice Override to credit externally managed funds to `account`.
-    /// Called once per BALANCE block in state.
-    /// @param account Destination account identifier.
-    /// @param asset Asset identifier.
-    /// @param amount Amount to credit.
-    function creditAccount(bytes32 account, bytes32 asset, uint amount) internal virtual;
-}
-
 /// @title CreditAccount
 /// @notice Command that delivers BALANCE state blocks to an account via a virtual hook.
 /// Use for internally recording credits that have already been settled externally.
@@ -29,16 +21,17 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     /// @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.
+    /// @return Empty transaction stream.
     function creditAccount(
         CommandContext calldata c
-    ) external onlyCommand returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory, bytes memory) {
         (Cur memory state, ) = openState(c.state, descriptor);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();
             creditAccount(c.account, asset, amount);
         }
-        return "";
+        return ("", "");
     }
 }
 

package/commands/Debit.sol

@@ -3,19 +3,11 @@ pragma solidity ^0.8.33;
 
 import { CommandContext, CommandBase, Keys } from "./Base.sol";
 import { Cursors, Cur, Writer, Writers } from "../Cursors.sol";
+import { DebitAccountHook } from "../core/Settlement.sol";
 
 using Cursors for Cur;
 using Writers for Writer;
 
-abstract contract DebitAccountHook {
-    /// @notice Override to debit externally managed funds from `account`.
-    /// Called once per AMOUNT block before a matching BALANCE is emitted.
-    /// @param account Source account identifier.
-    /// @param asset Asset identifier.
-    /// @param amount Amount to debit.
-    function debitAccount(bytes32 account, bytes32 asset, uint amount) internal virtual;
-}
-
 /// @title DebitAccount
 /// @notice Command that deducts AMOUNT blocks from an account and emits matching BALANCE state.
 /// Use for internally recording debits. The virtual `debitAccount` hook is called once per
@@ -47,10 +39,11 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     /// @notice Debit AMOUNT request blocks from the command account and output matching BALANCE blocks.
     /// @param c Command context; `c.input` must contain AMOUNT blocks.
     /// @return BALANCE block stream matching the debited amounts.
+    /// @return Empty transaction stream.
     function debitAccount(
         CommandContext calldata c
-    ) external onlyCommand returns (bytes memory) {
-        return debitAccount(c.account, c.input);
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        return (debitAccount(c.account, c.input), "");
     }
 }
 

package/commands/Deposit.sol

@@ -44,9 +44,10 @@ abstract contract Deposit is CommandBase, DepositHook {
     /// @notice Deposit AMOUNT request blocks into the command account and output matching BALANCE blocks.
     /// @param c Command context; `c.input` must contain AMOUNT blocks.
     /// @return BALANCE block stream matching the deposited amounts.
+    /// @return Empty transaction stream.
     function deposit(
         CommandContext calldata c
-    ) external onlyCommand returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory, bytes memory) {
         (Cur memory input, uint outputs) = openInput(c.input, descriptor);
         Writer memory output = Writers.allocBalances(outputs);
 
@@ -56,7 +57,7 @@ abstract contract Deposit is CommandBase, DepositHook {
             output.appendBalance(asset, amount);
         }
 
-        return output.finish();
+        return (output.finish(), "");
     }
 }
 
@@ -73,9 +74,10 @@ abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
     /// @notice Deposit AMOUNT request blocks with access to a mutable native-value budget.
     /// @param c Command context; `c.input` must contain AMOUNT blocks.
     /// @return BALANCE block stream matching the deposited amounts.
+    /// @return Remaining native value as a refund transaction stream.
     function depositPayable(
         CommandContext calldata c
-    ) external payable onlyCommand returns (bytes memory) {
+    ) external payable onlyCommand returns (bytes memory, bytes memory) {
         (Cur memory input, uint outputs) = openInput(c.input, descriptor);
         Writer memory output = Writers.allocBalances(outputs);
         Budget memory budget = openValue();
@@ -86,8 +88,7 @@ abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
             output.appendBalance(asset, amount);
         }
 
-        closeValue(c.account, budget);
-        return output.finish();
+        return (output.finish(), closeValue(budget, c.account));
     }
 }
 

package/commands/Payout.sol

@@ -29,13 +29,14 @@ abstract contract Payout is CommandBase, PayoutHook {
     /// @notice Pay out BALANCE state blocks to matching ACCOUNT request blocks.
     /// @param c Command context; `c.state` must contain BALANCE blocks and `c.input` matching ACCOUNT blocks.
     /// @return Empty output state.
-    function payout(CommandContext calldata c) external onlyCommand returns (bytes memory) {
+    /// @return Empty transaction stream.
+    function payout(CommandContext calldata c) external onlyCommand returns (bytes memory, bytes memory) {
         (Cur memory input, Cur memory state, ) = openCommand(c, descriptor);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();
             payout(c.account, input.unpackAccount(), asset, amount);
         }
-        return "";
+        return ("", "");
     }
 }