@rootzero/contracts 0.9.3 → 0.9.5

package/commands/Base.sol

@@ -2,11 +2,9 @@
 pragma solidity ^0.8.33;
 
 import {NodeCalls} from "../core/Calls.sol";
-import {Cur} from "../Cursors.sol";
 import {CommandEvent} from "../events/Command.sol";
 import {Keys} from "../blocks/Keys.sol";
 import {Ids, Selectors} from "../utils/Ids.sol";
-import {Budget, Values} from "../utils/Value.sol";
 
 /// @notice Execution context passed to every command invocation.
 struct CommandContext {
@@ -25,22 +23,18 @@ struct CommandContext {
 abstract contract CommandBase is NodeCalls, CommandEvent {
     /// @dev Thrown when `onlyActive` finds that `deadline` has already passed.
     error Expired();
-    /// @dev Thrown when the raw active account word in calldata does not match the decoded context account.
-    error ActiveAccountMismatch();
     /// @dev Thrown when `onlyAdmin` finds that `account` is not the admin account.
     error NotAdmin();
 
-    /// @dev Restrict execution to trusted callers whose decoded context account matches the active calldata account.
-    modifier onlyCommand(bytes32 account) {
-        if (activeAccount() != account) revert ActiveAccountMismatch();
-        enforceCaller(msg.sender);
+    /// @dev Restrict execution to the commander using the host's admin account.
+    modifier onlyAdmin(bytes32 account) {
+        if (account != adminAccount) revert NotAdmin();
+        enforceCommander(msg.sender);
         _;
     }
 
-    /// @dev Restrict execution to trusted callers using the host's admin account.
-    modifier onlyAdmin(bytes32 account) {
-        if (activeAccount() != account) revert ActiveAccountMismatch();
-        if (account != adminAccount) revert NotAdmin();
+    /// @dev Restrict execution to trusted callers.
+    modifier onlyCommand() {
         enforceCaller(msg.sender);
         _;
     }
@@ -66,40 +60,4 @@ abstract contract CommandBase is NodeCalls, CommandEvent {
     function commandId(string memory name) internal view returns (uint) {
         return Ids.toCommand(Selectors.command(name), address(this));
     }
-
-    /// @notice Return the active command account directly from the fixed tuple head in calldata.
-    /// @dev Command entrypoints use the ABI shape `name((bytes32,bytes,bytes))`, so the tuple head
-    /// starts at byte 36 of `msg.data`, with the account field at bytes [36:68).
-    function activeAccount() internal pure returns (bytes32 account) {
-        account = bytes32(msg.data[36:68]);
-    }
-}
-
-/// @title CommandPayable
-/// @notice Abstract base for commands that accept native value (`msg.value`).
-/// Provides a shared settlement hook for any unspent value remaining in the
-/// command's mutable budget after execution completes.
-abstract contract CommandPayable is CommandBase {
-    /// @dev Thrown when a payable command completes with unspent native value.
-    /// Override `settleValue` to implement refund or forwarding behavior instead.
-    error UnusedValue(uint remaining);
-
-    /// @notice Drains the command budget and settles any remaining native value.
-    /// @dev Calls the amount-based `settleValue` hook only when some value remains.
-    /// @param account Caller's account identifier for the current invocation.
-    /// @param budget Mutable native-value budget used during command execution.
-    function settleValue(bytes32 account, Budget memory budget) internal {
-        uint remaining = Values.drain(budget);
-        if (remaining != 0) settleValue(account, remaining);
-    }
-
-    /// @notice Handles leftover native value after a payable command has finished.
-    /// @dev Override this hook to refund or redirect unused value for a command.
-    /// The default implementation rejects any leftover amount.
-    /// @param account Caller's account identifier for the current invocation.
-    /// @param remaining Unspent native value left in the budget, in wei.
-    function settleValue(bytes32 account, uint remaining) internal virtual {
-        account;
-        revert UnusedValue(remaining);
-    }
 }

package/commands/Burn.sol

@@ -28,7 +28,7 @@ abstract contract Burn is CommandBase, BurnHook {
         emit Command(host, burnId, NAME, "0:1:0", "", Keys.Balance, Keys.Empty, false);
     }
 
-    function burn(CommandContext calldata c) external onlyCommand(c.account) returns (bytes memory) {
+    function burn(CommandContext calldata c) external onlyCommand returns (bytes memory) {
         (Cur memory state, ) = cursor(c.state, 1);
 
         while (state.i < state.bound) {
@@ -36,7 +36,7 @@ abstract contract Burn is CommandBase, BurnHook {
             burn(c.account, asset, meta, amount);
         }
 
-        state.complete();
+        state.close();
         return "";
     }
 }

package/commands/Credit.sol

@@ -22,7 +22,7 @@ abstract contract CreditAccountHook {
 /// An optional ACCOUNT block in the request overrides the default `c.account` destination.
 abstract contract CreditAccount is CommandBase, CreditAccountHook {
     string private constant NAME = "creditAccount";
-    string private constant REQUEST = string.concat(Schemas.Empty, ";", Schemas.Account, "?");
+    string private constant REQUEST = string.concat(Schemas.Unit, ", maybe ", Schemas.Account);
 
     uint internal immutable creditAccountId = commandId(NAME);
 
@@ -32,7 +32,7 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
 
     function creditAccount(
         CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory) {
         (Cur memory state, ) = cursor(c.state, 1);
         bytes32 to = Cursors.resolveAccount(c.request, c.account);
 
@@ -41,7 +41,7 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
             creditAccount(to, asset, meta, amount);
         }
 
-        state.complete();
+        state.close();
         return "";
     }
 }

package/commands/Debit.sol

@@ -43,12 +43,13 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
             writer.appendBalance(asset, meta, amount);
         }
 
-        return input.complete(writer);
+        input.close();
+        return writer.finish();
     }
 
     function debitAccount(
         CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory) {
         return debitAccount(c.account, c.request);
     }
 }

package/commands/Deposit.sol

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandContext, CommandBase, CommandPayable, Keys } from "./Base.sol";
+import { CommandContext, CommandBase, Keys } from "./Base.sol";
+import { Payable } from "../core/Payable.sol";
 import { Cursors, Cur, Schemas, Writer, Writers } from "../Cursors.sol";
-import { Budget, Values } from "../utils/Value.sol";
+import { Budget } from "../utils/Value.sol";
 
 using Cursors for Cur;
 using Writers for Writer;
@@ -46,7 +47,7 @@ abstract contract Deposit is CommandBase, DepositHook {
 
     function deposit(
         CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory) {
         (Cur memory request, uint groups) = cursor(c.request, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
@@ -56,14 +57,15 @@ abstract contract Deposit is CommandBase, DepositHook {
             writer.appendBalance(asset, meta, amount);
         }
 
-        return request.complete(writer);
+        request.close();
+        return writer.finish();
     }
 }
 
 /// @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 CommandPayable, DepositPayableHook {
+abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
     string private constant NAME = "depositPayable";
 
     uint internal immutable depositPayableId = commandId(NAME);
@@ -74,10 +76,10 @@ abstract contract DepositPayable is CommandPayable, DepositPayableHook {
 
     function depositPayable(
         CommandContext calldata c
-    ) external payable onlyCommand(c.account) returns (bytes memory) {
+    ) external payable onlyCommand returns (bytes memory) {
         (Cur memory request, uint groups) = cursor(c.request, 1);
         Writer memory writer = Writers.allocBalances(groups);
-        Budget memory budget = Values.fromMsg();
+        Budget memory budget = valueBudget();
 
         while (request.i < request.bound) {
             (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
@@ -86,7 +88,8 @@ abstract contract DepositPayable is CommandPayable, DepositPayableHook {
         }
 
         settleValue(c.account, budget);
-        return request.complete(writer);
+        request.close();
+        return writer.finish();
     }
 }
 

package/commands/Provision.sol

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandContext, CommandBase, CommandPayable, Keys} from "./Base.sol";
+import {CommandContext, CommandBase, Keys} from "./Base.sol";
+import {Payable} from "../core/Payable.sol";
 import {HostAmount, Cursors, Cur, Schemas, Writer, Writers} from "../Cursors.sol";
-import {Budget, Values} from "../utils/Value.sol";
+import {Budget} from "../utils/Value.sol";
 using Cursors for Cur;
 using Writers for Writer;
 
@@ -40,7 +41,7 @@ abstract contract Provision is CommandBase, ProvisionHook {
         emit Command(host, provisionId, NAME, "1:0:1", Schemas.Allocation, Keys.Empty, Keys.Custody, false);
     }
 
-    function provision(CommandContext calldata c) external onlyCommand(c.account) returns (bytes memory) {
+    function provision(CommandContext calldata c) external onlyCommand returns (bytes memory) {
         (Cur memory request, uint groups) = cursor(c.request, 1);
         Writer memory writer = Writers.allocCustodies(groups);
 
@@ -50,7 +51,8 @@ abstract contract Provision is CommandBase, ProvisionHook {
             writer.appendCustody(allocation);
         }
 
-        return request.complete(writer);
+        request.close();
+        return writer.finish();
     }
 }
 
@@ -58,7 +60,7 @@ abstract contract Provision is CommandBase, ProvisionHook {
 /// @notice Command that provisions assets to peer hosts from ALLOCATION request blocks.
 /// Each request block supplies the target host plus an asset amount; the output is a CUSTODY state stream.
 /// The hook receives a mutable native-value budget drawn from `msg.value`.
-abstract contract ProvisionPayable is CommandPayable, ProvisionPayableHook {
+abstract contract ProvisionPayable is CommandBase, Payable, ProvisionPayableHook {
     string private constant NAME = "provisionPayable";
 
     uint internal immutable provisionPayableId = commandId(NAME);
@@ -69,10 +71,10 @@ abstract contract ProvisionPayable is CommandPayable, ProvisionPayableHook {
 
     function provisionPayable(
         CommandContext calldata c
-    ) external payable onlyCommand(c.account) returns (bytes memory) {
+    ) external payable onlyCommand returns (bytes memory) {
         (Cur memory request, uint groups) = cursor(c.request, 1);
         Writer memory writer = Writers.allocCustodies(groups);
-        Budget memory budget = Values.fromMsg();
+        Budget memory budget = valueBudget();
 
         while (request.i < request.bound) {
             HostAmount memory allocation = request.unpackAllocationValue();
@@ -81,7 +83,8 @@ abstract contract ProvisionPayable is CommandPayable, ProvisionPayableHook {
         }
 
         settleValue(c.account, budget);
-        return request.complete(writer);
+        request.close();
+        return writer.finish();
     }
 }
 

package/commands/Transfer.sol

@@ -42,13 +42,13 @@ abstract contract Transfer is CommandBase, TransferHook {
             transfer(value);
         }
 
-        input.complete();
+        input.close();
         return "";
     }
 
     function transfer(
         CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory) {
         return transfer(c.account, c.request);
     }
 }

package/commands/Withdraw.sol

@@ -21,7 +21,7 @@ abstract contract WithdrawHook {
 /// For internal balance credits, use `creditAccount` instead.
 abstract contract Withdraw is CommandBase, WithdrawHook {
     string private constant NAME = "withdraw";
-    string private constant REQUEST = string.concat(Schemas.Empty, ";", Schemas.Account, "?");
+    string private constant REQUEST = string.concat(Schemas.Unit, ", maybe ", Schemas.Account);
 
     uint internal immutable withdrawId = commandId(NAME);
 
@@ -31,7 +31,7 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
 
     function withdraw(
         CommandContext calldata c
-    ) external onlyCommand(c.account) returns (bytes memory) {
+    ) external onlyCommand returns (bytes memory) {
         (Cur memory state, ) = cursor(c.state, 1);
         bytes32 to = Cursors.resolveAccount(c.request, c.account);
 
@@ -40,7 +40,7 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
             withdraw(to, asset, meta, amount);
         }
 
-        state.complete();
+        state.close();
         return "";
     }
 }

package/commands/admin/AllowAssets.sol

@@ -34,7 +34,7 @@ abstract contract AllowAssets is CommandBase, AdminEvent, AllowAssetsHook {
             allowAsset(asset, meta);
         }
 
-        request.complete();
+        request.close();
         return "";
     }
 }

package/commands/admin/Allowance.sol

@@ -37,7 +37,7 @@ abstract contract Allowance is CommandBase, AdminEvent, AllowanceHook {
             allowance(peer, asset, meta, amount);
         }
 
-        request.complete();
+        request.close();
         return "";
     }
 }

package/commands/admin/Authorize.sol

@@ -29,7 +29,7 @@ abstract contract Authorize is CommandBase, AdminEvent {
             authorize(node);
         }
 
-        request.complete();
+        request.close();
         return "";
     }
 }

