@rootzero/contracts 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 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 `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 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`
+  blocks.
+
+### Changed
+
+- Updated the schema DSL documentation to allow any number of child blocks in
+  declaration order, including fixed fields before, after, or between child
+  blocks.
+
 ## 1.11.0
 
 ### Breaking Changes

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";
@@ -31,6 +33,7 @@ import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
 import { Dismiss } from "./commands/admin/Dismiss.sol";
 import { ExecutePayable } from "./commands/admin/Execute.sol";
 import { Label } from "./commands/admin/Label.sol";
+import { PublishSchema } from "./commands/admin/Schemas.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints

package/README.md

@@ -89,8 +89,8 @@ request built for an EVM host is byte-for-byte the request a CosmWasm or Solana
 port would parse; what differs per chain is how a host *resolves* the
 identifiers inside, never how the bytes are laid out.
 
-Schemas can express more than flat fields: a block may end in nested child
-blocks (`#bytes as payload` names a run of raw dynamic bytes), items can be
+Schemas can express more than flat fields: a block may contain any number of
+nested child blocks (`#bytes as payload` names raw dynamic bytes), items can be
 marked `maybe` (optional) or `many` (a list), and aliases and dotted field
 paths give off-chain tooling presentation names without changing a single byte
 on the wire. The full schema language is specified in
@@ -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();
 ```
@@ -332,7 +355,7 @@ bytes and produce the same output bytes for every endpoint.
 
 Admin commands use the regular command shape but are gated to the host's admin
 account: trust management (`authorize`, `unauthorize`), guardian management
-(`appoint`, `dismiss`), naming (`label`), asset gating (`allowAssets`,
+(`appoint`, `dismiss`), metadata (`label`, `publishSchema`), asset gating (`allowAssets`,
 `denyAssets`, `allowance`), lifecycle (`init`, `destroy`), and raw calls
 (`executePayable`). Guards go the other way: direct actions guardians can take
 without any command context — the default is `revoke`, which lets a guardian
@@ -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.
@@ -726,6 +843,19 @@ library Cursors {
         cur.ensureAt(end);
     }
 
+    /// @notice Consume a SCHEMA block and return its fields.
+    /// @param cur Cursor; advanced past the SCHEMA block.
+    /// @return key Block key being defined.
+    /// @return body Schema DSL string describing the block payload body.
+    /// @return name Optional block alias.
+    function unpackSchema(Cur memory cur) internal pure returns (bytes4 key, string memory body, bytes32 name) {
+        uint end = cur.enter(Keys.Schema, 36 + Sizes.Header, 0);
+        key = cur.read4();
+        body = cur.unpackString();
+        name = cur.read32();
+        cur.ensureAt(end);
+    }
+
     /// @notice Consume a dynamic block with a single bytes32 payload.
     /// @param cur Cursor; advanced past the block.
     /// @param key Expected dynamic block key.
@@ -1326,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,16 +7,6 @@ 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.
@@ -71,6 +61,8 @@ library Keys {
     bytes4 constant Bounty = bytes4(keccak256("#bounty"));
     /// @dev Mutable node label - (uint id, bytes32 namespace, #string as name)
     bytes4 constant Label = bytes4(keccak256("#label"));
+    /// @dev Block schema publication - (bytes4 key, #string as body, bytes32 name)
+    bytes4 constant Schema = bytes4(keccak256("#schema"));
 
     /// @dev Structural status form - (uint code)
     bytes4 constant Status = bytes4(keccak256("#status"));

package/blocks/Schema.sol

@@ -28,9 +28,9 @@ pragma solidity ^0.8.33;
 //   are offchain projection metadata only and do not change runtime encoding
 // - child blocks resolve by alias in the active schema context; unresolved aliases are invalid
 // - schema strings describe the payload body only; the `Block` event carries the alias
-// - fixed fields are packed in declaration order
-// - blocks have fixed fields followed by a dynamic child-block tail
-// - child block tails are embedded directly, without an extra stream wrapper
+// - items are encoded in declaration order
+// - fixed fields are packed inline and any number of child blocks are embedded directly
+// - child blocks may appear between fixed fields because each block carries its own length
 // - `#bytes` is a reserved child block that stores raw bytes and has no body
 // - `#string` is a reserved child block that stores UTF-8 string bytes and has no body
 // - generic lists use the stable key derived from `#list`
@@ -87,6 +87,7 @@ library Schemas {
     string constant Fee = "{ uint amount }";
     string constant Auth = "{ uint cid, uint deadline, #bytes as proof }";
     string constant Label = "{ uint id, bytes32 namespace, #string as name }";
+    string constant Schema = "{ bytes4 key, #string as body, bytes32 name }";
     string constant Bytes = "";
     string constant String = "";
     string constant List = "";

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,47 +3,35 @@ 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.
 abstract contract CreditAccount is CommandBase, CreditAccountHook {
     bytes32 private immutable descriptor;
-    uint private immutable id;
+    uint internal immutable creditAccountId;
 
     constructor() {
-        (id, descriptor) = command("creditAccount", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
-    }
-
-    /// @notice Return true if `candidate` is this command's credit account ID.
-    function isCreditAccount(uint candidate) internal view returns (bool) {
-        return candidate == id;
+        (creditAccountId, descriptor) = command("creditAccount", Keys.Balance, Keys.Empty, Keys.Empty, 0, 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.
+    /// @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 ("", "");
     }
 }