@rootzero/contracts 1.13.0 → 1.14.0

package/commands/Base.sol

@@ -2,26 +2,24 @@
 pragma solidity ^0.8.33;
 
 import {NodeCalls} from "../core/Calls.sol";
-import {EndpointBase, Lane} from "../core/Endpoint.sol";
-import {Cur} from "../Cursors.sol";
-import {Keys} from "../blocks/Keys.sol";
+import {EndpointBase} from "../core/Endpoint.sol";
+import {Blocks} from "../codec/Blocks.sol";
+import {Specs} from "../codec/Specs.sol";
+import {HostAmount} from "../core/Types.sol";
+import {Execution, Executions, Lanes} from "../execution/Execution.sol";
+import {ReceivedEvent} from "../events/Received.sol";
+import {Actions} from "../utils/Actions.sol";
+import {Descriptors} from "../codec/Descriptors.sol";
 import {Nodes} from "../utils/Nodes.sol";
 import {Selectors} from "../utils/Selectors.sol";
+import {Cursors} from "../utils/Cursors.sol";
 
-/// @notice Execution context passed to every command invocation.
-struct CommandContext {
-    /// @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 input;
-}
+using Executions for Execution;
 
 /// @title CommandBase
 /// @notice Abstract base for all rootzero command contracts.
 /// Provides access control modifiers and command endpoint metadata helpers.
-abstract contract CommandBase is NodeCalls, EndpointBase {
+abstract contract CommandBase is NodeCalls, EndpointBase, ReceivedEvent {
     /// @dev Thrown when `onlyActive` finds that `deadline` has already passed.
     error Expired();
 
@@ -45,42 +43,78 @@ abstract contract CommandBase is NodeCalls, EndpointBase {
         _;
     }
 
+    /// @notice Close a command execution and refund unspent value to `account`.
+    /// @param exec Command execution to close.
+    /// @param account Account that should receive any unspent value.
+    /// @return output Final encoded output block stream.
+    /// @return transactions Final encoded transaction block stream.
+    function close(
+        Execution memory exec,
+        bytes32 account
+    ) internal returns (bytes memory output, bytes memory transactions) {
+        if (exec.budget == 0 && Cursors.initial(exec.writers)) return ("", "");
+
+        output = close(exec);
+        uint amount = exec.refundValue(account, nativeAsset);
+        if (amount != 0) {
+            emit Received(account, nativeAsset, amount, Actions.Refund, 0);
+        }
+
+        transactions = exec.finishTransactions();
+    }
+
     /// @notice Publish command metadata and a default label.
-    /// @param name Default human-readable command label and selector name.
-    /// @param state Packed state lane plus optional group byte.
-    /// @param input Packed input lane plus optional group byte.
-    /// @param output Packed output lane plus optional group byte.
-    /// @param selector Command ABI selector, or zero to derive it from `name`.
+    /// @param name Command entrypoint name and default label. It must exactly
+    /// match the Solidity command function name used by the canonical ABI.
+    /// @param state State block specification.
+    /// @param input Input block specification.
+    /// @param output Output block specification.
+    /// @param transactions Number of transaction blocks produced per batch, or zero for none.
     /// @param funded Whether the command accepts nonzero native value.
     /// @param admin Whether the command is restricted to the admin account.
     /// @return id Command node ID.
     /// @return descriptor Packed endpoint lane metadata and flags.
     function command(
         string memory name,
-        bytes9 state,
-        bytes9 input,
-        bytes9 output,
-        bytes4 selector,
+        uint state,
+        uint input,
+        uint output,
+        uint8 transactions,
         bool funded,
         bool admin
-    ) internal returns (uint id, bytes32 descriptor) {
-        selector = selector == bytes4(0) ? Selectors.command(name) : selector;
-        id = Nodes.toCommand(selector, address(this));
-        descriptor = endpoint(id, name, state, input, output, funded, admin);
+    ) internal returns (uint id, uint descriptor) {
+        id = Nodes.toCommand(Selectors.command(name), address(this));
+        uint8 flags;
+        if (funded) flags |= Descriptors.Funded;
+        if (admin) flags |= Descriptors.Admin;
+        descriptor = endpoint(id, name, state, input, output, transactions, flags);
+    }
+
+    /// @notice Open a command state stream and return the expected output block count.
+    /// @param source State block stream to open.
+    /// @param descriptor Packed command endpoint descriptor.
+    /// @param batches Required batch count, or zero to accept the state count.
+    /// @return exec Execution with its output buffer metadata initialized for the state batch count.
+    function openState(
+        bytes calldata source,
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        return Executions.openState(source, descriptor, batches);
     }
 
-    /// @notice Open input/state cursors and return the expected output block count.
-    /// @param c Command invocation context.
+    /// @notice Open a command execution with batches derived from its input and state lanes.
+    /// @param state Current command state block stream.
+    /// @param input Command input block stream.
     /// @param descriptor Packed command endpoint descriptor.
-    /// @return input Cursor scoped to the command input lane.
-    /// @return state Cursor scoped to the command state lane.
-    /// @return outputs Number of output blocks implied by the matched group count.
+    /// @param batches Required batch count, or zero to reconcile the lane counts.
+    /// @return exec Execution with its output buffer metadata initialized for the reconciled batch count.
     function openCommand(
-        CommandContext calldata c,
-        bytes32 descriptor
-    ) internal pure returns (Cur memory input, Cur memory state, uint outputs) {
-        uint groups;
-        (input, groups, ) = openLane(c.input, descriptor, Lane.Input, 0);
-        (state, , outputs) = openLane(c.state, descriptor, Lane.State, groups);
+        bytes calldata state,
+        bytes calldata input,
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        return Executions.open(state, input, descriptor, batches);
     }
 }

package/commands/Burn.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur } from "../Cursors.sol";
-using Cursors for Cur;
+import { Execution, Executions, CommandBase, Lanes, Specs } from "./Base.sol";
+using Executions for Execution;
 
