@rootzero/contracts 0.5.0 → 0.6.0

package/{contracts/Commands.sol → Commands.sol}

@@ -4,20 +4,20 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports all command and peer abstractions.
 // Import this file to inherit from any command or peer base contract without managing individual paths.
 
-import { CommandBase, CommandContext } from "./commands/Base.sol";
+import { CommandBase, CommandContext, CommandPayable } from "./commands/Base.sol";
 import { State } from "./utils/State.sol";
 import { BorrowAgainstBalanceToBalance, BorrowAgainstCustodyToBalance } from "./commands/Borrow.sol";
 import { Burn } from "./commands/Burn.sol";
 import { Create } from "./commands/Create.sol";
 import { CreditAccount } from "./commands/Credit.sol";
 import { DebitAccount } from "./commands/Debit.sol";
-import { Deposit } from "./commands/Deposit.sol";
+import { Deposit, DepositPayable } from "./commands/Deposit.sol";
 import { Remove } from "./commands/Remove.sol";
 import { AddLiquidityFromBalancesToBalances, AddLiquidityFromCustodiesToBalances, RemoveLiquidityFromBalanceToBalances, RemoveLiquidityFromCustodyToBalances } from "./commands/Liquidity.sol";
 import { LiquidateFromBalanceToBalances, LiquidateFromCustodyToBalances } from "./commands/Liquidate.sol";
 import { MintToBalances } from "./commands/Mint.sol";
-import { Pipe } from "./commands/Pipe.sol";
-import { Provision, ProvisionFromBalance } from "./commands/Provision.sol";
+import { PipePayable } from "./commands/Pipe.sol";
+import { Provision, ProvisionPayable, ProvisionFromBalance } from "./commands/Provision.sol";
 import { ReclaimToBalances } from "./commands/Reclaim.sol";
 import { RedeemFromBalanceToBalances, RedeemFromCustodyToBalances } from "./commands/Redeem.sol";
 import { RepayFromBalanceToBalances, RepayFromCustodyToBalances } from "./commands/Repay.sol";
@@ -33,7 +33,7 @@ import { Destroy } from "./commands/admin/Destroy.sol";
 import { Authorize } from "./commands/admin/Authorize.sol";
 import { DenyAssets } from "./commands/admin/DenyAssets.sol";
 import { Init } from "./commands/admin/Init.sol";
-import { Relocate } from "./commands/admin/Relocate.sol";
+import { RelocatePayable } from "./commands/admin/Relocate.sol";
 import { Allocate } from "./commands/admin/Allocate.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 import { PeerBase } from "./peer/Base.sol";
@@ -41,6 +41,8 @@ import { PeerAllowAssets } from "./peer/AllowAssets.sol";
 import { PeerDenyAssets } from "./peer/DenyAssets.sol";
 import { PeerPull } from "./peer/Pull.sol";
 import { PeerPush } from "./peer/Push.sol";
+import { PeerSettle } from "./peer/Settle.sol";
+
 
 
 

package/{contracts/Utils.sol → Utils.sol}

@@ -11,8 +11,8 @@ import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids, Selectors } from "./utils/Ids.sol";
 import { Layout } from "./utils/Layout.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToString, divisible, isFamily, isLocal, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
-import { Values } from "./utils/Value.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToString, divisible, isFamily, isLocal, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
+import { Budget, Values } from "./utils/Value.sol";
 
 
 

package/{contracts/commands → commands}/Base.sol

@@ -6,6 +6,7 @@ import {Cur} from "../Cursors.sol";
 import {CommandEvent} from "../events/Command.sol";
 import {State} from "../utils/State.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 {
@@ -63,3 +64,30 @@ abstract contract CommandBase is OperationBase, CommandEvent {
         return Ids.toCommand(Selectors.command(name), address(this));
     }
 }
+
+/// @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 Settle any remaining native value after command execution.
+    /// The default implementation rejects leftover value by reverting with
+    /// `UnusedValue(remaining)`. Override this hook to refund or redirect
+    /// unused value for specific payable commands.
+    /// @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 virtual {
+        account;
+        uint remaining = Values.drain(budget);
+        if (remaining != 0) revert UnusedValue(remaining);
+    }
+}
+
+

