@rootzero/contracts 0.2.0 → 0.4.0

package/blocks/Writers.sol

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { AssetAmount, HostAmount, Tx, Keys, Sizes } from "./Schema.sol";
+
+/// @notice Sequential block stream writer backed by a pre-allocated memory buffer.
+struct Writer {
+    /// @dev Current write position: number of bytes written so far.
+    uint i;
+    /// @dev Allocated buffer capacity in bytes.
+    uint end;
+    /// @dev Destination buffer; final length is set to `i` by `finish`.
+    bytes dst;
+}
+
+// Fixed-point scaling denominator for output-count allocation.
+// A `scaledRatio` of `ALLOC_SCALE` means 1:1 (one output block per input block).
+// `2 * ALLOC_SCALE` means 2:1; non-integer ratios revert with `BadWriterRatio`.
+uint constant ALLOC_SCALE = 10_000;
+
+/// @title Writers
+/// @notice Response block stream builder for the rootzero protocol.
+/// Allocates a fixed-size memory buffer up front and writes binary-encoded
+/// blocks into it sequentially. Call `finish` to trim the buffer to the
+/// number of bytes actually written and return the result.
+library Writers {
+    /// @dev `append` or a `write*` function tried to write past the end of `dst`.
+    error WriterOverflow();
+    /// @dev `finish` called with a writer whose `i` exceeds `dst.length`.
+    error IncompleteWriter();
+    /// @dev An alloc function received a zero count, or `finish` found no bytes written.
+    error EmptyRequest();
+    /// @dev Block payload length exceeds `uint32` max; cannot be encoded in the 4-byte header field.
+    error BlockLengthOverflow();
+    /// @dev `scaledRatio * count` is not evenly divisible by `ALLOC_SCALE`.
+    error BadWriterRatio();
+
+    // -------------------------------------------------------------------------
+    // Header encoding
+    // -------------------------------------------------------------------------
+
+    /// @notice Encode an 8-byte block header into a single uint for efficient `mstore`.
+    /// The header occupies the most-significant 8 bytes; the payload starts at `offset + 8`.
+    /// @param key Four-byte block type identifier.
+    /// @param len Payload byte length.
+    /// @return Packed header as a uint (key in bits [255:224], len in bits [223:192]).
+    function toBlockHeader(bytes4 key, uint len) internal pure returns (uint) {
+        if (len > type(uint32).max) revert BlockLengthOverflow();
+        return (uint(uint32(key)) << 224) | (uint(uint32(len)) << 192);
+    }
+
+    // -------------------------------------------------------------------------
+    // Allocation
+    // -------------------------------------------------------------------------
+
+    /// @notice Allocate a writer with an exact byte capacity.
+    /// @param len Number of bytes to pre-allocate.
+    /// @return writer Freshly allocated writer positioned at index 0.
+    function alloc(uint len) internal pure returns (Writer memory writer) {
+        writer = Writer({i: 0, end: len, dst: new bytes(len)});
+    }
+
+    /// @notice Append arbitrary bytes to the writer.
+    /// @param writer Destination writer; `i` is advanced by `data.length`.
+    /// @param data Bytes to append.
+    function append(Writer memory writer, bytes memory data) internal pure {
+        uint next = writer.i + data.length;
+        if (next > writer.dst.length) revert WriterOverflow();
+        // Copy `data` into `dst` starting at the current write position.
+        assembly ("memory-safe") {
+            mcopy(add(add(mload(add(writer, 0x40)), 0x20), mload(writer)), add(data, 0x20), mload(data))
+        }
+        writer.i = next;
+    }
+
+    /// @notice Allocate a writer sized for exactly `count` BALANCE blocks (1:1 ratio).
+    /// @param count Number of balance blocks to allocate space for.
+    /// @return writer Allocated writer.
+    function allocBalances(uint count) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.Balance);
+    }
+
+    /// @notice Allocate a writer sized for `2 * count` BALANCE blocks (2:1 ratio).
+    /// Used when each input produces a paired output (e.g. input balance + output balance).
+    /// @param count Number of input blocks; output capacity is doubled.
+    /// @return writer Allocated writer.
+    function allocPairedBalances(uint count) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, ALLOC_SCALE * 2, Sizes.Balance);
+    }
+
+    /// @notice Allocate a writer for BALANCE blocks with a custom output-to-input ratio.
+    /// @param count Number of input blocks.
+    /// @param scaledRatio Output count multiplier expressed in `ALLOC_SCALE` units
+    ///        (e.g. `ALLOC_SCALE` = 1:1, `2 * ALLOC_SCALE` = 2:1).
+    /// @return writer Allocated writer.
+    function allocScaledBalances(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, scaledRatio, Sizes.Balance);
+    }
+
+    /// @notice Allocate a writer sized for exactly `count` TRANSACTION blocks (1:1 ratio).
+    /// @param count Number of transaction blocks to allocate space for.
+    /// @return writer Allocated writer.
+    function allocTxs(uint count) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.Transaction);
+    }
+
+    /// @notice Allocate a writer sized for exactly `count` CUSTODY blocks (1:1 ratio).
+    /// @param count Number of custody blocks to allocate space for.
+    /// @return writer Allocated writer.
+    function allocCustodies(uint count) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, ALLOC_SCALE, Sizes.Custody);
+    }
+
+    /// @notice Allocate a writer for CUSTODY blocks with a custom output-to-input ratio.
+    /// @param count Number of input blocks.
+    /// @param scaledRatio Output count multiplier in `ALLOC_SCALE` units.
+    /// @return writer Allocated writer.
+    function allocScaledCustodies(uint count, uint scaledRatio) internal pure returns (Writer memory writer) {
+        return allocFromScaledCount(count, scaledRatio, Sizes.Custody);
+    }
+
+    /// @notice Core allocation routine used by all typed `alloc*` helpers.
+    /// Computes `(count * scaledRatio / ALLOC_SCALE) * blockLen` and allocates that many bytes.
+    /// @param count Number of input blocks.
+    /// @param scaledRatio Output-to-input ratio in `ALLOC_SCALE` units.
+    /// @param blockLen Byte size of each output block (including 8-byte header).
+    /// @return writer Allocated writer.
+    function allocFromScaledCount(
+        uint count,
+        uint scaledRatio,
+        uint blockLen
+    ) internal pure returns (Writer memory writer) {
+        if (count == 0) revert EmptyRequest();
+        uint scaledCount = count * scaledRatio;
+        if (scaledCount % ALLOC_SCALE != 0) revert BadWriterRatio();
+        uint len = (scaledCount / ALLOC_SCALE) * blockLen;
+        writer = Writer({i: 0, end: len, dst: new bytes(len)});
+    }
+
+    // -------------------------------------------------------------------------
+    // Low-level write helpers (direct index into a bytes buffer)
+    // -------------------------------------------------------------------------
+
+    /// @notice Write a BALANCE block directly into `dst` at byte offset `i`.
+    /// @param dst Destination buffer; must have at least `i + Sizes.Balance` bytes.
+    /// @param i Write offset within `dst`.
+    /// @param value Balance fields to encode.
+    /// @return next Byte offset immediately after the written block.
+    function writeBalanceBlock(bytes memory dst, uint i, AssetAmount memory value) internal pure returns (uint next) {
+        next = i + Sizes.Balance;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Balance, 96);
+        // Write 8-byte header then three 32-byte payload words.
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x08), mload(value))
+            mstore(add(p, 0x28), mload(add(value, 0x20)))
+            mstore(add(p, 0x48), mload(add(value, 0x40)))
+        }
+    }
+
+    /// @notice Append a BALANCE block using separate field values.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Balance`.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Token amount.
+    function appendBalance(Writer memory writer, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        appendBalance(writer, AssetAmount(asset, meta, amount));
+    }
+
+    /// @notice Append a BALANCE block from a struct.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Balance`.
+    /// @param value Balance fields to encode.
+    function appendBalance(Writer memory writer, AssetAmount memory value) internal pure {
+        writer.i = writeBalanceBlock(writer.dst, writer.i, value);
+    }
+
+    /// @notice Append a BALANCE block only if `amount > 0`; silently skips zero amounts.
+    /// @param writer Destination writer.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Token amount; block is not written if this is zero.
+    function appendNonZeroBalance(Writer memory writer, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        if (amount > 0) appendBalance(writer, asset, meta, amount);
+    }
+
+    /// @notice Append a BALANCE block from a struct only if the amount is non-zero.
+    /// @param writer Destination writer.
+    /// @param value Balance fields; block is not written if `value.amount == 0`.
+    function appendNonZeroBalance(Writer memory writer, AssetAmount memory value) internal pure {
+        if (value.amount > 0) appendBalance(writer, value);
+    }
+
+    /// @notice Write a BOUNTY block directly into `dst` at byte offset `i`.
+    /// @param dst Destination buffer; must have at least `i + Sizes.Bounty` bytes.
+    /// @param i Write offset within `dst`.
+    /// @param amount Relayer reward amount.
+    /// @param relayer Relayer account identifier.
+    /// @return next Byte offset immediately after the written block.
+    function writeBountyBlock(bytes memory dst, uint i, uint amount, bytes32 relayer) internal pure returns (uint next) {
+        next = i + Sizes.Bounty;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Bounty, 64);
+        // Write 8-byte header then amount and relayer.
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x08), amount)
+            mstore(add(p, 0x28), relayer)
+        }
+    }
+
+    /// @notice Append a BOUNTY block to the writer.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Bounty`.
+    /// @param amount Relayer reward amount.
+    /// @param relayer Relayer account identifier.
+    function appendBounty(Writer memory writer, uint amount, bytes32 relayer) internal pure {
+        writer.i = writeBountyBlock(writer.dst, writer.i, amount, relayer);
+    }
+
+    /// @notice Write a CUSTODY block directly into `dst` at byte offset `i`.
+    /// @param dst Destination buffer; must have at least `i + Sizes.Custody` bytes.
+    /// @param i Write offset within `dst`.
+    /// @param value Custody fields to encode.
+    /// @return next Byte offset immediately after the written block.
+    function writeCustodyBlock(bytes memory dst, uint i, HostAmount memory value) internal pure returns (uint next) {
+        next = i + Sizes.Custody;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Custody, 128);
+        // Write 8-byte header then four 32-byte payload words.
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x08), mload(value))
+            mstore(add(p, 0x28), mload(add(value, 0x20)))
+            mstore(add(p, 0x48), mload(add(value, 0x40)))
+            mstore(add(p, 0x68), mload(add(value, 0x60)))
+        }
+    }
+
+    /// @notice Append a CUSTODY block using separate field values.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Custody`.
+    /// @param host Host node ID.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Token amount.
+    function appendCustody(Writer memory writer, uint host, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        appendCustody(writer, HostAmount(host, asset, meta, amount));
+    }
+
+    /// @notice Append a CUSTODY block from a struct.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Custody`.
+    /// @param value Custody fields to encode.
+    function appendCustody(Writer memory writer, HostAmount memory value) internal pure {
+        writer.i = writeCustodyBlock(writer.dst, writer.i, value);
+    }
+
+    /// @notice Write a TRANSACTION block directly into `dst` at byte offset `i`.
+    /// @param dst Destination buffer; must have at least `i + Sizes.Transaction` bytes.
+    /// @param i Write offset within `dst`.
+    /// @param value Transaction fields to encode.
+    /// @return next Byte offset immediately after the written block.
+    function writeTxBlock(bytes memory dst, uint i, Tx memory value) internal pure returns (uint next) {
+        next = i + Sizes.Transaction;
+        if (next > dst.length) revert WriterOverflow();
+        uint header = toBlockHeader(Keys.Transaction, 160);
+        // Write 8-byte header then five 32-byte payload words.
+        assembly ("memory-safe") {
+            let p := add(add(dst, 0x20), i)
+            mstore(p, header)
+            mstore(add(p, 0x08), mload(value))
+            mstore(add(p, 0x28), mload(add(value, 0x20)))
+            mstore(add(p, 0x48), mload(add(value, 0x40)))
+            mstore(add(p, 0x68), mload(add(value, 0x60)))
+            mstore(add(p, 0x88), mload(add(value, 0x80)))
+        }
+    }
+
+    /// @notice Append a TRANSACTION block from a struct.
+    /// @param writer Destination writer; `i` is advanced by `Sizes.Transaction`.
+    /// @param value Transaction fields to encode.
+    function appendTx(Writer memory writer, Tx memory value) internal pure {
+        writer.i = writeTxBlock(writer.dst, writer.i, value);
+    }
+
+    // -------------------------------------------------------------------------
+    // Finalisation
+    // -------------------------------------------------------------------------
+
+    /// @notice Trim `dst` to the number of bytes actually written and return it.
+    /// Sets the `bytes` length slot in memory to `writer.i` without copying.
+    /// @param writer Completed writer.
+    /// @return out The written block stream; length equals `writer.i`.
+    function finish(Writer memory writer) internal pure returns (bytes memory out) {
+        if (writer.i == 0) revert EmptyRequest();
+        if (writer.i > writer.dst.length) revert IncompleteWriter();
+        out = writer.dst;
+        // Overwrite the memory length word of `out` with the actual written length.
+        assembly ("memory-safe") {
+            mstore(out, mload(writer))
+        }
+    }
+}

