@rootzero/contracts 1.26.0 → 1.28.0

package/commands/Settle.sol

@@ -7,6 +7,7 @@ import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
 import {Blocks, Memory} from "../codec/Blocks.sol";
 import {Sizes} from "../codec/Specs.sol";
+import {UnexpectedInput} from "../utils/Errors.sol";
 
 using Executions for Execution;
 
@@ -108,10 +109,10 @@ 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 Executions.ZeroStride();
+        if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
 
         (uint abs, uint end) = Memory.bounds(state, Sizes.Position);

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

@@ -89,6 +89,7 @@ abstract contract NodeAccess is AdminAccess, TrustAccess, NodeEvent {
     /// @param node Node ID to update.
     /// @param active True to authorize the node, false to revoke it.
     function setNode(uint node, bool active) internal {
+        node = Nodes.local(node);
         nodes[node] = active;
         emit Node(host, node, active);
     }
@@ -105,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} from "../utils/Errors.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,30 +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 {
-    /// @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
-    /// 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.
@@ -58,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/core/Settlement.sol

@@ -61,7 +61,8 @@ abstract contract Settlement is PostHook, SettleHook, RepayHook, DebitAccountHoo
     }
 
     /// @notice Settle one position by crediting its asset and debiting its liability.
-    /// Skips either operation when its corresponding amount is zero.
+    /// Skips either operation when its corresponding amount is zero, including
+    /// position sides encoded as absent with a zero identifier and quantity.
     function settle(
         bytes32 account,
         bytes32 asset,

package/core/Types.sol

@@ -76,6 +76,7 @@ struct Debt {
 }
 
 /// @notice Asset and liability pair threaded as live pipeline state.
+/// Either side may be absent by setting both its identifier and quantity to zero.
 struct Position {
     /// @dev Identifier for the asset side.
     bytes32 asset;

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

@@ -28,9 +28,6 @@ struct Execution {
 library Executions {
     using Cursors for uint;
 
-    /// @dev Command-defined lane policy rejected data in an expected-empty lane.
-    error ZeroStride();
-
     // -------------------------------------------------------------------------
     // Opening
     // -------------------------------------------------------------------------
@@ -621,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());
@@ -1032,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);
@@ -1167,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);
@@ -1250,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.26.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/Accounts.sol

@@ -34,6 +34,7 @@ library Accounts {
     }
 
     /// @notice Return true if `account` belongs to the EVM account family.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isEvm(bytes32 account) internal pure returns (bool) {
         return isFamily(uint(account), Family);
     }
@@ -44,20 +45,24 @@ library Accounts {
     }
 
     /// @notice Return true if `account` is an admin account.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isAdmin(bytes32 account) internal pure returns (bool) {
         return prefix(account) == Admin;
     }
 
     /// @notice Return true if `account` is a user account.
+    /// @dev Classification only; does not require a nonzero embedded address.
     function isUser(bytes32 account) internal pure returns (bool) {
         return prefix(account) == User;
     }
 
-    /// @notice Assert that `value` belongs to the EVM account family and return it unchanged.
+    /// @notice Assert that `value` belongs to the EVM account family, contains
+    /// a nonzero embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is an EVM account.
     function evm(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isEvm(value)) revert InvalidAccount();
+        if (!isFamily(uint(value), Family)) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
@@ -69,19 +74,23 @@ library Accounts {
         return value;
     }
 
-    /// @notice Assert that `value` is an admin account and return it unchanged.
+    /// @notice Assert that `value` is an admin account, contains a nonzero
+    /// embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is an admin account.
     function admin(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isAdmin(value)) revert InvalidAccount();
+        if (uint32(uint(value) >> 224) != Admin) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
-    /// @notice Assert that `value` is a user account and return it unchanged.
+    /// @notice Assert that `value` is a user account, contains a nonzero
+    /// embedded address, and return it unchanged.
     /// @param value Account identifier to validate.
     /// @return account The same `value` if it is a user account.
     function user(bytes32 value) internal pure returns (bytes32 account) {
-        if (!isUser(value)) revert InvalidAccount();
+        if (uint32(uint(value) >> 224) != User) revert InvalidAccount();
+        ensureAddr(address(uint160(uint(value) >> 32)));
         return value;
     }
 
@@ -120,6 +129,6 @@ library Accounts {
     /// @param account EVM-family account ID.
     /// @return Embedded address (bits [191:32] of the ID).
     function addr(bytes32 account) internal pure returns (address) {
-        return ensureAddr(address(uint160(uint(evm(account)) >> 32)));
+        return address(uint160(uint(evm(account)) >> 32));
     }
 }

package/utils/Errors.sol

@@ -7,6 +7,12 @@ error InsufficientValue();
 /// @dev Thrown when a decoder or execution is finalized with unread data.
 error UnconsumedData();
 
+/// @dev Thrown when an operation requires empty state but receives state data.
+error UnexpectedState();
+
+/// @dev Thrown when an operation requires empty input but receives input data.
+error UnexpectedInput();
+
 /// @dev Thrown when an ID does not match the expected convention or type.
 error InvalidId();
 

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.
 ///