package/commands/admin/DenyAssets.sol

@@ -34,7 +34,7 @@ abstract contract DenyAssets is CommandBase, AdminEvent, DenyAssetsHook {
             denyAsset(asset, meta);
         }
 
-        request.complete();
+        request.close();
         return "";
     }
 }

package/commands/admin/Execute.sol

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandContext, CommandPayable, Keys} from "../Base.sol";
+import {CommandBase, CommandContext, Keys} from "../Base.sol";
+import {Payable} from "../../core/Payable.sol";
 import {Cursors, Cur, Schemas} from "../../Cursors.sol";
 import {AdminEvent} from "../../events/Admin.sol";
-import {Budget, Values} from "../../utils/Value.sol";
+import {Budget} from "../../utils/Value.sol";
 import {Ids} from "../../utils/Ids.sol";
 
 using Cursors for Cur;
@@ -13,7 +14,7 @@ using Cursors for Cur;
 /// @notice Admin command that forwards raw calldata to one or more target nodes.
 /// Each CALL block specifies a target node ID, native value, and raw calldata payload.
 /// Only callable by the admin account.
-abstract contract ExecutePayable is CommandPayable, AdminEvent {
+abstract contract ExecutePayable is CommandBase, Payable, AdminEvent {
     string private constant NAME = "executePayable";
 
     uint internal immutable executePayableId = commandId(NAME);
@@ -24,15 +25,15 @@ abstract contract ExecutePayable is CommandPayable, AdminEvent {
 
     function executePayable(CommandContext calldata c) external payable onlyAdmin(c.account) returns (bytes memory) {
         (Cur memory request, ) = cursor(c.request, 1);
-        Budget memory budget = Values.fromMsg();
+        Budget memory budget = valueBudget();
 
         while (request.i < request.bound) {
             (uint target, uint value, bytes calldata data) = request.unpackCall();
             address addr = Ids.nodeAddr(target);
-            callAddr(addr, Values.use(budget, value), data);
+            callAddr(addr, useValue(budget, value), data);
         }
 
-        request.complete();
+        request.close();
         settleValue(c.account, budget);
         return "";
     }

package/commands/admin/Unauthorize.sol

@@ -29,7 +29,7 @@ abstract contract Unauthorize is CommandBase, AdminEvent {
             unauthorize(node);
         }
 
-        request.complete();
+        request.close();
         return "";
     }
 }

package/core/Access.sol

@@ -78,4 +78,15 @@ abstract contract AccessControl is RootZeroContext, AccessEvent {
         }
         return caller;
     }