package/commands/Base.sol

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {OperationBase} from "../core/Operation.sol";
+import {Cur} from "../Cursors.sol";
+import {CommandEvent} from "../events/Command.sol";
+import {State} from "../utils/State.sol";
+import {Ids, Selectors} from "../utils/Ids.sol";
+
+/// @notice Execution context passed to every command invocation.
+struct CommandContext {
+    /// @dev Destination command node ID; zero means "any command on this host".
+    uint target;
+    /// @dev Caller's account identifier.
+    bytes32 account;
+    /// @dev Current state block stream (previous command output or initial state).
+    bytes state;
+    /// @dev Input block stream for this invocation.
+    bytes request;
+}
+
+/// @title CommandBase
+/// @notice Abstract base for all rootzero command contracts.
+/// Provides access control modifiers, event emission, and the `commandId`
+/// helper used to derive stable identifiers for named commands.
+abstract contract CommandBase is OperationBase, CommandEvent {
+    /// @dev Thrown when `onlyActive` finds that `deadline` has already passed.
+    error Expired();
+    /// @dev Thrown when `onlyAdmin` finds that `account` is not the admin account.
+    error NotAdmin();
+    /// @dev Thrown when `onlyCommand` finds that `target` does not match this command's ID.
+    error UnexpectedEndpoint();
+
+    /// @dev Restrict execution to calls where `account` is the host's admin account.
+    modifier onlyAdmin(bytes32 account) {
+        if (account != adminAccount) revert NotAdmin();
+        _;
+    }
+
+    /// @dev Restrict execution to trusted callers targeting this specific command.
+    /// A zero `target` is treated as a wildcard and matches any command.
+    /// @param cid This command's node ID (from `commandId`).
+    /// @param target Requested destination from the `CommandContext`.
+    modifier onlyCommand(uint cid, uint target) {
+        if (target != 0 && target != cid) revert UnexpectedEndpoint();
+        enforceCaller(msg.sender);
+        _;
+    }
+
+    /// @dev Restrict execution to invocations where `deadline` is in the future.
+    /// @param deadline Unix timestamp after which the invocation is considered expired.
+    modifier onlyActive(uint deadline) {
+        if (deadline < block.timestamp) revert Expired();
+        _;
+    }
+
+    /// @notice Derive the deterministic node ID for a named command on this contract.
+    /// The ID encodes the ABI selector of `name((uint256,bytes32,bytes,bytes))` and
+    /// `address(this)`, making it unique per (function name, contract address) pair.
+    /// @param name Command function name (without argument list).
+    /// @return Command node ID.
+    function commandId(string memory name) internal view returns (uint) {
+        return Ids.toCommand(Selectors.command(name), address(this));
+    }
+}