package/{contracts/commands → commands}/Borrow.sol

@@ -16,7 +16,7 @@ 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);
+        emit Command(host, BACTB, input, borrowAgainstCustodyToBalanceId, State.Custodies, State.Balances, false);
     }
 
     /// @dev Override to borrow against a custody position.
@@ -30,7 +30,7 @@ abstract contract BorrowAgainstCustodyToBalance is CommandBase {
 
     function borrowAgainstCustodyToBalance(
         CommandContext calldata c
-    ) external payable onlyCommand(borrowAgainstCustodyToBalanceId, c.target) returns (bytes memory) {
+    ) external 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);
@@ -51,7 +51,7 @@ 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);
+        emit Command(host, BABTB, input, borrowAgainstBalanceToBalanceId, State.Balances, State.Balances, false);
     }
 
     /// @dev Override to borrow against a balance position.
@@ -65,7 +65,7 @@ abstract contract BorrowAgainstBalanceToBalance is CommandBase {
 
     function borrowAgainstBalanceToBalance(
         CommandContext calldata c
-    ) external payable onlyCommand(borrowAgainstBalanceToBalanceId, c.target) returns (bytes memory) {
+    ) external 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);
@@ -86,3 +86,4 @@ abstract contract BorrowAgainstBalanceToBalance is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Burn.sol

