@rootzero/contracts 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.25.0
+
+### Breaking Changes
+
+- Changed `Pipeline.pipe` to accept a scalar `uint` budget and return the
+  remaining scalar budget. The standalone mutable `Budget` type remains
+  available for other funded execution flows.
+- Split the pipeline hook from its standard implementation. `PipePayablePort`
+  now inherits only `PipeHook`; hosts that want the built-in pipeline must
+  compose `Pipeline` explicitly, while custom hosts may implement the hook
+  without inheriting the standard dispatch and posting implementation.
+- Changed `Decoders.open` to wrap the complete non-empty calldata source as an
+  ungrouped cursor. Code that needs the former counted first-homogeneous-run
+  behavior must use the new `Decoders.batch` helper.
+
+### Added
+
+- Added scalar `Budgets.useValue` and `Budgets.useResourceValue` overloads, and
+  `Executions.drainBudget` for transferring an execution budget as a `uint`.
+- Added `PipeHook` to the `Core.sol` and `Endpoints.sol` package barrels.
+- Added `Blocks.expectKey` and key-only `Decoders.consume` and
+  `Executions.consume` overloads for validating blocks whose payload shape is
+  established by specialized decoding logic.
+- Added `Blocks.require1`, `require2`, `require4`, `require8`, and `require16`,
+  completing the fixed-width validation family alongside `require32`.
+
+### Changed
+
+- Specialized built-in composite block unpackers to validate their known keys
+  directly instead of constructing and evaluating generic specifications.
+- Specialized fixed-width block validation, empty-block inspection, and
+  key-only `takeBlock` paths to avoid redundant specification and calldata
+  work.
+- Pipeline execution now validates the complete STEP source and rejects a
+  trailing block with a different key instead of silently stopping after the
+  first homogeneous run.
+- Simplified internal debit-account output allocation to use the fixed-width
+  input size directly.
+
 ## 1.24.0
 
 ### Breaking Changes

package/Core.sol