package/commands/Borrow.sol

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, State } from "./Base.sol";
+import { AssetAmount, HostAmount, Cur, Cursors, Writer, Writers } from "../Cursors.sol";
+
+string constant BABTB = "borrowAgainstBalanceToBalance";
+string constant BACTB = "borrowAgainstCustodyToBalance";
+
+using Cursors for Cur;
+using Writers for Writer;
+
+/// @title BorrowAgainstCustodyToBalance
+/// @notice Command that issues loans against CUSTODY state positions, emitting BALANCE outputs.
+abstract contract BorrowAgainstCustodyToBalance is CommandBase {
+    uint internal immutable borrowAgainstCustodyToBalanceId = commandId(BACTB);
+
+    constructor(string memory input) {
+        emit Command(host, BACTB, input, borrowAgainstCustodyToBalanceId, State.Custodies, State.Balances);
+    }
+
+    /// @dev Override to borrow against a custody position.
+    /// `request` is the live auxiliary request cursor for this command;
+    /// implementations validate and unpack it as needed.
+    function borrowAgainstCustodyToBalance(
+        bytes32 account,
+        HostAmount memory custody,
+        Cur memory request
+    ) internal virtual returns (AssetAmount memory);
+
+    function borrowAgainstCustodyToBalance(
+        CommandContext calldata c
+    ) external payable onlyCommand(borrowAgainstCustodyToBalanceId, c.target) returns (bytes memory) {
+        (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
+        Cur memory request = cursor(c.request);
+        Writer memory writer = Writers.allocBalances(stateCount);
+
+        while (state.i < state.bound) {
+            HostAmount memory custody = state.unpackCustodyValue();
+            AssetAmount memory out = borrowAgainstCustodyToBalance(c.account, custody, request);
+            writer.appendNonZeroBalance(out);
+        }
+
+        return state.complete(writer);
+    }
+}
+
+/// @title BorrowAgainstBalanceToBalance
+/// @notice Command that issues loans against BALANCE state positions, emitting BALANCE outputs.
+abstract contract BorrowAgainstBalanceToBalance is CommandBase {
+    uint internal immutable borrowAgainstBalanceToBalanceId = commandId(BABTB);
+
+    constructor(string memory input) {
+        emit Command(host, BABTB, input, borrowAgainstBalanceToBalanceId, State.Balances, State.Balances);
+    }
+
+    /// @dev Override to borrow against a balance position.
+    /// `request` is the live auxiliary request cursor for this command;
+    /// implementations validate and unpack it as needed.
+    function borrowAgainstBalanceToBalance(
+        bytes32 account,
+        AssetAmount memory balance,
+        Cur memory request
+    ) internal virtual returns (AssetAmount memory);
+
+    function borrowAgainstBalanceToBalance(
+        CommandContext calldata c
+    ) external payable onlyCommand(borrowAgainstBalanceToBalanceId, c.target) returns (bytes memory) {
+        (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
+        Cur memory request = cursor(c.request);
+        Writer memory writer = Writers.allocBalances(stateCount);
+
+        while (state.i < state.bound) {
+            AssetAmount memory balance = state.unpackBalanceValue();
+            AssetAmount memory out = borrowAgainstBalanceToBalance(c.account, balance, request);
+            writer.appendNonZeroBalance(out);
+        }
+
+        return state.complete(writer);
+    }
+}
+
+
+
+
+
+
+

package/commands/Burn.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext, State } from "./Base.sol";
+import { Cursors, Cur } from "../Cursors.sol";
+using Cursors for Cur;
+
+string constant NAME = "burn";
+
+/// @title Burn
+/// @notice Command that irreversibly destroys each BALANCE state block via a virtual hook.
+/// Produces no output state.
+abstract contract Burn is CommandBase {
+    uint internal immutable burnId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, "", burnId, State.Balances, State.Empty);
+    }
+
+    /// @notice Override to burn or consume the provided balance amount.
+    /// Called once per BALANCE block in state.
+    /// @param account Caller's account identifier.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount to burn.
+    /// @return Amount actually burned (may differ from `amount` for partial burns).
+    function burn(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal virtual returns (uint);
+
+    function burn(CommandContext calldata c) external payable onlyCommand(burnId, c.target) returns (bytes memory) {
+        (Cur memory state, , ) = cursor(c.state, 1);
+
+        while (state.i < state.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();
+            burn(c.account, asset, meta, amount);
+        }
+
+        state.complete();
+        return "";
+    }
+}
+
+
+
+
+

