@rootzero/contracts 1.15.0 → 1.17.0

package/commands/Relay.sol

@@ -5,28 +5,53 @@ import {Blocks, Execution, Executions, CommandBase, Lanes, Specs} from "./Base.s
 
 using Executions for Execution;
 
-/// @notice Hook implemented by hosts that route funded relay payloads.
-abstract contract RoutePayableHook {
-    /// @notice Override to route an encoded payload through `portal`.
+/// @notice Hook implemented by hosts that forward funded relay payloads.
+abstract contract RelayPayableHook {
+    /// @notice Override to relay an encoded payload to `portal`.
     /// @param portal Destination portal identifier, often the destination host ID.
     /// @param resources Chain-specific destination resources. EVM adapters
     /// may interpret this as packed execution gas and destination value.
     /// @param payload Encoded payload ready for the transport layer.
-    /// @param funds Execution used only for source value available for transport
-    /// fees and destination resource funding.
-    function route(uint portal, uint resources, bytes memory payload, Execution memory funds) internal virtual;
+    /// @param funds Execution used for source value available for transport fees
+    /// and destination resource funding.
+    function relayTo(uint portal, uint resources, bytes memory payload, Execution memory funds) internal virtual;
 }
 
 /// @title RelayPayable
-/// @notice Command that forwards one RELAY block to a host-defined relay hook.
+/// @notice Command that forwards one RELAY block without pipeline state.
+abstract contract RelayPayable is CommandBase, RelayPayableHook {
+    uint private immutable descriptor;
+
+    constructor() {
+        (, descriptor) = command("relayPayable", Specs.Empty, Specs.Relay, Specs.Empty, 0, true, false);
+    }
+
+    /// @notice Relay one RELAY input block with the command account and empty state.
+    function relayPayable(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external payable onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 1);
+        (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
+        bytes memory context = Blocks.context(account, bytes(state), bytes(payload));
+
+        relayTo(portal, resources, context, exec);
+
+        return close(exec, account);
+    }
+}
+
+/// @title RelayBalancePayable
+/// @notice Command that forwards required BALANCE state with one RELAY block.
 /// Reverts unless the input contains exactly one RELAY block, preventing
 /// the same state from being duplicated across multiple relays.
 /// Produces no output state.
-abstract contract RelayPayable is CommandBase, RoutePayableHook {
+abstract contract RelayBalancePayable is CommandBase, RelayPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("relayPayable", Specs.Any, Specs.Relay, Specs.Empty, 0, true, false);
+        (, descriptor) = command("relayBalancePayable", Specs.Balance, Specs.Relay, Specs.Empty, 0, true, false);
     }
 
     /// @notice Relay one RELAY input block with the command account and current state.
@@ -34,16 +59,16 @@ abstract contract RelayPayable is CommandBase, RoutePayableHook {
     /// @param input Exactly one RELAY block.
     /// @return Empty output state.
     /// @return Remaining native value as a refund transaction stream.
-    function relayPayable(
+    function relayBalancePayable(
         bytes32 account,
         bytes calldata state,
         bytes calldata input
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 1);
+        Execution memory exec = openCommand(state, input, descriptor, 1);
         (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
         bytes memory context = Blocks.context(account, bytes(state), bytes(payload));
 
-        route(portal, resources, context, exec);
+        relayTo(portal, resources, context, exec);
 
         return close(exec, account);
     }

package/commands/Settle.sol

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {SettleHook} from "../core/Settlement.sol";
+import {Action} from "../annotations/Action.sol";
+import {Actions} from "../utils/Actions.sol";
+import {Blocks} from "../codec/Blocks.sol";
+import {Reader, Readers} from "../codec/Readers.sol";
+
+using Executions for Execution;
+using Readers for Reader;
+
+/// @notice Hook implemented by hosts that settle positions using native value.
+abstract contract SettlePayableHook {
+    /// @notice Override to settle one position for `account` with a shared value budget.
+    /// @param account Account whose position is being settled.
+    /// @param asset Identifier for the asset side.
+    /// @param amount Quantity on the asset side.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity on the liability side.
+    /// @param funds Mutable execution used only for its remaining native-value budget.
+    function settle(
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt,
+        Execution memory funds
+    ) internal virtual;
+}
+
+/// @title Settle
+/// @notice Command that consumes POSITION state blocks through a virtual hook.
+abstract contract Settle is CommandBase, SettleHook, Action {
+    uint private immutable descriptor;
+    uint private immutable id;
+
+    constructor() {
+        (id, descriptor) = command("settle", Specs.Position, Specs.Empty, Specs.Empty, 0, false, false);
+        action(id, Actions.Settle);
+    }
+
+    /// @notice Return the registered SETTLE command ID.
+    function settleId() internal view returns (uint) {
+        return id;
+    }
+
+    /// @notice Settle each POSITION block from the command state.
+    /// @param state POSITION block stream.
+    /// @return Empty output state.
+    /// @return Empty transaction stream.
+    function settle(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
+            settle(account, asset, amount, liability, debt);
+        }
+
+        return close(exec, account);
+    }
+}
+
+/// @title SettlePayable
+/// @notice Funded command that consumes POSITION state blocks through a virtual hook.
+abstract contract SettlePayable is CommandBase, SettlePayableHook, Action {
+    uint private immutable descriptor;
+
+    constructor() {
+        uint id;
+        (id, descriptor) = command("settlePayable", Specs.Position, Specs.Empty, Specs.Empty, 0, true, false);
+        action(id, Actions.Settle);
+    }
+
+    /// @notice Settle each POSITION block with access to a shared native-value budget.
+    /// @param state POSITION block stream.
+    /// @return Empty output state.
+    /// @return Remaining native value as a refund transaction stream.
+    function settlePayable(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external payable onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
+            settle(account, asset, amount, liability, debt, exec);
+        }
+
+        return close(exec, account);
+    }
+}
+
+/// @title InternalSettle
+/// @notice Extends the advertised settle command with memory-state pipeline dispatch.
+/// @dev This adapter is not a separate command. It uses the command ID and settlement hook
+/// inherited from `Settle` while accepting the state location used by `Pipeline`.
+abstract contract InternalSettle is Settle {
+    /// @notice Execute the inherited settle command from an internal pipeline.
+    /// @param account Account for which each position is settled.
+    /// @param state POSITION block stream held in pipeline memory.
+    /// @param input Empty input required by the command schema.
+    /// @param value Native value assigned to the command; must be zero.
+    /// @return output Empty output state.
+    /// @return transactions Empty transaction stream.
+    function executeSettle(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata input,
+        uint128 value
+    ) internal returns (bytes memory, bytes memory) {
+        if (value != 0) revert ValueNotAllowed();
+        if (input.length != 0) revert Executions.ZeroStride();
+        if (state.length == 0) revert Blocks.EmptyRun();
+
+        Reader memory reader = Readers.open(state);
+        while (reader.more()) {
+            (bytes32 asset, uint amount, bytes32 liability, uint debt) = reader.unpackPosition();
+            settle(account, asset, amount, liability, debt);
+        }
+
+        return ("", "");
+    }
+}

package/commands/Withdraw.sol

@@ -36,9 +36,9 @@ abstract contract Withdraw is CommandBase, WithdrawHook, Action {
     function withdraw(
         bytes32 account,
         bytes calldata state,
-        bytes calldata
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openState(state, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);

package/commands/admin/AllowAssets.sol

@@ -28,10 +28,10 @@ abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     /// @return Empty transaction stream.
     function allowAssets(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);

package/commands/admin/Allowance.sol

@@ -12,7 +12,7 @@ abstract contract AllowanceHook {
     /// or another host-specific authorization record.
     /// @param peer Host node receiving the allowed cap.
     /// @param asset Asset identifier.
-    /// @param amount Allowed cap amount.
+    /// @param amount Allowed cap amount. A zero amount MUST revoke the allowance.
     function allowance(uint peer, bytes32 asset, uint amount) internal virtual;
 }
 
@@ -32,10 +32,10 @@ abstract contract Allowance is AdminBase, AllowanceHook {
     /// @return Empty transaction stream.
     function allowance(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (uint peer, bytes32 asset, uint amount) = exec.unpackAllowance(Lanes.Input);

package/commands/admin/Annotate.sol

@@ -21,10 +21,10 @@ abstract contract Annotate is AdminBase {
     /// @return Empty transaction stream.
     function annotate(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (uint entity, bytes calldata data) = exec.unpackAnnotation(Lanes.Input);

package/commands/admin/Appoint.sol

@@ -22,10 +22,10 @@ abstract contract Appoint is GuardianAccess, AdminBase {
     /// @return Empty transaction stream.
     function appoint(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);

package/commands/admin/Authorize.sol

@@ -27,10 +27,10 @@ abstract contract Authorize is AdminBase {
     /// @return Empty transaction stream.
     function authorize(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);

package/commands/admin/DenyAssets.sol

@@ -28,10 +28,10 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     /// @return Empty transaction stream.
     function denyAssets(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);

package/commands/admin/Dismiss.sol

@@ -22,10 +22,10 @@ abstract contract Dismiss is GuardianAccess, AdminBase {
     /// @return Empty transaction stream.
     function dismiss(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             bytes32 guardian = exec.unpackAccount(Lanes.Input);

package/commands/admin/Execute.sol

@@ -24,14 +24,14 @@ abstract contract ExecutePayable is RawNodeCalls, AdminBase {
     /// @return Remaining native value as a refund transaction stream.
     function executePayable(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external payable onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             (uint target, uint resources, bytes calldata data) = exec.unpackCall(Lanes.Input);
-            rawCall(target, exec.useValue(resources), data);
+            rawCall(target, exec.useResourceValue(resources), data);
         }
 
         return close(exec, account);

package/commands/admin/Unauthorize.sol

@@ -27,10 +27,10 @@ abstract contract Unauthorize is AdminBase {
     /// @return Empty transaction stream.
     function unauthorize(
         bytes32 account,
-        bytes calldata,
+        bytes calldata state,
         bytes calldata input
     ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openInput(input, descriptor, 0);
+        Execution memory exec = openCommand(state, input, descriptor, 0);
 
         while (exec.more()) {
             uint node = exec.unpackNode(Lanes.Input);

package/core/Endpoint.sol

@@ -43,19 +43,6 @@ abstract contract EndpointBase is EndpointEvent, Label, Schema {
         return descriptor;
     }
 
-    /// @notice Open an endpoint input stream with an expected batch count.
-    /// @param source Input block stream to open.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param batches Required batch count, or zero to accept the input count.
-    /// @return exec Execution with its output buffer metadata initialized for the input batch count.
-    function openInput(
-        bytes calldata source,
-        uint descriptor,
-        uint batches
-    ) internal view returns (Execution memory exec) {
-        return Executions.openInput(source, descriptor, batches);
-    }
-
     /// @notice Finalize an execution output and return its encoded block stream.
     /// @param exec Completed endpoint execution.
     /// @return Encoded output block stream.
@@ -63,3 +50,18 @@ abstract contract EndpointBase is EndpointEvent, Label, Schema {
         return Executions.finish(exec);
     }
 }
+
+/// @title InputEndpointBase
+/// @notice Shared input opening for endpoint families that have only an input lane.
+/// Commands intentionally do not inherit this base because they must open state
+/// and input together through `openCommand`.
+abstract contract InputEndpointBase is EndpointBase {
+    /// @notice Open an endpoint input stream with an expected batch count.
+    function openInput(
+        bytes calldata input,
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        return Executions.openInput(input, descriptor, batches);
+    }
+}

package/core/Pipeline.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {Decoders, Cur, Readers, Reader} from "../Codec.sol";
-import {Settlement} from "./Settlement.sol";
+import {PostHook} from "./Settlement.sol";
 import {Budget, Budgets} from "../execution/Budget.sol";
 
 using Decoders for Cur;
@@ -11,14 +11,14 @@ using Budgets for Budget;
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is Settlement {
+abstract contract Pipeline is PostHook {
     /// @dev Thrown when the pipeline finishes with non-empty threaded state.
     error UnexpectedState();
 
     /// @notice Override to dispatch one piped step.
     /// Called once per STEP block. The returned state becomes the state passed to
     /// the next step, and the final returned state must be empty. Returned
-    /// transactions are decoded and passed individually to `settle` before the next step runs.
+    /// transactions are decoded and passed individually to `post` before the next step runs.
     /// @param cmd Command node ID to invoke or handle.
     /// @param account Account identifier for the piped context.
     /// @param state Current threaded state block stream.
@@ -42,16 +42,16 @@ abstract contract Pipeline is Settlement {
     /// @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 cur = Decoders.open(steps, 1);
+        Cur memory cur = Decoders.open(steps);
 
         while (cur.more()) {
             (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
             Reader memory txs;
-            (state, txs.source) = dispatch(cmd, account, state, input, budget.use(resources));
+            (state, txs.source) = dispatch(cmd, account, state, input, budget.useResourceValue(resources));
 
             while (txs.more()) {
                 (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
-                settle(from, to, asset, amount);
+                post(from, to, asset, amount);
             }
         }
 

package/core/Settlement.sol

@@ -21,19 +21,48 @@ abstract contract CreditAccountHook {
     function creditAccount(bytes32 account, bytes32 asset, uint amount) internal virtual;
 }
 
+/// @title PostHook
+/// @notice Hook for posting one transaction between accounts.
+abstract contract PostHook {
+    /// @notice Override to post one transaction.
+    function post(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal virtual;
+}
+
+/// @title SettleHook
+/// @notice Hook for settling one asset-liability position.
+abstract contract SettleHook {
+    /// @notice Override to settle one position for `account`.
+    function settle(
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal virtual;
+}
+
 /// @title Settlement
-/// @notice Settles decoded transactions through debit and credit account hooks.
-abstract contract Settlement is DebitAccountHook, CreditAccountHook {
-    /// @notice Settle one transaction by debiting its source and crediting its destination.
+/// @notice Default account-hook implementation for transaction posting and position settlement.
+abstract contract Settlement is PostHook, SettleHook, DebitAccountHook, CreditAccountHook {
+    /// @notice Post one transaction by debiting its source and crediting its destination.
     /// Returns without calling either hook when `amount` is zero and skips either
     /// operation when the corresponding account is zero.
-    /// @param from Source account identifier.
-    /// @param to Destination account identifier.
-    /// @param asset Asset identifier.
-    /// @param amount Token amount.
-    function settle(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal {
+    function post(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal virtual override {
         if (amount == 0) return;
         if (from != 0) debitAccount(from, asset, amount);
         if (to != 0) creditAccount(to, asset, amount);
     }
+
+    /// @notice Settle one position by crediting its asset and debiting its liability.
+    /// Skips either operation when its corresponding amount is zero.
+    function settle(
+        bytes32 account,
+        bytes32 asset,
+        uint amount,
+        bytes32 liability,
+        uint debt
+    ) internal virtual override {
+        if (amount != 0) creditAccount(account, asset, amount);
+        if (debt != 0) debitAccount(account, liability, debt);
+    }
 }

package/core/Types.sol

@@ -27,6 +27,14 @@ struct AccountAmount {
     uint amount;
 }
 
+/// @notice Host-scoped asset shape.
+struct HostAsset {
+    /// @dev Host node identifier.
+    uint host;
+    /// @dev Asset identifier.
+    bytes32 asset;
+}
+
 /// @notice Host-scoped asset and amount shape.
 struct HostAmount {
     /// @dev Host node identifier.
@@ -59,7 +67,19 @@ struct HostAccountAmount {
     uint amount;
 }
 
-/// @notice Transfer payload used by transaction blocks and peer settlement.
+/// @notice Asset and liability pair threaded as live pipeline state.
+struct Position {
+    /// @dev Identifier for the asset side.
+    bytes32 asset;
+    /// @dev Quantity on the asset side.
+    uint amount;
+    /// @dev Identifier for the liability side.
+    bytes32 liability;
+    /// @dev Quantity owed on the liability side.
+    uint debt;
+}
+
+/// @notice Transfer payload used by transaction blocks and peer posting.
 struct Tx {
     /// @dev Sender account identifier.
     bytes32 from;

package/docs/Schema.md

@@ -161,8 +161,58 @@ with no payload, use a zero-payload block such as `#unit`.
 
 Endpoint descriptors currently use a narrower convention than the full block
 grammar: each state, input, or output lane is a single run of blocks, without
-additional global items. Future protocol surfaces may use the more flexible
-top-level structure.
+additional global items. Endpoint decoder opening requires that run to consume
+the complete supplied lane; a trailing block with another key is invalid.
+Lower-level cursor scanning may still intentionally open only a prefix run.
+Those lower layers retain only the raw block count; descriptor strides are
+applied and lane groups reconciled once when an endpoint execution opens.
+Future protocol surfaces may use the more flexible top-level structure.
+
+For commands, complete-lane validation is also a state-safety rule. State is a
+linear value owned by the current pipeline step, not optional context that a
+command may disregard. Every command must account for the complete supplied
+state by consuming it, transforming and returning it, forwarding it intact, or
+reverting. A command whose descriptor declares an empty state lane must reject
+non-empty state. A command that accepts state must validate the complete stream
+against its declared schema; accepting only a prefix and silently dropping the
+remainder is invalid.
+
+## Live Pipeline State
+
+`#balance`, `#custody`, and `#position` are live state carried between command
+steps for the active account. A position atomically pairs an asset side with a
+liability side:
+
+```txt
+position { bytes32 asset, uint amount, bytes32 liability, uint debt }
+```
+
+The pair is deliberately general. The asset side represents value acquired or
+controlled, and the liability side represents value owed or required. Commands
+may preserve or replace either side and return a new position. The terminal
+`settle` command consumes the pair. Position state is transient protocol state;
+rewriting it does not by itself create, discharge, or replace an obligation
+persisted by a host or external protocol. The responsible command hook must
+perform or verify those effects. A command must not ignore a supplied position:
+it must explicitly consume, transform, forward, or reject it, so neither its
+asset nor its debt can disappear accidentally.
+
+This representation supports ordinary forward transformations as well as
+backward composition. For example, an exact-output route can carry its desired
+asset while successive hops replace the upstream liability:
+
+```txt
+position(C, 100, C, 100)
+→ position(C, 100, B, 50)
+→ position(C, 100, A, 25)
+→ settle
+```
+
+“Backward” describes how requirements are composed from the desired result
+toward the source. Pipeline execution is not reversed: STEP blocks always run
+forward in their encoded order. Exact-output routing is only an example;
+borrowing, refinancing, collateral transformation, callback obligations,
+cross-host claims, fees, and netting can use the same position state.
 
 ## Field Aliases
 

package/execution/Budget.sol

@@ -19,15 +19,23 @@ library Budgets {
         budget.remaining = msg.value;
     }
 
+    /// @notice Deduct an exact native value from `budget`.
+    /// @param budget Mutable budget to debit.
+    /// @param value Native value to consume in wei.
+    /// @return The consumed native value.
+    function useValue(Budget memory budget, uint value) internal pure returns (uint) {
+        if (value > budget.remaining) revert InsufficientValue();
+        budget.remaining -= value;
+        return value;
+    }
+
     /// @notice Deduct the EVM value lane of `resources` from `budget`.
     /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param budget Mutable budget to debit.
     /// @param resources Packed resources whose low 128 bits contain native value.
     /// @return value Native value to forward in wei.
-    function use(Budget memory budget, uint resources) internal pure returns (uint128 value) {
-        value = uint128(resources);
-        if (value > budget.remaining) revert InsufficientValue();
-        budget.remaining -= value;
+    function useResourceValue(Budget memory budget, uint resources) internal pure returns (uint128) {
+        return uint128(useValue(budget, uint128(resources)));
     }
 
     /// @notice Remove and return all remaining value from `budget`.