@rootzero/contracts 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.28.0
+
+### Breaking Changes
+
+- Expanded STEP's native `value` field from `uint128` to `uint`, increasing an
+  empty STEP block from 64 to 80 bytes. Plain native values now use `uint`
+  throughout runtime APIs; packed `resources` remain separate `uint` words
+  whose EVM value lane is extracted explicitly with `useResourceValue`.
+- Replaced the `CommandCalls` abstraction and its allocating `encodeCommandCall`
+  and `callCommand` helpers with the free `rawCommandCall` function. The caller
+  now supplies the decoded selector and target after validating and authorizing
+  the command, then uses the single-scratch assembly call path.
+- Added the required `ExecuteHook` to `Pipeline` and removed its `dispatch` hook.
+  Steps whose command IDs target the current host use `execute`; other commands
+  are checked through `TrustAccess` and called directly with `rawCommandCall`.
+
+### Changed
+
+- Added the free `unpackCommand` utility for validating a command node and
+  extracting its selector and target in one operation. Pipeline steps now use
+  it to validate command IDs and select local execution by target address.
+- Simplified `NodeAccess.ensureTrusted` to a single mapping check; an unset zero
+  node already resolves to false like every other untrusted node.
+
 ## 1.27.0
 
 ### Breaking Changes

package/Core.sol