package/commands/Create.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext, State } from "./Base.sol";
+import { Cursors, Cur } from "../Cursors.sol";
+
+string constant NAME = "create";
+
+using Cursors for Cur;
+
+/// @title Create
+/// @notice Generic command that creates or initializes objects via a virtual hook.
+/// The request schema is constructor-defined; `create` is called once per top-level group.
+/// Produces no output state.
+abstract contract Create is CommandBase {
+    uint internal immutable createId = commandId(NAME);
+
+    constructor(string memory input) {
+        emit Command(host, NAME, input, createId, State.Empty, State.Empty);
+    }
+
+    /// @dev Override to create or initialize an object described by `input`.
+    /// Called once per top-level request item.
+    function create(bytes32 account, Cur memory input) internal virtual;
+
+    function create(CommandContext calldata c) external payable onlyCommand(createId, c.target) returns (bytes memory) {
+        (Cur memory request, , ) = cursor(c.request, 1);
+
+        while (request.i < request.bound) {
+            create(c.account, request);
+        }
+
+        request.complete();
+        return "";
+    }
+}
+
+
+
+
+

package/commands/Credit.sol

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandBase, CommandContext, State } from "./Base.sol";
+import { Cursors, Cur, Schemas } from "../Cursors.sol";
+string constant NAME = "creditAccount";
+
+using Cursors for Cur;
+
+/// @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.
+/// An optional RECIPIENT block in the request overrides the default `c.account` destination.
+abstract contract CreditAccount is CommandBase {
+    uint internal immutable creditAccountId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, Schemas.Recipient, creditAccountId, State.Balances, State.Empty);
+    }
+
+    /// @notice Override to credit externally managed funds to `account`.
+    /// Called once per BALANCE block in state.
+    /// @param account Recipient account identifier.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount to credit.
+    function creditAccount(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal virtual;
+
+    function creditAccount(
+        CommandContext calldata c
+    ) external payable onlyCommand(creditAccountId, c.target) returns (bytes memory) {
+        (Cur memory state, , ) = cursor(c.state, 1);
+        Cur memory request = cursor(c.request);
+        bytes32 to = request.recipientAfter(c.account);
+
+        while (state.i < state.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();
+            creditAccount(to, asset, meta, amount);
+        }
+
+        state.complete();
+        return "";
+    }
+}
+
+
+
+
+