+/// @notice Hook implemented by hosts that burn account assets.
 abstract contract BurnHook {
     /// @notice Override to burn or consume the provided balance amount.
     /// Called once per BALANCE block in state.
@@ -19,24 +19,29 @@ abstract contract BurnHook {
 /// @notice Command that irreversibly destroys each BALANCE state block via a virtual hook.
 /// Produces no output state.
 abstract contract Burn is CommandBase, BurnHook {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("burn", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
+        (, descriptor) = command("burn", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
     }
 
     /// @notice Burn each BALANCE block from the command state.
-    /// @param c Command context; `c.state` must contain BALANCE blocks.
+    /// @param state BALANCE block stream.
     /// @return Empty output state.
     /// @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);
+    function burn(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openState(state, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
+            burn(account, asset, amount);
         }
-        return ("", "");
+
+        return close(exec, account);
     }
 }
 

package/commands/Credit.sol

@@ -1,42 +1,43 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur } from "../Cursors.sol";
-import { CreditAccountHook } from "../core/Settlement.sol";
+import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {CreditAccountHook} from "../core/Settlement.sol";
 
-using Cursors for Cur;
+using Executions for Execution;
 
 /// @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 internal immutable creditAccountId;
+    uint private immutable descriptor;
+    uint private immutable id;
 
     constructor() {
-        (creditAccountId, descriptor) = command("creditAccount", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
+        (id, descriptor) = command("creditAccount", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
+    }
+
+    /// @notice Return the registered CREDIT_ACCOUNT command ID.
+    function creditAccountId() internal view returns (uint) {
+        return id;
     }
 
     /// @notice Credit each BALANCE block from the command state to the command account.
-    /// @param c Command context; `c.state` must contain BALANCE blocks.
+    /// @param state BALANCE block stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function creditAccount(
-        CommandContext calldata c
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        (Cur memory state, ) = openState(c.state, descriptor);
+        Execution memory exec = openState(state, descriptor, 0);
 
-        while (state.i < state.len) {
-            (bytes32 asset, uint amount) = state.unpackBalance();
-            creditAccount(c.account, asset, amount);
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
+            creditAccount(account, asset, amount);
         }
-        return ("", "");
+
+        return close(exec, account);
     }
 }
-
-
-
-
-
-

package/commands/Debit.sol

@@ -1,55 +1,52 @@
 // SPDX-License-Identifier: GPL-3.0-only
 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";
+import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {DebitAccountHook} from "../core/Settlement.sol";
 
-using Cursors for Cur;
-using Writers for Writer;
+using Executions for Execution;
 
 /// @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.
+/// AMOUNT block; the default batch implementation handles the full input loop.
 abstract contract DebitAccount is CommandBase, DebitAccountHook {
-    bytes32 private immutable descriptor;
-    uint internal immutable debitAccountId;
+    uint private immutable descriptor;
+    uint private immutable id;
 
     constructor() {
-        (debitAccountId, descriptor) = command("debitAccount", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
+        (id, descriptor) = command("debitAccount", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
     }
 
-    /// @notice Override to customize request parsing or batching for debits.
+    /// @notice Return the registered DEBIT_ACCOUNT command ID.
+    function debitAccountId() internal view returns (uint) {
+        return id;
+    }
+
+    /// @notice Override to customize input 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 outputs) = openInput(request, descriptor);
-        Writer memory output = Writers.allocBalances(outputs);
+    function debitAccount(bytes32 account, bytes calldata input) internal virtual returns (bytes memory, bytes memory) {
+        Execution memory exec = openInput(input, descriptor, 0);
 
-        while (input.i < input.len) {
-            (bytes32 asset, uint amount) = input.unpackAmount();
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
             debitAccount(account, asset, amount);
-            output.appendBalance(asset, amount);
+            exec.outputBalance(asset, amount);
         }
 
-        return output.finish();
+        return close(exec, account);
     }
 
-    /// @notice Debit AMOUNT request blocks from the command account and output matching BALANCE blocks.
-    /// @param c Command context; `c.input` must contain AMOUNT blocks.
+    /// @notice Debit AMOUNT input blocks from the command account and output matching BALANCE blocks.
+    /// @param input AMOUNT block stream.
     /// @return BALANCE block stream matching the debited amounts.
     /// @return Empty transaction stream.
     function debitAccount(
-        CommandContext calldata c
+        bytes32 account,
+        bytes calldata,
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        return (debitAccount(c.account, c.input), "");
+        return debitAccount(account, input);
     }
 }
-
-
-
-
-
-
-

package/commands/Deposit.sol

@@ -1,14 +1,11 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandContext, CommandBase, Keys } from "./Base.sol";
-import { Payable } from "../core/Payable.sol";
-import { Cursors, Cur, Writer, Writers } from "../Cursors.sol";
-import { Budget } from "../utils/Value.sol";
+import { Execution, Executions, CommandBase, Lanes, Specs } from "./Base.sol";
 
-using Cursors for Cur;
-using Writers for Writer;
+using Executions for Execution;
 
+/// @notice Hook implemented by hosts that accept account deposits.
 abstract contract DepositHook {
     /// @notice Override to receive externally sourced funds for `account`.
     /// Called once per AMOUNT block. A matching BALANCE block is appended to the
@@ -19,6 +16,7 @@ abstract contract DepositHook {
     function deposit(bytes32 account, bytes32 asset, uint amount) internal virtual;
 }
 
+/// @notice Hook implemented by hosts that accept value-funded deposits.
 abstract contract DepositPayableHook {
     /// @notice Override to receive externally sourced funds for `account`.
     /// Called once per AMOUNT block. A matching BALANCE block is appended to the
@@ -26,8 +24,8 @@ abstract contract DepositPayableHook {
     /// @param account Destination account identifier.
     /// @param asset Asset identifier.
     /// @param amount Amount received.
-    /// @param budget Mutable native-value budget drawn from `msg.value`.
-    function deposit(bytes32 account, bytes32 asset, uint amount, Budget memory budget) internal virtual;
+    /// @param funds Mutable execution used only for its remaining native-value budget.
+    function deposit(bytes32 account, bytes32 asset, uint amount, Execution memory funds) internal virtual;
 }
 
 /// @title Deposit
@@ -35,60 +33,61 @@ abstract contract DepositPayableHook {
 /// Use `deposit` for assets arriving from outside the protocol (e.g. ERC-20 transfers, ETH).
 /// For internal balance deductions, use `debitAccount` instead.
 abstract contract Deposit is CommandBase, DepositHook {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("deposit", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
+        (, descriptor) = command("deposit", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
     }
 
-    /// @notice Deposit AMOUNT request blocks into the command account and output matching BALANCE blocks.
-    /// @param c Command context; `c.input` must contain AMOUNT blocks.
+    /// @notice Deposit AMOUNT input blocks into the command account and output matching BALANCE blocks.
+    /// @param input AMOUNT block stream.
     /// @return BALANCE block stream matching the deposited amounts.
     /// @return Empty transaction stream.
     function deposit(
-        CommandContext calldata c
+        bytes32 account,
+        bytes calldata,
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        (Cur memory input, uint outputs) = openInput(c.input, descriptor);
-        Writer memory output = Writers.allocBalances(outputs);
+        Execution memory exec = openInput(input, descriptor, 0);
 
-        while (input.i < input.len) {
-            (bytes32 asset, uint amount) = input.unpackAmount();
-            deposit(c.account, asset, amount);
-            output.appendBalance(asset, amount);
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+            deposit(account, asset, amount);
+            exec.outputBalance(asset, amount);
         }
 
-        return (output.finish(), "");
+        return close(exec, account);
     }
 }
 
 /// @title DepositPayable
 /// @notice Command that receives externally sourced assets and records them as BALANCE state.
 /// Use `depositPayable` when the hook needs tracked access to `msg.value` via a mutable budget.
-abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
-    bytes32 private immutable descriptor;
+abstract contract DepositPayable is CommandBase, DepositPayableHook {
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("depositPayable", Keys.Empty, Keys.Amount, Keys.Balance, 0, true, false);
+        (, descriptor) = command("depositPayable", Specs.Empty, Specs.Amount, Specs.Balance, 0, true, false);
     }
 
-    /// @notice Deposit AMOUNT request blocks with access to a mutable native-value budget.
-    /// @param c Command context; `c.input` must contain AMOUNT blocks.
+    /// @notice Deposit AMOUNT input blocks with access to a mutable native-value budget.
+    /// @param input AMOUNT block stream.
     /// @return BALANCE block stream matching the deposited amounts.
     /// @return Remaining native value as a refund transaction stream.
     function depositPayable(
-        CommandContext calldata c
+        bytes32 account,
+        bytes calldata,
+        bytes calldata input
     ) 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();
-
-        while (input.i < input.len) {
-            (bytes32 asset, uint amount) = input.unpackAmount();
-            deposit(c.account, asset, amount, budget);
-            output.appendBalance(asset, amount);
+        Execution memory exec = openInput(input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+            deposit(account, asset, amount, exec);
+            exec.outputBalance(asset, amount);
         }
 
-        return (output.finish(), closeValue(budget, c.account));
+        return close(exec, account);
     }
 }
 

package/commands/Payout.sol

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandContext, CommandBase, Keys} from "./Base.sol";
-import {Cursors, Cur} from "../Cursors.sol";
+import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
 
-using Cursors for Cur;
+using Executions for Execution;
 
+/// @notice Hook implemented by hosts that pay balances to accounts.
 abstract contract PayoutHook {
     /// @notice Override to pay `amount` from `account` to `to`.
-    /// Called once per paired BALANCE state block and ACCOUNT request block.
+    /// Called once per paired BALANCE state block and ACCOUNT input block.
     /// @param account Source account identifier.
     /// @param to Destination account identifier.
     /// @param asset Asset identifier.
@@ -17,26 +17,32 @@ abstract contract PayoutHook {
 }
 
 /// @title Payout
-/// @notice Command that sinks BALANCE state blocks to matching ACCOUNT request blocks.
+/// @notice Command that sinks BALANCE state blocks to matching ACCOUNT input blocks.
 /// Each BALANCE block is paired with one ACCOUNT block at the same position.
 abstract contract Payout is CommandBase, PayoutHook {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("payout", Keys.Balance, Keys.Account, Keys.Empty, 0, false, false);
+        (, descriptor) = command("payout", Specs.Balance, Specs.Account, Specs.Empty, 0, 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.input` matching ACCOUNT blocks.
+    /// @notice Pay out BALANCE state blocks to matching ACCOUNT input blocks.
+    /// @param state BALANCE block stream.
+    /// @param input Matching ACCOUNT block stream.
     /// @return Empty output state.
     /// @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);
+    function payout(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
-        while (state.i < state.len) {
-            (bytes32 asset, uint amount) = state.unpackBalance();
-            payout(c.account, input.unpackAccount(), asset, amount);
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
+            payout(account, exec.unpackAccount(Lanes.Input), asset, amount);
         }
-        return ("", "");
+
+        return close(exec, account);
     }
 }