@@ -14,7 +14,7 @@ abstract contract Burn is CommandBase {
     uint internal immutable burnId = commandId(NAME);
 
     constructor() {
-        emit Command(host, NAME, "", burnId, State.Balances, State.Empty);
+        emit Command(host, NAME, "", burnId, State.Balances, State.Empty, false);
     }
 
     /// @notice Override to burn or consume the provided balance amount.
@@ -26,7 +26,7 @@ abstract contract Burn is CommandBase {
     /// @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) {
+    function burn(CommandContext calldata c) external onlyCommand(burnId, c.target) returns (bytes memory) {
         (Cur memory state, , ) = cursor(c.state, 1);
 
         while (state.i < state.bound) {
@@ -43,3 +43,4 @@ abstract contract Burn is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Create.sol

@@ -16,14 +16,14 @@ 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);
+        emit Command(host, NAME, input, createId, State.Empty, State.Empty, false);
     }
 
     /// @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) {
+    function create(CommandContext calldata c) external onlyCommand(createId, c.target) returns (bytes memory) {
         (Cur memory request, , ) = cursor(c.request, 1);
 
         while (request.i < request.bound) {
@@ -39,3 +39,4 @@ abstract contract Create is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Credit.sol

@@ -15,7 +15,7 @@ abstract contract CreditAccount is CommandBase {
     uint internal immutable creditAccountId = commandId(NAME);
 
     constructor() {
-        emit Command(host, NAME, Schemas.Recipient, creditAccountId, State.Balances, State.Empty);
+        emit Command(host, NAME, Schemas.Recipient, creditAccountId, State.Balances, State.Empty, false);
     }
 
     /// @notice Override to credit externally managed funds to `account`.
@@ -28,7 +28,7 @@ abstract contract CreditAccount is CommandBase {
 
     function creditAccount(
         CommandContext calldata c
-    ) external payable onlyCommand(creditAccountId, c.target) returns (bytes memory) {
+    ) external 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);
@@ -47,3 +47,4 @@ abstract contract CreditAccount is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Debit.sol

@@ -17,7 +17,7 @@ abstract contract DebitAccount is CommandBase {
     uint internal immutable debitAccountId = commandId(NAME);
 
     constructor() {
-        emit Command(host, NAME, Schemas.Amount, debitAccountId, State.Empty, State.Balances);
+        emit Command(host, NAME, Schemas.Amount, debitAccountId, State.Empty, State.Balances, false);
     }
 
     /// @notice Override to debit externally managed funds from `account`.
@@ -46,7 +46,7 @@ abstract contract DebitAccount is CommandBase {
 
     function debitAccount(
         CommandContext calldata c
-    ) external payable onlyCommand(debitAccountId, c.target) returns (bytes memory) {
+    ) external onlyCommand(debitAccountId, c.target) returns (bytes memory) {
         return debitAccount(c.account, c.request);
     }
 }
@@ -56,3 +56,4 @@ abstract contract DebitAccount is CommandBase {
 
 
 
+

package/commands/Deposit.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { CommandContext, CommandBase, CommandPayable, State } from "./Base.sol";
+import { Cursors, Cur, Schemas, Writer, Writers } from "../Cursors.sol";
+import { Budget, Values } from "../utils/Value.sol";
+
+string constant DEPOSIT = "deposit";
+string constant DEPOSIT_PAYABLE = "depositPayable";
+
+using Cursors for Cur;
+using Writers for Writer;
+
+/// @title Deposit
+/// @notice Command that receives externally sourced assets and records them as BALANCE state.
+/// 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 {
+    uint internal immutable depositId = commandId(DEPOSIT);
+
+    constructor() {
+        emit Command(host, DEPOSIT, Schemas.Amount, depositId, State.Empty, State.Balances, false);
+    }
+
+    /// @notice Override to receive externally sourced funds for `account`.
+    /// Called once per AMOUNT block. A matching BALANCE block is appended to the
+    /// output after each call.
+    /// @param account Recipient account identifier.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount received.
+    function deposit(
+        bytes32 account,
+        bytes32 asset,
+        bytes32 meta,
+        uint amount
+    ) internal virtual;
+
+    function deposit(
+        CommandContext calldata c
+    ) external onlyCommand(depositId, c.target) returns (bytes memory) {
+        (Cur memory request, uint count, ) = cursor(c.request, 1);
+        Writer memory writer = Writers.allocBalances(count);
+
+        while (request.i < request.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
+            deposit(c.account, asset, meta, amount);
+            writer.appendBalance(asset, meta, amount);
+        }
+
+        return request.complete(writer);
+    }
+}
+
+/// @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 {
+    uint internal immutable depositPayableId = commandId(DEPOSIT_PAYABLE);
+
+    constructor() {
+        emit Command(host, DEPOSIT_PAYABLE, Schemas.Amount, depositPayableId, State.Empty, State.Balances, true);
+    }
+
+    /// @notice Override to receive externally sourced funds for `account`.
+    /// Called once per AMOUNT block. A matching BALANCE block is appended to the
+    /// output after each call.
+    /// @param account Recipient account identifier.
+    /// @param asset Asset identifier.
+    /// @param meta Asset metadata slot.
+    /// @param amount Amount received.
+    /// @param budget Mutable native-value budget drawn from `msg.value`.
+    function deposit(
+        bytes32 account,
+        bytes32 asset,
+        bytes32 meta,
+        uint amount,
+        Budget memory budget
+    ) internal virtual;
+
+    function depositPayable(
+        CommandContext calldata c
+    ) external payable onlyCommand(depositPayableId, c.target) returns (bytes memory) {
+        (Cur memory request, uint count, ) = cursor(c.request, 1);
+        Writer memory writer = Writers.allocBalances(count);
+        Budget memory budget = Values.fromMsg();
+
+        while (request.i < request.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
+            deposit(c.account, asset, meta, amount, budget);
+            writer.appendBalance(asset, meta, amount);
+        }
+
+        settleValue(c.account, budget);
+        return request.complete(writer);
+    }
+}
+
+
+
+
+
+
+

package/{contracts/commands → commands}/Liquidate.sol

@@ -19,7 +19,7 @@ abstract contract LiquidateFromBalanceToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, LFBTB, input, liquidateFromBalanceToBalancesId, State.Balances, State.Balances);
+        emit Command(host, LFBTB, input, liquidateFromBalanceToBalancesId, State.Balances, State.Balances, false);
     }
 
     /// @dev Override to liquidate using a balance repayment amount.
@@ -36,7 +36,7 @@ abstract contract LiquidateFromBalanceToBalances is CommandBase {
 
     function liquidateFromBalanceToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(liquidateFromBalanceToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(liquidateFromBalanceToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -59,7 +59,7 @@ abstract contract LiquidateFromCustodyToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, LFCTB, input, liquidateFromCustodyToBalancesId, State.Custodies, State.Balances);
+        emit Command(host, LFCTB, input, liquidateFromCustodyToBalancesId, State.Custodies, State.Balances, false);
     }
 
     /// @dev Override to liquidate using a custody repayment amount.
@@ -76,7 +76,7 @@ abstract contract LiquidateFromCustodyToBalances is CommandBase {
 
     function liquidateFromCustodyToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(liquidateFromCustodyToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(liquidateFromCustodyToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -96,3 +96,4 @@ abstract contract LiquidateFromCustodyToBalances is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Liquidity.sol

@@ -21,7 +21,7 @@ abstract contract AddLiquidityFromCustodiesToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, ALFCTB, input, addLiquidityFromCustodiesToBalancesId, State.Custodies, State.Balances);
+        emit Command(host, ALFCTB, input, addLiquidityFromCustodiesToBalancesId, State.Custodies, State.Balances, false);
     }
 
     /// @dev Override to add liquidity from the current `custodies` stream
@@ -40,7 +40,7 @@ abstract contract AddLiquidityFromCustodiesToBalances is CommandBase {
 
     function addLiquidityFromCustodiesToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(addLiquidityFromCustodiesToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(addLiquidityFromCustodiesToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -61,7 +61,7 @@ abstract contract RemoveLiquidityFromCustodyToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, RLFCTB, input, removeLiquidityFromCustodyToBalancesId, State.Custodies, State.Balances);
+        emit Command(host, RLFCTB, input, removeLiquidityFromCustodyToBalancesId, State.Custodies, State.Balances, false);
     }
 
     /// @dev Override to remove liquidity from a custody position.
@@ -78,7 +78,7 @@ abstract contract RemoveLiquidityFromCustodyToBalances is CommandBase {
 
     function removeLiquidityFromCustodyToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(removeLiquidityFromCustodyToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(removeLiquidityFromCustodyToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -101,7 +101,7 @@ abstract contract AddLiquidityFromBalancesToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, ALFBTB, input, addLiquidityFromBalancesToBalancesId, State.Balances, State.Balances);
+        emit Command(host, ALFBTB, input, addLiquidityFromBalancesToBalancesId, State.Balances, State.Balances, false);
     }
 
     /// @dev Override to add liquidity from the current `balances` stream
@@ -119,7 +119,7 @@ abstract contract AddLiquidityFromBalancesToBalances is CommandBase {
 
     function addLiquidityFromBalancesToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(addLiquidityFromBalancesToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(addLiquidityFromBalancesToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -140,7 +140,7 @@ abstract contract RemoveLiquidityFromBalanceToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, RLFBTB, input, removeLiquidityFromBalanceToBalancesId, State.Balances, State.Balances);
+        emit Command(host, RLFBTB, input, removeLiquidityFromBalanceToBalancesId, State.Balances, State.Balances, false);
     }
 
     /// @dev Override to remove liquidity from a balance position.
@@ -157,7 +157,7 @@ abstract contract RemoveLiquidityFromBalanceToBalances is CommandBase {
 
     function removeLiquidityFromBalanceToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(removeLiquidityFromBalanceToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(removeLiquidityFromBalanceToBalancesId, c.target) returns (bytes memory) {
         (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
         Cur memory request = cursor(c.request);
         Writer memory writer = Writers.allocScaledBalances(stateCount, outScale);
@@ -177,3 +177,4 @@ abstract contract RemoveLiquidityFromBalanceToBalances is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Mint.sol

@@ -19,7 +19,7 @@ abstract contract MintToBalances is CommandBase {
 
     constructor(string memory input, uint scaledRatio) {
         outScale = scaledRatio;
-        emit Command(host, NAME, input, mintToBalancesId, State.Empty, State.Balances);
+        emit Command(host, NAME, input, mintToBalancesId, State.Empty, State.Balances, false);
     }
 
     /// @dev Override to mint balances described by the current `input` stream
@@ -35,7 +35,7 @@ abstract contract MintToBalances is CommandBase {
 
     function mintToBalances(
         CommandContext calldata c
-    ) external payable onlyCommand(mintToBalancesId, c.target) returns (bytes memory) {
+    ) external onlyCommand(mintToBalancesId, c.target) returns (bytes memory) {
         (Cur memory request, uint count, ) = cursor(c.request, 1);
         Writer memory writer = Writers.allocScaledBalances(count, outScale);
 
@@ -51,3 +51,4 @@ abstract contract MintToBalances is CommandBase {
 
 
 
+

package/{contracts/commands → commands}/Pipe.sol

@@ -1,25 +1,25 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext } from "./Base.sol";
-import { Cursors, Cur, Schemas } from "../Cursors.sol";
-import { Accounts } from "../utils/Accounts.sol";
-import { Values } from "../utils/Value.sol";
+import {CommandBase, CommandContext, CommandPayable} from "./Base.sol";
+import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Accounts} from "../utils/Accounts.sol";
+import {Budget, Values} from "../utils/Value.sol";
 
 using Cursors for Cur;
 
-string constant NAME = "pipe";
+string constant NAME = "pipePayable";
 
-/// @title Pipe
+/// @title PipePayable
 /// @notice Command that sequences multiple sub-command STEP invocations in a single transaction.
 /// Each STEP block carries a target node, native value to forward, and an embedded request.
 /// State threads through the steps: each step's output becomes the next step's state.
-/// Admin accounts are not permitted to use `pipe`.
-abstract contract Pipe is CommandBase {
-    uint internal immutable pipeId = commandId(NAME);
+/// Admin accounts are not permitted to use `pipePayable`.
+abstract contract PipePayable is CommandPayable {
+    uint internal immutable pipePayableId = commandId(NAME);
 
     constructor() {
-        emit Command(host, NAME, Schemas.Step, pipeId, 0, 0);
+        emit Command(host, NAME, Schemas.Step, pipePayableId, 0, 0, true);
     }
 
     /// @notice Override to execute a single STEP and return the resulting state.
@@ -42,7 +42,7 @@ abstract contract Pipe is CommandBase {
         bytes32 account,
         bytes memory state,
         bytes calldata steps,
-        Values.Budget memory budget
+        Budget memory budget
     ) internal returns (bytes memory) {
         (Cur memory input, , ) = cursor(steps, 1);
 
@@ -52,20 +52,17 @@ abstract contract Pipe is CommandBase {
             state = dispatchStep(target, account, state, request, spend);
         }
 
+        settleValue(account, budget);
         input.complete();
         return state;
     }
 
-    /// @notice Execute the pipe command.
-    /// Note: any unused `msg.value` is NOT automatically refunded to the caller.
-    function pipe(CommandContext calldata c) external payable onlyCommand(pipeId, c.target) returns (bytes memory) {
+    /// @notice Execute the pipePayable command.
+    function pipePayable(
+        CommandContext calldata c
+    ) external payable onlyCommand(pipePayableId, c.target) returns (bytes memory) {
         if (Accounts.isAdmin(c.account)) revert Accounts.InvalidAccount();
-        Values.Budget memory budget = Values.fromMsg();
+        Budget memory budget = Values.fromMsg();
         return pipe(c.account, c.state, c.request, budget);
     }
 }
-
-
-
-
-

package/commands/Provision.sol

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandContext, CommandBase, CommandPayable, State} from "./Base.sol";
+import {Cursors, Cur, HostAmount, Schemas, Writer, Writers} from "../Cursors.sol";
+import {Budget, Values} from "../utils/Value.sol";
+using Cursors for Cur;
+using Writers for Writer;
+
+string constant PROVISION = "provision";
+string constant PP = "provisionPayable";
+string constant PFB = "provisionFromBalance";
+
+/// @notice Shared provision hook used by both `Provision` and `ProvisionFromBalance`.
+abstract contract ProvisionHook {
+    /// @notice Override to send or provision a custody value.
+    /// Called once per provisioned asset. Implementations should perform only the
+    /// side effect (e.g. transfer or record); output blocks are written by the caller.
+    /// @param account Caller's account identifier.
+    /// @param custody Destination host plus asset amount to provision.
+    function provision(bytes32 account, HostAmount memory custody) internal virtual;
+}
+
+/// @notice Shared provision hook used by `ProvisionPayable`.
+abstract contract ProvisionPayableHook {
+    /// @notice Override to send or provision a custody value.
+    /// Called once per provisioned asset. Implementations should perform only the
+    /// side effect (e.g. transfer or record); output blocks are written by the caller.
+    /// @param account Caller's account identifier.
+    /// @param custody Destination host plus asset amount to provision.
+    /// @param budget Mutable native-value budget drawn from `msg.value`.
+    function provision(
+        bytes32 account,
+        HostAmount memory custody,
+        Budget memory budget
+    ) internal virtual;
+}
+
+/// @title Provision
+/// @notice Command that provisions assets to remote hosts from CUSTODY request blocks.
+/// Each request block supplies the target host plus an asset amount; the output is a CUSTODY state stream.
+abstract contract Provision is CommandBase, ProvisionHook {
+    uint internal immutable provisionId = commandId(PROVISION);
+
+    constructor() {
+        emit Command(host, PROVISION, Schemas.Custody, provisionId, State.Empty, State.Custodies, false);
+    }
+
+    function provision(
+        CommandContext calldata c
+    ) external onlyCommand(provisionId, c.target) returns (bytes memory) {
+        (Cur memory request, uint count, ) = cursor(c.request, 1);
+        Writer memory writer = Writers.allocCustodies(count);
+
+        while (request.i < request.bound) {
+            HostAmount memory custody = request.unpackCustodyValue();
+            provision(c.account, custody);
+            writer.appendCustody(custody);
+        }
+
+        return request.complete(writer);
+    }
+}
+
+/// @title ProvisionPayable
+/// @notice Command that provisions assets to remote hosts from CUSTODY 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 {
+    uint internal immutable provisionPayableId = commandId(PP);
+
+    constructor() {
+        emit Command(host, PP, Schemas.Custody, provisionPayableId, State.Empty, State.Custodies, true);
+    }
+
+    function provisionPayable(
+        CommandContext calldata c
+    ) external payable onlyCommand(provisionPayableId, c.target) returns (bytes memory) {
+        (Cur memory request, uint count, ) = cursor(c.request, 1);
+        Writer memory writer = Writers.allocCustodies(count);
+        Budget memory budget = Values.fromMsg();
+
+        while (request.i < request.bound) {
+            HostAmount memory custody = request.unpackCustodyValue();
+            provision(c.account, custody, budget);
+            writer.appendCustody(custody);
+        }
+
+        settleValue(c.account, budget);
+        return request.complete(writer);
+    }
+}
+
+/// @title ProvisionFromBalance
+/// @notice Command that converts BALANCE state into CUSTODY state for a destination host.
+/// The destination node is read from an optional NODE trailing block; reverts if absent.
+abstract contract ProvisionFromBalance is CommandBase, ProvisionHook {
+    uint internal immutable provisionFromBalanceId = commandId(PFB);
+
+    constructor() {
+        emit Command(host, PFB, Schemas.Node, provisionFromBalanceId, State.Balances, State.Custodies, false);
+    }
+
+    function provisionFromBalance(
+        CommandContext calldata c
+    ) external onlyCommand(provisionFromBalanceId, c.target) returns (bytes memory) {
+        (Cur memory state, uint stateCount, ) = cursor(c.state, 1);
+        Cur memory request = cursor(c.request);
+        Writer memory writer = Writers.allocCustodies(stateCount);
+        uint toHost = request.nodeAfter(0);
+        if (toHost == 0) revert Cursors.ZeroNode();
+
+        while (state.i < state.bound) {
+            (bytes32 asset, bytes32 meta, uint amount) = state.unpackBalance();
+            HostAmount memory custody = HostAmount(toHost, asset, meta, amount);
+            provision(c.account, custody);
+            writer.appendCustody(custody);
+        }
+
+        return state.complete(writer);
+    }
+}
+