+
+    /// @notice Assert that `caller` is the commander and return it.
+    /// Used by admin modifiers to keep governance authority separate from peer trust.
+    /// @param caller Address to validate.
+    /// @return The same `caller` value if it is the commander.
+    function enforceCommander(address caller) internal view returns (address) {
+        if (caller == address(0) || caller != commander) {
+            revert UnauthorizedCaller(caller);
+        }
+        return caller;
+    }
 }

package/core/Calls.sol

@@ -72,13 +72,13 @@ abstract contract NodeCalls is AccessControl {
     }
 
     /// @notice Encode and call a trusted command node.
-    /// @param ctx Command execution context.
-    /// @param cid Command node ID embedding the target selector.
+    /// @param id Command node ID embedding the target selector.
     /// @param value Native value to forward in wei.
+    /// @param ctx Command execution context.
     /// @return Decoded command output block stream.
-    function callCommand(CommandContext memory ctx, uint cid, uint value) internal returns (bytes memory) {
-        bytes4 selector = Ids.commandSelector(cid);
+    function callCommand(uint id, uint value, CommandContext memory ctx) internal returns (bytes memory) {
+        bytes4 selector = Ids.commandSelector(id);
         bytes memory data = abi.encodeWithSelector(selector, ctx);
-        return abi.decode(callTo(cid, value, data), (bytes));
+        return abi.decode(callTo(id, value, data), (bytes));
     }
 }