package/commands/Debit.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, State } from "./Base.sol";
+import { Cursors, Cur, Schemas, Writer, Writers } from "../Cursors.sol";
+
+string constant NAME = "debitAccount";
+
+using Cursors for Cur;
+using Writers for Writer;
+
+/// @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
+/// AMOUNT block; the default batch implementation handles the full request loop.
+abstract contract DebitAccount is CommandBase {
+    uint internal immutable debitAccountId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, Schemas.Amount, debitAccountId, State.Empty, State.Balances);
+    }
+
+    /// @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 meta Asset metadata slot.
+    /// @param amount Amount to debit.
+    function debitAccount(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal virtual;
+
+    /// @notice Override to customize request parsing or batching for debits.
+    /// 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 count, ) = cursor(request, 1);
+        Writer memory writer = Writers.allocBalances(count);
+
+        while (input.i < input.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = input.unpackAmount();
+            debitAccount(account, asset, meta, amount);
+            writer.appendBalance(asset, meta, amount);
+        }
+
+        return input.complete(writer);
+    }
+
+    function debitAccount(
+        CommandContext calldata c
+    ) external payable onlyCommand(debitAccountId, c.target) returns (bytes memory) {
+        return debitAccount(c.account, c.request);
+    }
+}
+
+
+
+
+
+