@@ -12,9 +12,9 @@ import { Balances, InsufficientFunds } from "./core/Balances.sol";
 import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 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 { FailedCall, NodeCalls, PortCalls, RawNodeCalls, rawCommandCall } from "./core/Calls.sol";
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
-import { PipeHook, Pipeline } from "./core/Pipeline.sol";
+import { ExecuteHook, 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,7 +6,7 @@ pragma solidity ^0.8.33;
 
 // Shared endpoint hooks
 import {Flags} from "./codec/Descriptors.sol";
-import {PipeHook} from "./core/Pipeline.sol";
+import {ExecuteHook, PipeHook} from "./core/Pipeline.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands

package/README.md

@@ -365,7 +365,7 @@ A single command is rarely the whole story. A pipeline is a run of `#step`
 blocks executed in order within one transaction:
 
 ```txt
-step { uint cmd, uint128 value, #bytes as input }
+step { uint cmd, uint value, #bytes as input }
 ```
 
 Each step names a command, the native value it may spend, and its input.
@@ -379,22 +379,22 @@ debits each asset through the standard account hook, introduces matching
 native asset through the same hook. Its pipeline-local implementation uses assigned step value first when
 bootstrapping the native asset, debits any remainder from the account, and
 returns unused assigned value as credit. Bootstrap is registered with command
-metadata but is only executable through local pipeline dispatch. This is the core of
+metadata but is only executable through local pipeline execution. This is the core of
 `Pipeline.pipe`:
 
 ```solidity
 while (cur.more()) {
-    (uint cmd, uint128 value, bytes calldata input) = cur.unpackStep();
+    (uint cmd, uint value, bytes calldata input) = cur.unpackStep();
+    (bytes4 selector, address target) = unpackCommand(cmd);
     if (budget < value) revert InsufficientValue();
     unchecked { budget -= value; }
     uint credit;
-    (state, credit) = dispatch(
-        cmd,
-        account,
-        state,
-        input,
-        value
-    );
+    if (target == address(this)) {
+        (state, credit) = execute(cmd, account, state, input, value);
+    } else {
+        ensureTrusted(cmd);
+        (state, credit) = rawCommandCall(selector, target, value, account, state, input);
+    }
     budget += credit;
 }
 if (state.length != 0) revert UnexpectedState();
@@ -407,9 +407,11 @@ settles that final value once.
 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
-command batching. A step's `uint128 value` is drawn directly from the shared
-native-value budget. Transport envelopes retain separate chain-specific
-`resources` fields for adapters that also need gas or runtime parameters.
+command batching. A step's plain `uint value` is drawn directly from the shared
+native-value budget. Transport envelopes retain separate opaque, packed
+chain-specific `resources` fields for adapters that also need gas or runtime
+parameters. A `resources` word is never itself native value; EVM adapters use
+`useResourceValue` to extract its low 128-bit value lane before spending it.
 
 Hosts that implement a pipeline locally can inherit `Bootstrap`,
 `CashoutInternal`, `DebitAccountInternal`, `CreditAccountInternal`,
@@ -509,11 +511,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`, `PipeHook`, `Pipeline`, `Portal`, validator
+  `Settlement`, `ExecuteHook`, `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 (including `PipeHook`), and `Flags`
+  mixins, their hooks (including `ExecuteHook` and `PipeHook`), and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
   `Memory`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
   `Specs`

package/Utils.sol

@@ -10,7 +10,7 @@ import { Actions } from "./utils/Actions.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
-import { Nodes } from "./utils/Nodes.sol";
+import { Nodes, unpackCommand } from "./utils/Nodes.sol";
 import { Layout } from "./utils/Layout.sol";
 import { BadAmount, InsufficientValue, InvalidAccount, InvalidAsset, InvalidContract, InvalidId, InvalidPreimage, MissingCursor, NotDivisible, OutOfBounds, UnauthorizedAsset, UnconsumedData, UnexpectedPosition, ValueOverflow, ZeroAddress, ZeroAmount} from "./utils/Errors.sol";
 import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, ensureContract, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase } from "./utils/Utils.sol";

package/codec/Blocks.sol

@@ -761,17 +761,17 @@ library Blocks {
     /// @param cmd Command identifier.
     /// @param value Native value assigned to the step.
     /// @param input Command input.
-    function writeStep(bytes memory dst, uint i, uint cmd, uint128 value, bytes memory input) internal pure {
-        uint len = 48 + Sizes.Header + input.length;
+    function writeStep(bytes memory dst, uint i, uint cmd, uint value, bytes memory input) internal pure {
+        uint len = 64 + Sizes.Header + input.length;
         uint key = uint32(Keys.Step);
         uint byteskey = uint32(Keys.Bytes);
         assembly ("memory-safe") {
             let p := add(add(dst, 0x20), i)
             mstore(p, or(shl(224, key), shl(192, len)))
             mstore(add(p, 0x08), cmd)
-            mstore(add(p, 0x28), shl(128, value))
+            mstore(add(p, 0x28), value)
 
-            let q := add(p, 0x38)
+            let q := add(p, 0x48)
             let inputlen := mload(input)
             mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
             mcopy(add(q, 0x08), add(input, 0x20), inputlen)
@@ -1031,17 +1031,17 @@ library Blocks {
     }
 
     /// @notice Encode a STEP block at `i`, copying its nested input from calldata.
-    function copyStep(bytes memory dst, uint i, uint cmd, uint128 value, bytes calldata input) internal pure {
-        uint len = max32(48 + Sizes.Header + input.length);
+    function copyStep(bytes memory dst, uint i, uint cmd, uint value, bytes calldata input) internal pure {
+        uint len = max32(64 + Sizes.Header + input.length);
         uint key = uint32(Keys.Step);
         uint byteskey = uint32(Keys.Bytes);
         assembly ("memory-safe") {
             let p := add(add(dst, 0x20), i)
             mstore(p, or(shl(224, key), shl(192, len)))
             mstore(add(p, 0x08), cmd)
-            mstore(add(p, 0x28), shl(128, value))
+            mstore(add(p, 0x28), value)
 
-            let q := add(p, 0x38)
+            let q := add(p, 0x48)
             let inputlen := input.length
             mstore(q, or(shl(224, byteskey), shl(192, inputlen)))
             calldatacopy(add(q, 0x08), input.offset, inputlen)
@@ -1836,14 +1836,14 @@ library Blocks {
     /// @return end Absolute position after the block.
     function unpackStep(
         uint abs
-    ) internal pure returns (uint cmd, uint128 value, bytes calldata input, uint end) {
+    ) internal pure returns (uint cmd, uint value, bytes calldata input, uint end) {
         uint limit;
         (abs, limit) = expectKey(abs, Keys.Step);
         assembly ("memory-safe") {
             cmd := calldataload(abs)
-            value := shr(128, calldataload(add(abs, 0x20)))
+            value := calldataload(add(abs, 0x20))
         }
-        (input, end) = unpackBytes(abs + 48);
+        (input, end) = unpackBytes(abs + 64);
         if (end != limit) revert InvalidBlock();
     }
 
@@ -2203,14 +2203,14 @@ library Blocks {
     /// @param value Native value assigned to the step.
     /// @param input Raw nested input payload.
     /// @return encoded Encoded STEP block bytes.
-    function createStep(uint cmd, uint128 value, bytes memory input) internal pure returns (bytes memory encoded) {
+    function createStep(uint cmd, uint value, bytes memory input) internal pure returns (bytes memory encoded) {
         uint len = max32(Sizes.Step + input.length);
         encoded = allocate(len);
         writeStep(encoded, 0, cmd, value, input);
     }
 
     /// @notice Encode a STEP block by copying its nested input from calldata.
-    function createStepCopy(uint cmd, uint128 value, bytes calldata input) internal pure returns (bytes memory encoded) {
+    function createStepCopy(uint cmd, uint value, bytes calldata input) internal pure returns (bytes memory encoded) {
         uint len = max32(Sizes.Step + input.length);
         encoded = allocate(len);
         copyStep(encoded, 0, cmd, value, input);

package/codec/Decoders.sol

@@ -740,7 +740,7 @@ library Decoders {
     /// @return input Decoded command input.
     function unpackStep(
         Cur memory cur
-    ) internal pure returns (uint cmd, uint128 value, bytes calldata input) {
+    ) internal pure returns (uint cmd, uint value, bytes calldata input) {
         uint abs = cur.state.absolute();
         uint end;
         (cmd, value, input, end) = Blocks.unpackStep(abs);

package/codec/Keys.sol

@@ -39,7 +39,7 @@ library Keys {
     bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, uint amount)
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
-    /// @dev Sub-command invocation - (uint cmd, uint128 value, #bytes as input)
+    /// @dev Sub-command invocation - (uint cmd, uint value, #bytes as input)
     bytes4 constant Step = bytes4(keccak256("#step"));
     /// @dev Portal relay input - (uint portal, uint resources, #bytes as input)
     bytes4 constant Relay = bytes4(keccak256("#relay"));

package/codec/Schema.sol

@@ -29,10 +29,11 @@ pragma solidity ^0.8.33;
 // - `portal` fields identify destination portal hosts. By convention the value
 //   is the portal implementation's host ID; core passes it through unchanged
 //   and hooks may validate or resolve it for their transport
-// - `resources` fields are chain-specific resource words. A portal adapter
-//   interprets them for the destination runtime. EVM resources use the low
-//   128 bits as native value.
-// - STEP encodes native `value` directly as uint128; it does not carry a
+// - `resources` fields are opaque chain-specific packed words, not native
+//   values. A portal adapter interprets them for the destination runtime. EVM
+//   resources use the low 128 bits as native value, extracted explicitly with
+//   `useResourceValue` before spending.
+// - STEP encodes native `value` directly as uint; it does not carry a
 //   chain-specific resources word
 // - dotted field names and aliases, e.g. `dst.portal` or `#bytes as dst.payload`,
 //   are offchain projection metadata only and do not change runtime encoding
@@ -116,7 +117,7 @@ library Schemas {
 
     // Composite payloads
 
-    string constant Step = "uint cmd, uint128 value, #bytes as input";
+    string constant Step = "uint cmd, uint value, #bytes as input";
     string constant Call = "uint target, uint resources, #bytes as payload";
     string constant Relay = "uint portal, uint resources, #bytes as input";
     string constant Dispatch = "uint portal, uint resources, #bytes as payload";

package/codec/Specs.sol

@@ -21,8 +21,8 @@ library Sizes {
     uint constant B128 = Header + 4 * Word;
     /// @dev 8 header + 160 payload = 168 bytes total.
     uint constant B160 = Header + 5 * Word;
-    /// @dev Minimum STEP size: 8 header + 32 command + 16 value + 8 nested BYTES header.
-    uint constant Step = 2 * Header + Word + 16;
+    /// @dev Minimum STEP size: 8 header + 32 command + 32 value + 8 nested BYTES header.
+    uint constant Step = 2 * Header + 2 * Word;
     /// @dev STATUS block: 8 header + 32 status code = 40 bytes
     uint constant Status = B32;
     /// @dev CASHOUT block: 8 header + 32 native-asset amount = 40 bytes
@@ -64,7 +64,6 @@ library Specs {
     uint private constant Exact128 = 128 * SizeFields;
     uint private constant UnboundedHint128 = uint(128) << 136;
     uint private constant UnboundedMin40Hint256 = (uint(40) << 192) | (uint(256) << 136);
-    uint private constant UnboundedMin56Hint256 = (uint(56) << 192) | (uint(256) << 136);
     uint private constant UnboundedMin72Hint256 = (uint(72) << 192) | (uint(256) << 136);
     uint private constant UnboundedMin48Hint512 = (uint(48) << 192) | (uint(512) << 136);
     uint private constant UnboundedMin104Hint256 = (uint(104) << 192) | (uint(256) << 136);
@@ -85,7 +84,7 @@ library Specs {
     uint constant String = uint(bytes32(Keys.String)) | UnboundedHint128;
     uint constant Account = uint(bytes32(Keys.Account)) | Exact32;
     uint constant Transaction = uint(bytes32(Keys.Transaction)) | Exact128;
-    uint constant Step = uint(bytes32(Keys.Step)) | UnboundedMin56Hint256;
+    uint constant Step = uint(bytes32(Keys.Step)) | UnboundedMin72Hint256;
     uint constant Relay = uint(bytes32(Keys.Relay)) | UnboundedMin72Hint256;
     uint constant Context = uint(bytes32(Keys.Context)) | UnboundedMin48Hint512;
     uint constant Recover = uint(bytes32(Keys.Recover)) | UnboundedMin104Hint256;

package/codec/Writers.sol

@@ -414,7 +414,7 @@ library Writers {
     /// @param cmd Command identifier to encode.
     /// @param value Native value to encode.
     /// @param input Command input to encode.
-    function appendStep(Writer memory writer, uint cmd, uint128 value, bytes memory input) internal pure {
+    function appendStep(Writer memory writer, uint cmd, uint value, bytes memory input) internal pure {
         uint size = Sizes.Step + input.length;
         uint i = reserve(writer, size);
         Blocks.writeStep(writer.dst, i, cmd, value, input);
@@ -561,7 +561,7 @@ library Writers {
     }
 
     /// @notice Append a STEP block by copying its nested input from calldata.
-    function copyStep(Writer memory writer, uint cmd, uint128 value, bytes calldata input) internal pure {
+    function copyStep(Writer memory writer, uint cmd, uint value, bytes calldata input) internal pure {
         uint size = Sizes.Step + input.length;
         uint i = reserve(writer, size);
         Blocks.copyStep(writer.dst, i, cmd, value, input);

package/commands/Bootstrap.sol

@@ -58,7 +58,7 @@ abstract contract Bootstrap is CommandBase, DebitAccountHook {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory output, uint credit) {
         if (state.length != 0) revert UnexpectedState();
         if (input.length % Sizes.Bootstrap != 0) revert Blocks.InvalidBlock();

package/commands/Cashout.sol

@@ -68,7 +68,7 @@ abstract contract CashoutInternal is Cashout {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert UnexpectedState();

package/commands/Credit.sol

@@ -59,7 +59,7 @@ abstract contract CreditAccountInternal is CreditAccount {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();

package/commands/Debit.sol

@@ -62,7 +62,7 @@ abstract contract DebitAccountInternal is DebitAccount {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert UnexpectedState();

package/commands/Recover.sol

@@ -9,7 +9,8 @@ using Executions for Execution;
 abstract contract RecoverPayableHook {
     /// @notice Override to recover a witness through `handler`.
     /// @param handler Port that should attempt recovery.
-    /// @param resources Chain-specific resources assigned to the recovery attempt.
+    /// @param resources Opaque packed chain-specific resources, not plain native
+    /// value. EVM handlers extract the low 128-bit value lane with `useResourceValue`.
     /// @param key Recovery lookup key.
     /// @param witness Witness payload used to prove and replay recovery.
     /// @param funds Shared execution containing the source value budget.

package/commands/Relay.sol

@@ -13,8 +13,9 @@ abstract contract RelayPayableHook {
     /// the source state is consumed before destination success is known.
     /// @param portal Destination portal implementation's host ID. Implementations
     /// may validate or resolve it for their transport.
-    /// @param resources Chain-specific destination resources. EVM adapters
-    /// may interpret this as packed execution gas and destination value.
+    /// @param resources Opaque packed chain-specific destination resources, not
+    /// plain native value. EVM adapters extract the low 128-bit value lane with
+    /// `useResourceValue`; higher bits may encode execution gas or other data.
     /// @param account Destination command account.
     /// @param state Complete state forwarded into the destination context.
     /// @param input Input forwarded into the destination context.

package/commands/Repay.sol

@@ -162,7 +162,7 @@ abstract contract RepayInternal is Repay {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();

package/commands/Settle.sol

@@ -109,7 +109,7 @@ abstract contract SettleInternal is Settle {
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
+        uint value
     ) internal returns (bytes memory, uint) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();

package/commands/admin/Execute.sol

@@ -8,7 +8,9 @@ using Executions for Execution;
 
 /// @title ExecutePayable
 /// @notice Admin command that forwards raw calldata to one or more target nodes.
-/// Each CALL block specifies a target node ID, packed resources, and raw calldata payload.
+/// Each CALL block specifies a target node ID, opaque packed resources, and raw
+/// calldata payload. Packed resources are converted to plain native value only
+/// through `useResourceValue`.
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` is returned as native budget credit.
 abstract contract ExecutePayable is RawNodeCalls, AdminBase {

package/core/Access.sol

@@ -106,9 +106,7 @@ abstract contract NodeAccess is AdminAccess, TrustAccess, NodeEvent {
     /// @param node Node ID to validate.
     /// @return The same `node` value if trusted.
     function ensureTrusted(uint node) internal view override returns (uint) {
-        if (node == 0 || !nodes[node]) {
-            revert AccessDenied();
-        }
+        if (!nodes[node]) revert AccessDenied();
         return node;
     }
 

package/core/Calls.sol

@@ -3,9 +3,6 @@ pragma solidity ^0.8.33;
 
 import {TrustAccess} from "./Access.sol";
 import {Nodes} from "../utils/Nodes.sol";
-import {Keys} from "../codec/Keys.sol";
-import {Sizes} from "../codec/Specs.sol";
-import {max32} from "../utils/Utils.sol";
 
 /// @dev Emitted when a trusted inter-node call fails.
 /// @param addr Contract address that was called.
@@ -13,6 +10,81 @@ import {max32} from "../utils/Utils.sol";
 /// @param err Revert data returned by the failed call.
 error FailedCall(address addr, bytes4 selector, bytes err);
 
+/// @notice Execute a raw `command(bytes)` call and decode its state and credit results.
+/// @dev The caller must validate and authorize the command before entering this helper.
+/// Uses one scratch region for both call data and return data. Successful return data
+/// must use the exact ABI layout of `(bytes, uint)`.
+function rawCommandCall(
+    bytes4 selector,
+    address target,
+    uint value,
+    bytes32 account,
+    bytes memory state,
+    bytes calldata input
+) returns (bytes memory output, uint credit) {
+    assembly ("memory-safe") {
+        let scratch := mload(0x40)
+        let statelen := mload(state)
+        let ctxlen := add(56, add(statelen, input.length))
+
+        // ABI envelope for command(bytes).
+        mstore(scratch, selector)
+        mstore(add(scratch, 0x04), 0x20)
+        mstore(add(scratch, 0x24), ctxlen)
+
+        // CONTEXT(account, BYTES(state), BYTES(input)).
+        let ctx := add(scratch, 0x44)
+        // 0xc5769e23 = bytes4(keccak256("#context"))
+        mstore(ctx, or(shl(224, 0xc5769e23), shl(192, sub(ctxlen, 8))))
+        // `ctxlen` is dead after the header and can carry the complete call length.
+        ctxlen := add(68, and(add(ctxlen, 0x1f), not(0x1f)))
+        mstore(add(ctx, 0x08), account)
+        let stateblk := add(ctx, 0x28)
+        // 0x6911b332 = bytes4(keccak256("#bytes"))
+        mstore(stateblk, or(shl(224, 0x6911b332), shl(192, statelen)))
+        mcopy(add(stateblk, 0x08), add(state, 0x20), statelen)
+        let inputblk := add(add(stateblk, 0x08), statelen)
+        let inputlen := input.length
+        mstore(inputblk, or(shl(224, 0x6911b332), shl(192, inputlen)))
+        calldatacopy(add(inputblk, 0x08), input.offset, inputlen)
+
+        // ABI word alignment also covers the input header's full-word write. Advance
+        // the free memory pointer once, after the return-data size is also known.
+        let inputend := and(add(add(scratch, ctxlen), 0x1f), not(0x1f))
+        let success := call(gas(), target, value, scratch, ctxlen, 0, 0)
+        let retlen := returndatasize()
+        if iszero(success) {
+            // FailedCall(target, selector, returndata)
+            // 0x20577b07 = FailedCall(address,bytes4,bytes)
+            mstore(scratch, shl(224, 0x20577b07))
+            mstore(add(scratch, 0x04), target)
+            mstore(add(scratch, 0x24), selector)
+            mstore(add(scratch, 0x44), 0x60)
+            mstore(add(scratch, 0x64), retlen)
+            mstore(add(add(scratch, 0x84), retlen), 0)
+            returndatacopy(add(scratch, 0x84), 0, retlen)
+            revert(scratch, add(0x84, and(add(retlen, 0x1f), not(0x1f))))
+        }
+
+        if lt(retlen, 0x60) { revert(0, 0) }
+        returndatacopy(scratch, 0, retlen)
+
+        // Strictly validate the exact ABI layout for (bytes, uint). The returned
+        // byte array can then point directly into the copied returndata.
+        if iszero(eq(mload(scratch), 0x40)) { revert(0, 0) }
+        let len1 := mload(add(scratch, 0x40))
+        if gt(len1, sub(retlen, 0x60)) { revert(0, 0) }
+        let pad1 := and(add(len1, 0x1f), not(0x1f))
+        if iszero(eq(retlen, add(0x60, pad1))) { revert(0, 0) }
+        output := add(scratch, 0x40)
+        credit := mload(add(scratch, 0x20))
+
+        let retend := and(add(add(scratch, retlen), 0x1f), not(0x1f))
+        if gt(retend, inputend) { inputend := retend }
+        mstore(0x40, inputend)
+    }
+}
+
 /// @title RawNodeCalls
 /// @notice Low-level inter-node call helpers without target authorization.
 abstract contract RawNodeCalls {
@@ -21,7 +93,7 @@ abstract contract RawNodeCalls {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return success True if the low-level call succeeded.
-    function tryRawCall(uint node, uint128 value, bytes memory data) internal returns (bool success) {
+    function tryRawCall(uint node, uint value, bytes memory data) internal returns (bool success) {
         address addr = Nodes.addr(node);
         (success, ) = payable(addr).call{value: value}(data);
     }
@@ -31,7 +103,7 @@ abstract contract RawNodeCalls {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return out Return data from the successful call.
-    function rawCall(uint node, uint128 value, bytes memory data) internal returns (bytes memory out) {
+    function rawCall(uint node, uint value, bytes memory data) internal returns (bytes memory out) {
         bool success;
         address addr = Nodes.addr(node);
         (success, out) = payable(addr).call{value: value}(data);
@@ -59,7 +131,7 @@ abstract contract NodeCalls is RawNodeCalls, TrustAccess {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return success True if the low-level call succeeded.
-    function tryTrustedCall(uint node, uint128 value, bytes memory data) internal returns (bool success) {
+    function tryTrustedCall(uint node, uint value, bytes memory data) internal returns (bool success) {
         return tryRawCall(ensureTrusted(node), value, data);
     }
 
@@ -68,7 +140,7 @@ abstract contract NodeCalls is RawNodeCalls, TrustAccess {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return out Return data from the successful call.
-    function trustedCall(uint node, uint128 value, bytes memory data) internal returns (bytes memory out) {
+    function trustedCall(uint node, uint value, bytes memory data) internal returns (bytes memory out) {
         return rawCall(ensureTrusted(node), value, data);
     }
 
@@ -81,74 +153,6 @@ abstract contract NodeCalls is RawNodeCalls, TrustAccess {
     }
 }
 
-/// @title CommandCalls
-/// @notice Trusted command-call helpers for contracts that route command nodes.
-abstract contract CommandCalls is NodeCalls {
-    /// @dev Build `command(bytes)` calldata and its nested CONTEXT block in one allocation.
-    /// Threaded state is copied from memory and step input directly from calldata.
-    function encodeCommandCall(
-        bytes4 selector,
-        bytes32 account,
-        bytes memory state,
-        bytes calldata input
-    ) internal pure returns (bytes memory data) {
-        uint contextLen = max32(Sizes.B32 + 2 * Sizes.Header + state.length + input.length);
-        uint paddedContextLen = (contextLen + 31) & ~uint(31);
-        uint dataLen = 4 + 64 + paddedContextLen;
-
-        // Reserve one scratch word because the final eight-byte block header is
-        // written with mstore. Exclude that word from the returned calldata.
-        data = new bytes(dataLen + 32);
-
-        uint contextKey = uint32(Keys.Context);
-        uint bytesKey = uint32(Keys.Bytes);
-        assembly ("memory-safe") {
-            mstore(data, dataLen)
-            let out := add(data, 0x20)
-
-            // ABI envelope for command(bytes).
-            mstore(out, selector)
-            mstore(add(out, 0x04), 0x20)
-            mstore(add(out, 0x24), contextLen)
-
-            // CONTEXT(account, BYTES(state), BYTES(input)).
-            let context := add(out, 0x44)
-            mstore(context, or(shl(224, contextKey), shl(192, sub(contextLen, 8))))
-            mstore(add(context, 0x08), account)
-
-            let stateBlock := add(context, 0x28)
-            let stateLen := mload(state)
-            mstore(stateBlock, or(shl(224, bytesKey), shl(192, stateLen)))
-            mcopy(add(stateBlock, 0x08), add(state, 0x20), stateLen)
-
-            let inputBlock := add(add(stateBlock, 0x08), stateLen)
-            let inputLen := input.length
-            mstore(inputBlock, or(shl(224, bytesKey), shl(192, inputLen)))
-            calldatacopy(add(inputBlock, 0x08), input.offset, inputLen)
-        }
-    }
-
-    /// @notice Encode and call a trusted command node.
-    /// @param command Command node ID embedding the target selector.
-    /// @param value Native value to forward in wei.
-    /// @param account Command account identifier.
-    /// @param state Current command state block stream.
-    /// @param input Command input block stream.
-    /// @return nextState Decoded command output state block stream.
-    /// @return credit Trusted native value to add to the caller's execution budget.
-    function callCommand(
-        uint command,
-        uint128 value,
-        bytes32 account,
-        bytes memory state,
-        bytes calldata input
-    ) internal returns (bytes memory nextState, uint credit) {
-        bytes4 selector = Nodes.commandSelector(command);
-        bytes memory data = encodeCommandCall(selector, account, state, input);
-        return abi.decode(trustedCall(command, value, data), (bytes, uint));
-    }
-}
-
 /// @title PortCalls
 /// @notice Trusted port-call helpers for contracts that route port nodes.
 abstract contract PortCalls is NodeCalls {
@@ -157,7 +161,7 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return success True if the low-level port call succeeded.
-    function tryCallPort(uint port, uint128 value, bytes memory input) internal returns (bool success) {
+    function tryCallPort(uint port, uint value, bytes memory input) internal returns (bool success) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return tryTrustedCall(port, value, data);
@@ -168,7 +172,7 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return success True if the low-level port call succeeded.
-    function tryCallPortCopy(uint port, uint128 value, bytes calldata input) internal returns (bool success) {
+    function tryCallPortCopy(uint port, uint value, bytes calldata input) internal returns (bool success) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return tryTrustedCall(port, value, data);
@@ -179,7 +183,7 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return Decoded port output block stream.
-    function callPort(uint port, uint128 value, bytes memory input) internal returns (bytes memory) {
+    function callPort(uint port, uint value, bytes memory input) internal returns (bytes memory) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return abi.decode(trustedCall(port, value, data), (bytes));
@@ -190,7 +194,7 @@ abstract contract PortCalls is NodeCalls {
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return Decoded port output block stream.
-    function callPortCopy(uint port, uint128 value, bytes calldata input) internal returns (bytes memory) {
+    function callPortCopy(uint port, uint value, bytes calldata input) internal returns (bytes memory) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return abi.decode(trustedCall(port, value, data), (bytes));

package/core/Pipeline.sol

@@ -2,8 +2,11 @@
 pragma solidity ^0.8.33;
 
 import {Blocks} from "../codec/Blocks.sol";
+import {TrustAccess} from "./Access.sol";
+import {rawCommandCall} from "./Calls.sol";
 import {Cursors} from "../utils/Cursors.sol";
 import {InsufficientValue, OutOfBounds, UnexpectedState} from "../utils/Errors.sol";
+import {unpackCommand} from "../utils/Nodes.sol";
 
 /// @notice Hook implemented by hosts that execute encoded step streams.
 abstract contract PipeHook {
@@ -16,27 +19,34 @@ abstract contract PipeHook {
     ) internal virtual returns (uint remaining);
 }
 
+/// @notice Hook implemented by pipeline hosts that execute host-local commands.
+abstract contract ExecuteHook {
+    /// @notice Execute one command whose node ID targets the current host.
+    /// @dev Implementations must revert for unsupported local command IDs.
+    function execute(
+        uint cmd,
+        bytes32 account,
+        bytes memory state,
+        bytes calldata input,
+        uint value
+    ) internal virtual returns (bytes memory output, uint credit);
+}
+
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is PipeHook {
-    /// @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
-    /// credit is added to the shared native-value budget 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.
-    /// @param input Step input block stream.
-    /// @param value Native EVM value assigned to this step.
-    /// @return output Updated state block stream for the next step.
-    /// @return credit Trusted native value to add to the pipeline budget.
-    function dispatch(
+abstract contract Pipeline is TrustAccess, PipeHook, ExecuteHook {
+    function run(
         uint cmd,
         bytes32 account,
         bytes memory state,
         bytes calldata input,
-        uint128 value
-    ) internal virtual returns (bytes memory output, uint credit);
+        uint value
+    ) private returns (bytes memory output, uint credit) {
+        (bytes4 selector, address target) = unpackCommand(cmd);
+        if (target == address(this)) return execute(cmd, account, state, input, value);
+        ensureTrusted(cmd);
+        return rawCommandCall(selector, target, value, account, state, input);
+    }
 
     /// @notice Execute a STEP block stream through the pipeline.
     /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
@@ -55,18 +65,15 @@ abstract contract Pipeline is PipeHook {
         (uint abs, uint end) = Cursors.bounds(steps);
 
         while (abs < end) {
-            uint cmd;
-            uint128 value;
-            bytes calldata input;
-            (cmd, value, input, abs) = Blocks.unpackStep(abs);
-            if (abs > end) revert OutOfBounds();
+            (uint cmd, uint value, bytes calldata input, uint next) = Blocks.unpackStep(abs);
+            if (next > end) revert OutOfBounds();
             if (value > budget) revert InsufficientValue();
             unchecked {
                 budget -= value;
             }
-            uint credit;
-            (state, credit) = dispatch(cmd, account, state, input, value);
-            budget += credit;
+            (state, value) = run(cmd, account, state, input, value);
+            budget += value;
+            abs = next;
         }
 
         if (state.length != 0) revert UnexpectedState();

package/core/Portal.sol

@@ -20,7 +20,7 @@ abstract contract Portal is PortCalls, NodeAccess, UnresolvedEvent, ResolvedEven
     /// @param message Encoded port input to forward.
     /// @param value Native EVM value assigned to the forwarding attempt.
     /// @return miss Message digest recorded for recovery when forwarding fails; zero on success.
-    function forward(uint port, bytes32 key, bytes calldata message, uint128 value) internal returns (bytes32 miss) {
+    function forward(uint port, bytes32 key, bytes calldata message, uint value) internal returns (bytes32 miss) {
         if (tryCallPortCopy(port, value, message)) return bytes32(0);
 
         miss = keccak256(message);
@@ -33,7 +33,7 @@ abstract contract Portal is PortCalls, NodeAccess, UnresolvedEvent, ResolvedEven
     /// @param key Recovery lookup key.
     /// @param witness Witness payload used to prove and replay recovery.
     /// @param value Native EVM value assigned to the resolution attempt.
-    function resolve(uint port, bytes32 key, bytes calldata witness, uint128 value) internal virtual {
+    function resolve(uint port, bytes32 key, bytes calldata witness, uint value) internal virtual {
         if (unresolved[key] != keccak256(witness)) revert BadWitness();
 
         delete unresolved[key];

package/execution/Budget.sol

@@ -38,15 +38,19 @@ library Budgets {
     }
 
     /// @notice Deduct the EVM value lane of `resources` from `budget`.
-    /// @dev EVM resources use the low 128 bits as native value/endowment.
+    /// @dev `resources` is not a native value. This helper explicitly extracts
+    /// its low 128-bit EVM value lane and widens that lane to a plain `uint`.
     /// @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 useResourceValue(Budget memory budget, uint resources) internal pure returns (uint128) {
-        return uint128(useValue(budget, uint128(resources)));
+    function useResourceValue(Budget memory budget, uint resources) internal pure returns (uint value) {
+        value = uint128(resources);
+        useValue(budget, value);
     }
 
     /// @notice Deduct the EVM value lane of `resources` from a scalar budget.
+    /// @dev `resources` is not a native value. This helper explicitly extracts
+    /// its low 128-bit EVM value lane and widens that lane to a plain `uint`.
     /// @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.
@@ -54,7 +58,7 @@ library Budgets {
     function useResourceValue(
         uint budget,
         uint resources
-    ) internal pure returns (uint remaining, uint128 value) {
+    ) internal pure returns (uint remaining, uint value) {
         value = uint128(resources);
         remaining = useValue(budget, value);
     }

package/execution/Execution.sol

@@ -618,7 +618,7 @@ library Executions {
     /// @return cmd Decoded command identifier.
     /// @return value Decoded native value.
     /// @return input Decoded nested input.
-    function unpackStep(Execution memory exec) internal pure returns (uint cmd, uint128 value, bytes calldata input) {
+    function unpackStep(Execution memory exec) internal pure returns (uint cmd, uint value, bytes calldata input) {
         uint cur = exec.decoders;
         uint end;
         (cmd, value, input, end) = Blocks.unpackStep(cur.absolute());
@@ -1029,7 +1029,7 @@ library Executions {
     /// @param cmd Command identifier to encode.
     /// @param value Native value to encode.
     /// @param input Command input to encode.
-    function outputStep(Execution memory exec, uint cmd, uint128 value, bytes memory input) internal pure {
+    function outputStep(Execution memory exec, uint cmd, uint value, bytes memory input) internal pure {
         uint size = Sizes.Step + input.length;
         uint i = reserve(exec, size);
         Blocks.writeStep(exec.output, i, cmd, value, input);
@@ -1164,7 +1164,7 @@ library Executions {
     }
 
     /// @notice Append a STEP block to execution output by copying its nested input from calldata.
-    function outputCopyStep(Execution memory exec, uint cmd, uint128 value, bytes calldata input) internal pure {
+    function outputCopyStep(Execution memory exec, uint cmd, uint value, bytes calldata input) internal pure {
         uint size = Sizes.Step + input.length;
         uint i = reserve(exec, size);
         Blocks.copyStep(exec.output, i, cmd, value, input);
@@ -1247,12 +1247,14 @@ library Executions {
     }
 
     /// @notice Deduct the EVM value lane of `resources` from the execution budget.
-    /// @dev EVM resources use the low 128 bits as native value/endowment.
+    /// @dev `resources` is not a native value. This helper explicitly extracts
+    /// its low 128-bit EVM value lane and widens that lane to a plain `uint`.
     /// @param exec Mutable execution whose budget is charged.
     /// @param resources Packed resources whose value lane should be spent.
     /// @return value Native value to forward in wei.
-    function useResourceValue(Execution memory exec, uint resources) internal pure returns (uint128) {
-        return uint128(useValue(exec, uint128(resources)));
+    function useResourceValue(Execution memory exec, uint resources) internal pure returns (uint value) {
+        value = uint128(resources);
+        useValue(exec, value);
     }
 
     // -------------------------------------------------------------------------

package/package.json

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

package/ports/Dispatch.sol

@@ -13,8 +13,9 @@ abstract contract DispatchPayableHook {
     /// @notice Override to dispatch an encoded payload to `portal`.
     /// @param portal Destination portal implementation's host ID. Implementations
     /// may validate or resolve it for their transport.
-    /// @param resources Chain-specific destination resources. EVM adapters
-    /// may interpret this as packed execution gas and destination value.
+    /// @param resources Opaque packed chain-specific destination resources, not
+    /// plain native value. EVM adapters extract the low 128-bit value lane with
+    /// `useResourceValue`; higher bits may encode execution gas or other data.
     /// @param payload Encoded payload ready for the transport layer.
     /// @param funds Execution used for source value available for transport fees
     /// and destination resource funding.

package/utils/Nodes.sol

@@ -6,6 +6,21 @@ import {InvalidId} from "./Errors.sol";
 import {Ids} from "./Ids.sol";
 import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
 
+/// @notice Validate and unpack a command node into its ABI selector and target address.
+/// @dev Validates only the command type prefix; chain locality and authorization are caller concerns.
+/// @param cmd Command node ID to unpack.
+/// @return selector ABI selector stored in bits [191:160].
+/// @return target Contract address stored in bits [159:0].
+function unpackCommand(uint cmd) pure returns (bytes4 selector, address target) {
+    uint32 command = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
+    if (uint32(cmd >> 224) != command) revert InvalidId();
+
+    assembly ("memory-safe") {
+        selector := shl(224, and(shr(160, cmd), 0xffffffff))
+        target := and(cmd, 0xffffffffffffffffffffffffffffffffffffffff)
+    }
+}
+
 /// @title Nodes
 /// @notice Encoding and decoding helpers for 256-bit node identifiers.
 ///