@@ -14,7 +14,7 @@ import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Admins, CommandHost, Guardians, Host, HostIntroduction, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./core/Calls.sol";
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
-import { Pipeline } from "./core/Pipeline.sol";
+import { PipeHook, Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";
 import { CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";

package/Endpoints.sol

@@ -6,6 +6,7 @@ pragma solidity ^0.8.33;
 
 // Shared endpoint hooks
 import {Flags} from "./codec/Descriptors.sol";
+import {PipeHook} from "./core/Pipeline.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands

package/README.md

@@ -366,13 +366,15 @@ running the next step. This is the core of `Pipeline.pipe`:
 ```solidity
 while (cur.more()) {
     (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
+    uint128 value;
+    (budget, value) = Budgets.useResourceValue(budget, resources);
     Reader memory transactions;
     (state, transactions.source) = dispatch(
         cmd,
         account,
         state,
         input,
-        budget.useResourceValue(resources)
+        value
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
@@ -382,6 +384,9 @@ while (cur.more()) {
 if (state.length != 0) revert UnexpectedState();
 ```
 
+`Pipeline.pipe` takes the available native-value budget as a `uint` and returns
+the remaining budget after every step has executed.
+
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
 `#amount` input into `#balance` state, and `payout` consumes that state
 toward a recipient. Because a pipeline is just blocks, it is also the unit of
@@ -482,11 +487,11 @@ names, access sets, balances — from logs alone, with no artifact files.
 Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
-  `Settlement`, `Pipeline`, `Portal`, validator
+  `Settlement`, `PipeHook`, `Pipeline`, `Portal`, validator
 - `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, `Flags`,
   codec helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
-  mixins, their hooks, and `Flags`
+  mixins, their hooks (including `PipeHook`), and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
   `Reader`/`Readers`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
   `Specs`

package/codec/Blocks.sol

@@ -100,16 +100,33 @@ library Blocks {
         end = body + len;
     }
 
+    /// @notice Validate a known block key and return its payload bounds.
+    /// @dev DANGER: This performs an unchecked calldata read and validates only
+    /// the key. The caller must validate the known payload shape and returned end.
+    /// @param abs Absolute calldata position of the header.
+    /// @param key Expected block key.
+    /// @return body Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function expectKey(uint abs, bytes4 key) internal pure returns (uint body, uint end) {
+        uint len = header(abs, key);
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + len;
+        }
+    }
+
     /// @dev Validate the key and exact payload size of a fixed-width block.
     /// @param abs Absolute calldata position of the header.
-    /// @param spec Expected block specification.
+    /// @param key Expected block key.
     /// @param size Expected payload length.
     /// @return body Absolute position of the payload.
     /// @return end Absolute position after the payload.
-    function expectFixed(uint abs, uint spec, uint size) private pure returns (uint body, uint end) {
-        if (header(abs, Specs.key(spec)) != size) revert InvalidBlock();
-        body = abs + Sizes.Header;
-        end = body + size;
+    function expectFixed(uint abs, bytes4 key, uint size) private pure returns (uint body, uint end) {
+        if (header(abs, key) != size) revert InvalidBlock();
+        unchecked {
+            body = abs + Sizes.Header;
+            end = body + size;
+        }
     }
 
     /// @notice Validate an empty block at an absolute calldata position.
@@ -139,8 +156,9 @@ library Blocks {
     /// @param key Expected block key.
     /// @return Whether the expected key occurs with a zero-length payload.
     function isEmpty(uint abs, uint end, bytes4 key) internal pure returns (bool) {
-        if (!hasAt(abs, end, key)) return false;
-        return uint32(uint(read32(abs)) >> 192) == 0;
+        if (abs > end || Sizes.Header > end - abs) return false;
+        uint head = uint(read32(abs));
+        return uint32(head >> 224) == uint32(key) && uint32(head >> 192) == 0;
     }
 
     /// @notice Find the first block with `key` at or after absolute position `abs`.
@@ -1080,6 +1098,46 @@ library Blocks {
         }
     }
 
+    /// @notice Require the byte at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected byte.
+    function require1(uint abs, bytes1 expected) internal pure {
+        if (read1(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the two bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected two-byte value.
+    function require2(uint abs, bytes2 expected) internal pure {
+        if (read2(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the four bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected four-byte value.
+    function require4(uint abs, bytes4 expected) internal pure {
+        if (read4(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the eight bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected eight-byte value.
+    function require8(uint abs, bytes8 expected) internal pure {
+        if (read8(abs) != expected) revert UnexpectedValue();
+    }
+
+    /// @notice Require the sixteen bytes at an absolute calldata position to match `expected`.
+    /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
+    /// @param abs Absolute calldata position.
+    /// @param expected Expected sixteen-byte value.
+    function require16(uint abs, bytes16 expected) internal pure {
+        if (read16(abs) != expected) revert UnexpectedValue();
+    }
+
     /// @notice Require the word at an absolute calldata position to match `expected`.
     /// @dev DANGER: Unchecked calldata read. Values beyond calldata are zero-padded.
     /// @param abs Absolute calldata position.
@@ -1106,7 +1164,7 @@ library Blocks {
     /// @return a First payload word.
     /// @return end Absolute position after the block.
     function unpack32(uint abs, uint spec) internal pure returns (bytes32 a, uint end) {
-        (abs, end) = expectFixed(abs, spec, 32);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 32);
         a = read32(abs);
     }
 
@@ -1117,7 +1175,7 @@ library Blocks {
     /// @return b Second payload word.
     /// @return end Absolute position after the block.
     function unpack64(uint abs, uint spec) internal pure returns (bytes32 a, bytes32 b, uint end) {
-        (abs, end) = expectFixed(abs, spec, 64);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 64);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1135,7 +1193,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, uint end) {
-        (abs, end) = expectFixed(abs, spec, 96);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 96);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1155,7 +1213,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, uint end) {
-        (abs, end) = expectFixed(abs, spec, 128);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 128);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1177,7 +1235,7 @@ library Blocks {
         uint abs,
         uint spec
     ) internal pure returns (bytes32 a, bytes32 b, bytes32 c, bytes32 d, bytes32 e, uint end) {
-        (abs, end) = expectFixed(abs, spec, 160);
+        (abs, end) = expectFixed(abs, Specs.key(spec), 160);
         assembly ("memory-safe") {
             a := calldataload(abs)
             b := calldataload(add(abs, 0x20))
@@ -1653,7 +1711,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint entity, bytes calldata stream, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Annotation);
+        (abs, limit) = expectKey(abs, Keys.Annotation);
         assembly ("memory-safe") {
             entity := calldataload(abs)
         }
@@ -1671,7 +1729,7 @@ library Blocks {
         uint abs
     ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Context);
+        (abs, limit) = expectKey(abs, Keys.Context);
         assembly ("memory-safe") {
             account := calldataload(abs)
         }
@@ -1692,7 +1750,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint cmd, uint resources, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Step);
+        (abs, limit) = expectKey(abs, Keys.Step);
         assembly ("memory-safe") {
             cmd := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1711,7 +1769,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint target, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Call);
+        (abs, limit) = expectKey(abs, Keys.Call);
         assembly ("memory-safe") {
             target := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1730,7 +1788,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata input, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Relay);
+        (abs, limit) = expectKey(abs, Keys.Relay);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1749,7 +1807,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint portal, uint resources, bytes calldata payload, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Dispatch);
+        (abs, limit) = expectKey(abs, Keys.Dispatch);
         assembly ("memory-safe") {
             portal := calldataload(abs)
             resources := calldataload(add(abs, 0x20))
@@ -1765,7 +1823,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackLabel(uint abs) internal pure returns (bytes32 namespace, string memory name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Label);
+        (abs, limit) = expectKey(abs, Keys.Label);
         assembly ("memory-safe") {
             namespace := calldataload(abs)
         }
@@ -1783,7 +1841,7 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackSchema(uint abs) internal pure returns (uint spec, string memory body, bytes32 name, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Schema);
+        (abs, limit) = expectKey(abs, Keys.Schema);
         assembly ("memory-safe") {
             spec := calldataload(abs)
         }
@@ -1810,7 +1868,7 @@ library Blocks {
         uint abs
     ) internal pure returns (uint handler, uint resources, bytes32 key, bytes calldata witness, uint end) {
         uint limit;
-        (abs, limit) = expect(abs, Specs.Recover);
+        (abs, limit) = expectKey(abs, Keys.Recover);
         assembly ("memory-safe") {
             handler := calldataload(abs)
             resources := calldataload(add(abs, 0x20))

package/codec/Decoders.sol

@@ -32,10 +32,18 @@ library Decoders {
         cur.state = Cursors.wrap(source[i:], 0, 0);
     }
 
-    /// @notice Open the first homogeneous run in `source`.
-    /// @param source Calldata block stream to open.
-    /// @return cur Cursor spanning the first homogeneous run.
+    /// @notice Open a non-empty calldata source as an ungrouped cursor.
+    /// @param source Calldata region to open.
+    /// @return cur Cursor spanning the complete source.
     function open(bytes calldata source) internal pure returns (Cur memory cur) {
+        if (source.length == 0) revert Blocks.EmptyRun();
+        cur.state = Cursors.wrap(source, 0, 0);
+    }
+
+    /// @notice Open the first homogeneous batch in `source`.
+    /// @param source Calldata block stream to open.
+    /// @return cur Counted cursor spanning the first homogeneous batch.
+    function batch(bytes calldata source) internal pure returns (Cur memory cur) {
         (uint abs, uint limit) = Cursors.bounds(source);
         if (abs == limit) revert Blocks.EmptyRun();
 
@@ -69,6 +77,18 @@ library Decoders {
         cur.state = cur.state.seekAbs(end);
     }
 
+    /// @notice Validate a known key and consume the next block from a cursor.
+    /// @dev Validates no payload-size constraint beyond proving the complete block
+    /// lies within the cursor's logical region.
+    /// @param cur Cursor advanced over the complete block.
+    /// @param key Expected block key.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function consume(Cur memory cur, bytes4 key) internal pure returns (uint abs, uint end) {
+        (abs, end) = Blocks.expectKey(cur.state.absolute(), key);
+        cur.state = cur.state.seekAbs(end);
+    }
+
     /// @notice Consume a matching empty block from a cursor when present.
     /// @param cur Cursor advanced only when the matching block is empty.
     /// @param key Expected block key.
@@ -268,7 +288,7 @@ library Decoders {
     /// @return out Cursor spanning the complete encoded block.
     function takeBlock(Cur memory cur, bytes4 key) internal pure returns (Cur memory out) {
         uint abs = cur.state.absolute();
-        (, uint end) = consume(cur, Specs.create(key, 0, 0, 0));
+        (, uint end) = consume(cur, key);
         out.state = Cursors.create(abs, end - abs, 0, 0, 0);
     }
 

package/commands/Base.sol

@@ -99,10 +99,7 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        bytes32 account;
-        bytes calldata state;
-        bytes calldata input;
-        (account, state, input) = unpackCommandContext(context);
+        (bytes32 account, bytes calldata state, bytes calldata input) = unpackCommandContext(context);
         exec = Executions.open(state, input, descriptor, batches);
         exec.account = account;
     }

package/commands/Debit.sol

@@ -67,11 +67,8 @@ abstract contract DebitAccountInternal is DebitAccount {
     ) internal returns (bytes memory, bytes memory) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert Executions.ZeroStride();
-        if (input.length == 0) revert Blocks.EmptyRun();
-
-        Cur memory cur = Decoders.wrap(input);
-        uint count = input.length / Sizes.Amount;
-        bytes memory output = new bytes(count * Sizes.Balance);
+        Cur memory cur = Decoders.open(input);
+        bytes memory output = new bytes(input.length);
         uint i;
 
         while (cur.more()) {

package/commands/admin/Base.sol

@@ -13,10 +13,7 @@ abstract contract AdminBase is NodeAccess, CommandBase {
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        bytes32 account;
-        bytes calldata state;
-        bytes calldata input;
-        (account, state, input) = unpackCommandContext(context);
+        (bytes32 account, bytes calldata state, bytes calldata input) = unpackCommandContext(context);
         enforceAdmin(account, msg.sender);
         exec = Executions.open(state, input, descriptor, batches);
         exec.account = account;

package/core/Pipeline.sol

@@ -3,15 +3,25 @@ pragma solidity ^0.8.33;
 
 import {Decoders, Cur, Readers, Reader} from "../Codec.sol";
 import {PostHook} from "./Settlement.sol";
-import {Budget, Budgets} from "../execution/Budget.sol";
+import {Budgets} from "../execution/Budget.sol";
 
 using Decoders for Cur;
 using Readers for Reader;
-using Budgets for Budget;
+
+/// @notice Hook implemented by hosts that execute encoded step streams.
+abstract contract PipeHook {
+    /// @notice Execute a step stream and return its remaining native-value budget.
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        uint budget
+    ) internal virtual returns (uint remaining);
+}
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is PostHook {
+abstract contract Pipeline is PipeHook, PostHook {
     /// @dev Thrown when the pipeline finishes with non-empty threaded state.
     error UnexpectedState();
 
@@ -36,18 +46,26 @@ abstract contract Pipeline is PostHook {
 
     /// @notice Execute a STEP block stream through the pipeline.
     /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
-    /// Callers remain responsible for settling any unspent value in `budget`.
+    /// Callers remain responsible for settling the returned unspent value.
     /// @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 {
+    /// @param budget Native-value budget shared across all steps.
+    /// @return remaining Native value remaining after every step executes.
+    function pipe(
+        bytes32 account,
+        bytes memory state,
+        bytes calldata steps,
+        uint budget
+    ) internal virtual override returns (uint remaining) {
         Cur memory cur = Decoders.open(steps);
 
         while (cur.more()) {
             (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
+            uint128 value;
+            (budget, value) = Budgets.useResourceValue(budget, resources);
             Reader memory txs;
-            (state, txs.source) = dispatch(cmd, account, state, input, budget.useResourceValue(resources));
+            (state, txs.source) = dispatch(cmd, account, state, input, value);
 
             while (txs.more()) {
                 (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
@@ -56,5 +74,6 @@ abstract contract Pipeline is PostHook {
         }
 
         if (state.length != 0) revert UnexpectedState();
+        return budget;
     }
 }

package/execution/Budget.sol

@@ -29,6 +29,15 @@ library Budgets {
         return value;
     }
 
+    /// @notice Deduct an exact native value from a scalar budget.
+    /// @param budget Remaining native value in wei.
+    /// @param value Native value to consume in wei.
+    /// @return remaining Native value remaining after the deduction.
+    function useValue(uint budget, uint value) internal pure returns (uint remaining) {
+        if (value > budget) revert InsufficientValue();
+        remaining = budget - 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.
@@ -38,6 +47,19 @@ library Budgets {
         return uint128(useValue(budget, uint128(resources)));
     }
 
+    /// @notice Deduct the EVM value lane of `resources` from a scalar budget.
+    /// @param budget Remaining native value in wei.
+    /// @param resources Packed resources whose low 128 bits contain native value.
+    /// @return remaining Native value remaining after the deduction.
+    /// @return value Native value consumed from the budget.
+    function useResourceValue(
+        uint budget,
+        uint resources
+    ) internal pure returns (uint remaining, uint128 value) {
+        value = uint128(resources);
+        remaining = useValue(budget, value);
+    }
+
     /// @notice Remove and return all remaining value from `budget`.
     /// @param budget Mutable budget to drain.
     /// @return value Native value removed from the budget.

package/execution/Execution.sol

@@ -246,6 +246,20 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Validate a known key and consume the next block from an execution decoder lane.
+    /// @dev Validates no payload-size constraint beyond proving the complete block
+    /// lies within the selected lane's logical region.
+    /// @param exec Execution whose selected decoder cursor is advanced over the complete block.
+    /// @param lane Execution decoder lane to select.
+    /// @param key Expected block key.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function consume(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (uint abs, uint end) {
+        uint cur = exec.decoders.select(lane);
+        (abs, end) = Blocks.expectKey(cur.absolute(), key);
+        exec.decoders = cur.seekAbs(end);
+    }
+
     /// @notice Validate and consume one block from a decoder lane, returning its complete encoding.
     /// @param exec Execution whose selected decoder cursor is advanced past the block.
     /// @param lane Execution decoder lane to select.
@@ -256,7 +270,7 @@ library Executions {
         uint8 lane,
         bytes4 key
     ) internal pure returns (bytes calldata data) {
-        (uint abs, uint end) = consume(exec, lane, Specs.create(key, 0, 0, 0));
+        (uint abs, uint end) = consume(exec, lane, key);
         data = msg.data[abs - Sizes.Header:end];
     }
 
@@ -1403,13 +1417,20 @@ library Executions {
     // Value and transaction writing
     // -------------------------------------------------------------------------
 
+    /// @notice Remove and return the remaining execution value budget.
+    /// @param exec Execution whose budget is drained.
+    /// @return budget Native value removed from the execution.
+    function drainBudget(Execution memory exec) internal pure returns (uint budget) {
+        budget = exec.budget;
+        exec.budget = 0;
+    }
+
     /// @notice Transfer the remaining value budget out of an execution.
     /// @dev Clears `exec.budget` so the returned budget becomes its sole owner.
     /// @param exec Execution whose budget is detached.
     /// @return budget Detached budget containing the remaining value.
     function takeBudget(Execution memory exec) internal pure returns (Budget memory budget) {
-        budget.remaining = exec.budget;
-        exec.budget = 0;
+        budget.remaining = drainBudget(exec);
     }
 
     /// @notice Deduct an exact native value from the execution budget.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/ports/Pipe.sol

@@ -3,17 +3,16 @@ pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
 import {Flags} from "../codec/Descriptors.sol";
-import {Pipeline} from "../core/Pipeline.sol";
+import {PipeHook} from "../core/Pipeline.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
-import {Budget} from "../execution/Budget.sol";
 
 using Executions for Execution;
 
 /// @title PipePayablePort
 /// @notice Port that consumes CONTEXT blocks and executes each input as a step stream.
 /// Each context's input bytes are passed to the shared pipeline.
-abstract contract PipePayablePort is PortBase, Pipeline {
+abstract contract PipePayablePort is PortBase, PipeHook {
     uint private immutable descriptor;
 
     constructor() {
@@ -27,11 +26,11 @@ abstract contract PipePayablePort is PortBase, Pipeline {
     /// @return Empty response bytes.
     function portPipePayable(bytes calldata data) external payable onlyPeer returns (bytes memory) {
         Execution memory exec = openInput(data, descriptor, 0);
-        Budget memory budget = exec.takeBudget();
+        uint budget = exec.drainBudget();
 
         while (exec.more()) {
             (bytes32 account, bytes calldata state, bytes calldata input) = exec.unpackContext(Lanes.Input);
-            pipe(account, state, input, budget);
+            budget = pipe(account, state, input, budget);
         }
         
         return "";