package/core/Context.sol

@@ -29,8 +29,7 @@ abstract contract RootZeroContext {
     /// @return cur Cursor with `bound` set to the end of the first run.
     /// @return groups Number of block groups in the run (`prime block count / group`).
     function cursor(bytes calldata source, uint group) internal pure returns (Cur memory cur, uint groups) {
-        cur = Cursors.open(source);
-        (, , groups) = cur.primeRun(group);
+        return Cursors.init(source, group);
     }
 
     /// @notice Open a cursor, prime it, and assert that its group count matches `expectedGroups`.
@@ -41,8 +40,8 @@ abstract contract RootZeroContext {
     /// @param expectedGroups Required number of groups in the first run.
     /// @return cur Cursor with `bound` set to the end of the first run.
     function cursor(bytes calldata source, uint group, uint expectedGroups) internal pure returns (Cur memory cur) {
-        cur = Cursors.open(source);
-        (, , uint groups) = cur.primeRun(group);
+        uint groups;
+        (cur, groups) = Cursors.init(source, group);
         if (groups != expectedGroups) revert Cursors.BadRatio();
     }
 }

package/core/Host.sol

@@ -5,38 +5,43 @@ import {AccessControl} from "./Access.sol";
 import {Authorize} from "../commands/admin/Authorize.sol";
 import {Unauthorize} from "../commands/admin/Unauthorize.sol";
 import {ExecutePayable} from "../commands/admin/Execute.sol";
-import {HostAnnouncedEvent} from "../events/Host.sol";
-import {IHostDiscovery} from "../interfaces/IHostDiscovery.sol";
-import {Ids} from "../utils/Ids.sol";
+import {IntroductionEvent} from "../events/Introduction.sol";
 
-/// @notice Mixin that allows a contract to act as a host discovery registry.
-/// Hosts call `announceHost` on a discovery contract to register themselves.
-abstract contract HostDiscovery is HostAnnouncedEvent, IHostDiscovery {
-    /// @notice Announce this host to the discovery registry.
-    /// Validates that `id` matches `msg.sender` before emitting.
-    /// @param id Host node ID (must equal `Ids.toHost(msg.sender)`).
-    /// @param blocknum Block number at which the host was deployed.
-    /// @param version Protocol version the host implements.
-    /// @param namespace Human-readable namespace string for the host.
-    function announceHost(uint id, uint blocknum, uint16 version, string calldata namespace) external {
-        emit HostAnnounced(Ids.matchHost(id, msg.sender), blocknum, version, namespace);
-    }
+/// @title IHostIntroduction
+/// @notice Interface implemented by hosts that accept introductions from other hosts.
+interface IHostIntroduction {
+    /// @notice Record a host introduction claim.
+    /// @param peer Host node ID being introduced.
+    /// @param blocknum Block number at which the introduction was made.
+    /// @param version Protocol version the host is running.
+    /// @param namespace Human-readable namespace or label for the host.
+    function introduce(uint peer, uint blocknum, uint16 version, string calldata namespace) external;
 }
 
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
 /// Inherits admin command support (authorize, unauthorize, executePayable) and
-/// optionally announces itself to a discovery contract at deployment.
+/// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.
-abstract contract Host is Authorize, Unauthorize, ExecutePayable {
+abstract contract Host is Authorize, Unauthorize, ExecutePayable, IntroductionEvent, IHostIntroduction {
     /// @param cmdr Commander address; passed to `AccessControl`.
-    ///        If `cmdr` is a deployed contract, the host calls `announceHost`
-    ///        on it during construction to register with the discovery registry.
+    ///        If `cmdr` is a deployed contract, the host calls `introduce`
+    ///        on it during construction.
     /// @param version Protocol version number to publish in the announcement.
     /// @param namespace Human-readable namespace string for the host.
     constructor(address cmdr, uint16 version, string memory namespace) AccessControl(cmdr) {
         if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
-        IHostDiscovery(cmdr).announceHost(host, block.number, version, namespace);
+        IHostIntroduction(cmdr).introduce(host, block.number, version, namespace);
+    }
+
+    /// @notice Record a host introduction claim.
+    /// @dev This event is informational only; it does not authorize or trust the introduced host.
+    /// @param peer Host node ID being introduced.
+    /// @param blocknum Block number at which the host was deployed.
+    /// @param version Protocol version the host implements.
+    /// @param namespace Human-readable namespace string for the host.
+    function introduce(uint peer, uint blocknum, uint16 version, string calldata namespace) external {
+        emit Introduction(peer, blocknum, version, namespace);
     }
 
     /// @notice Accept native ETH transfers (e.g. from command value flows).

package/core/Payable.sol

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Budget, Values} from "../utils/Value.sol";
+
+/// @title Payable
+/// @notice Abstract mixin for entrypoints that accept native value (`msg.value`).
+/// Provides a shared settlement hook for any unspent value remaining in the
+/// mutable budget after execution completes.
+abstract contract Payable {
+    /// @dev Thrown when a payable entrypoint completes with unspent native value.
+    /// Override `settleValue` to implement refund or forwarding behavior instead.
+    error UnusedValue(uint remaining);
+
+    /// @notice Create a native-value budget from the current call's `msg.value`.
+    /// @return Budget initialised with the full `msg.value`.
+    function valueBudget() internal view returns (Budget memory) {
+        return Budget({remaining: msg.value});
+    }
+
+    /// @notice Deduct `amount` from the budget and return it.
+    /// @param budget Mutable budget to deduct from.
+    /// @param amount Native value to spend.
+    /// @return The same `amount`, ready to forward to a callee.
+    function useValue(Budget memory budget, uint amount) internal pure returns (uint) {
+        return Values.use(budget, amount);
+    }
+
+    /// @notice Deduct `amount` from the budget and return it as a new sub-budget.
+    /// @param budget Mutable parent budget to deduct from.
+    /// @param amount Native value to assign to the sub-budget.
+    /// @return A new budget with `amount` remaining.
+    function allocateValue(Budget memory budget, uint amount) internal pure returns (Budget memory) {
+        return Values.allocate(budget, amount);
+    }
+
+    /// @notice Drains the budget and settles any remaining native value.
+    /// @dev Calls the amount-based `settleValue` hook only when some value remains.
+    /// @param account Account identifier for the current invocation.
+    /// @param budget Mutable native-value budget used during execution.
+    function settleValue(bytes32 account, Budget memory budget) internal {
+        uint value = budget.remaining;
+        if (value == 0) return;
+        budget.remaining = 0;
+        settleValue(account, value);
+    }
+
+    /// @notice Handles leftover native value after payable execution has finished.
+    /// @dev Override this hook to refund or redirect unused value.
+    /// The default implementation rejects any leftover amount.
+    /// @param account Account identifier for the current invocation.
+    /// @param remaining Unspent native value left in the budget, in wei.
+    function settleValue(bytes32 account, uint remaining) internal virtual {
+        account;
+        revert UnusedValue(remaining);
+    }
+}

package/core/Pipeline.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Cursors, Cur} from "../Cursors.sol";
+import {Payable} from "./Payable.sol";
+import {Budget} from "../utils/Value.sol";
+
+using Cursors for Cur;
+
+/// @title Pipeline
+/// @notice Core pipeline functionality shared by higher-level surfaces.
+abstract contract Pipeline is Payable {
+    error UnexpectedState();
+
+    /// @notice Override to dispatch one piped step.
+    /// Called once per STEP block. The returned bytes become the state passed to
+    /// the next step, and the final returned state must be empty.
+    /// @param target Node ID to invoke or handle.
+    /// @param account Account identifier for the piped context.
+    /// @param state Current threaded state block stream.
+    /// @param request Step request block stream.
+    /// @param value Native value assigned to this step.
+    /// @return Updated state block stream for the next step.
+    function dispatch(
+        uint target,
+        bytes32 account,
+        bytes memory state,
+        bytes calldata request,
+        uint value
+    ) internal virtual returns (bytes memory);
+
+    /// @notice Execute a STEP block stream through the pipeline.
+    /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
+    /// @param account Account identifier used for each dispatched step.
+    /// @param state Initial state block stream passed to the first step.
+    /// @param steps STEP block stream to execute.
+    /// @param budget Mutable native-value budget shared across all steps.
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        Budget memory budget
+    ) internal {
+        (Cur memory input, ) = Cursors.init(steps, 1);
+
+        while (input.i < input.bound) {
+            (uint target, uint value, bytes calldata request) = input.unpackStep();
+            state = dispatch(target, account, state, request, useValue(budget, value));
+        }
+
+        if (state.length != 0) revert UnexpectedState();
+        settleValue(account, budget);
+        input.close();
+    }
+}