@rootzero/contracts 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Until the protocol reaches integration-stable status, minor versions may include
+breaking API changes. Breaking changes are called out explicitly.
+
+## 1.1.0
+
+### Breaking Changes
+
+- Renamed local execution fields from `value` to `resources` in PIPE, CALL, and STEP schemas.
+- Interprets EVM value as the low 128 bits of packed `resources`.
+- Changed native value APIs and dispatch hooks to use `uint128` for actual EVM value.
+- Replaced the relay-specific hook with shared `DispatchPayableHook`.
+- `RelayPayable` now dispatches an encoded PIPE payload and settles leftover user command value.

package/Endpoints.sol

@@ -16,7 +16,7 @@ import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
-import { RelayPayable, RelayPayableHook } from "./commands/Relay.sol";
+import { RelayPayable, DispatchPayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands

package/blocks/Cursors.sol

@@ -518,20 +518,20 @@ library Cursors {
 
     /// @notice Encode a STEP block.
     /// @param target Command target identifier.
-    /// @param value Native value forwarded with the step.
+    /// @param resources Chain resources assigned to the step.
     /// @param request Raw nested request payload.
     /// @return Encoded STEP block bytes.
-    function toStepBlock(uint target, uint value, bytes memory request) internal pure returns (bytes memory) {
-        return createBlock(Keys.Step, bytes.concat(bytes32(target), bytes32(value), toBytesBlock(request)));
+    function toStepBlock(uint target, uint resources, bytes memory request) internal pure returns (bytes memory) {
+        return createBlock(Keys.Step, bytes.concat(bytes32(target), bytes32(resources), toBytesBlock(request)));
     }
 
     /// @notice Encode a CALL block.
     /// @param target Target node identifier.
-    /// @param value Native value forwarded with the call.
+    /// @param resources Chain resources assigned to the call.
     /// @param data Raw calldata payload for the target.
     /// @return Encoded CALL block bytes.
-    function toCallBlock(uint target, uint value, bytes memory data) internal pure returns (bytes memory) {
-        return createBlock(Keys.Call, bytes.concat(bytes32(target), bytes32(value), toBytesBlock(data)));
+    function toCallBlock(uint target, uint resources, bytes memory data) internal pure returns (bytes memory) {
+        return createBlock(Keys.Call, bytes.concat(bytes32(target), bytes32(resources), toBytesBlock(data)));
     }
 
     /// @notice Encode a CONTEXT block.
@@ -548,37 +548,37 @@ library Cursors {
     }
 
     /// @notice Encode a PIPE block.
-    /// @param value Native value assigned to the pipe.
+    /// @param resources Chain resources assigned to the pipe.
     /// @param account Command account identifier.
     /// @param state Embedded state block stream.
     /// @param steps Embedded step block stream.
     /// @return Encoded PIPE block bytes.
     function toPipeBlock(
-        uint value,
+        uint resources,
         bytes32 account,
         bytes memory state,
         bytes memory steps
     ) internal pure returns (bytes memory) {
-        return createBlock(Keys.Pipe, bytes.concat(bytes32(value), toContextBlock(account, state, steps)));
-    }
-
-    /// @notice Encode a RELAY block.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific resources for the destination pipe.
-    /// @param steps Nested step block stream.
-    /// @return Encoded RELAY block bytes.
-    function toRelayBlock(uint chain, uint resources, bytes memory steps) internal pure returns (bytes memory) {
-        return createBlock(Keys.Relay, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(steps)));
-    }
-
-    /// @notice Encode a DISPATCH block.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific resources for the destination dispatch.
-    /// @param payload Encoded cross-chain payload.
-    /// @return Encoded DISPATCH block bytes.
-    function toDispatchBlock(uint chain, uint resources, bytes memory payload) internal pure returns (bytes memory) {
-        return createBlock(Keys.Dispatch, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(payload)));
-    }
+        return createBlock(Keys.Pipe, bytes.concat(bytes32(resources), toContextBlock(account, state, steps)));
+    }
+
+    /// @notice Encode a RELAY block.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific resources for the destination pipe.
+    /// @param steps Nested step block stream.
+    /// @return Encoded RELAY block bytes.
+    function toRelayBlock(uint chain, uint resources, bytes memory steps) internal pure returns (bytes memory) {
+        return createBlock(Keys.Relay, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(steps)));
+    }
+
+    /// @notice Encode a DISPATCH block.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific resources for the destination dispatch.
+    /// @param payload Encoded cross-chain payload.
+    /// @return Encoded DISPATCH block bytes.
+    function toDispatchBlock(uint chain, uint resources, bytes memory payload) internal pure returns (bytes memory) {
+        return createBlock(Keys.Dispatch, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(payload)));
+    }
 
     // -------------------------------------------------------------------------
     // Raw calldata loaders
@@ -590,31 +590,31 @@ library Cursors {
     /// @param cur Cursor whose current position is advanced by `n` bytes.
     /// @param n Number of bytes to advance.
     /// @return value Loaded word.
-    function read(Cur memory cur, uint n) internal pure returns (bytes32 value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += n;
-    }
-
-    /// @notice Read the next 4 bytes from the cursor and advance by 4 bytes.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 4 bytes.
-    /// @return value Loaded bytes4 value.
-    function read4(Cur memory cur) internal pure returns (bytes4 value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += 4;
-    }
-
-    /// @notice Read the next 16 bytes from the cursor and advance by 16 bytes.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 16 bytes.
-    /// @return value Loaded bytes16 value.
-    function read16(Cur memory cur) internal pure returns (bytes16 value) {
+    function read(Cur memory cur, uint n) internal pure returns (bytes32 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += n;
+    }
+
+    /// @notice Read the next 4 bytes from the cursor and advance by 4 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 4 bytes.
+    /// @return value Loaded bytes4 value.
+    function read4(Cur memory cur) internal pure returns (bytes4 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 4;
+    }
+
+    /// @notice Read the next 16 bytes from the cursor and advance by 16 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 16 bytes.
+    /// @return value Loaded bytes16 value.
+    function read16(Cur memory cur) internal pure returns (bytes16 value) {
         uint abs = cur.offset + cur.i;
         assembly ("memory-safe") {
             value := calldataload(abs)
@@ -626,30 +626,30 @@ library Cursors {
     /// @dev Performs no bounds, key, length, or cursor checks.
     /// @param cur Cursor whose current position is advanced by 32 bytes.
     /// @return value Loaded word.
-    function read32(Cur memory cur) internal pure returns (bytes32 value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += 32;
-    }
-
-    /// @notice Read the next uint from the cursor and advance by one word.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 32 bytes.
-    /// @return value Loaded uint value.
-    function readUint(Cur memory cur) internal pure returns (uint value) {
-        uint abs = cur.offset + cur.i;
-        assembly ("memory-safe") {
-            value := calldataload(abs)
-        }
-        cur.i += 32;
-    }
-
-    /// @notice Read the next two 32-byte words from the cursor and advance by 64 bytes.
-    /// @dev Performs no bounds, key, length, or cursor checks.
-    /// @param cur Cursor whose current position is advanced by 64 bytes.
-    /// @return a First loaded word.
+    function read32(Cur memory cur) internal pure returns (bytes32 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 32;
+    }
+
+    /// @notice Read the next uint from the cursor and advance by one word.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 32 bytes.
+    /// @return value Loaded uint value.
+    function readUint(Cur memory cur) internal pure returns (uint value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 32;
+    }
+
+    /// @notice Read the next two 32-byte words from the cursor and advance by 64 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 64 bytes.
+    /// @return a First loaded word.
     /// @return b Second loaded word.
     function read64(Cur memory cur) internal pure returns (bytes32 a, bytes32 b) {
         uint abs = cur.offset + cur.i;
@@ -1079,12 +1079,12 @@ library Cursors {
     /// The `req` slice is the raw payload of the block's required BYTES child.
     /// @param cur Cursor; advanced past the block.
     /// @return target Destination node ID for the sub-command.
-    /// @return value Native value to forward with the call.
+    /// @return resources Chain resources assigned to the step.
     /// @return req Embedded request bytes for the sub-command.
-    function unpackStep(Cur memory cur) internal pure returns (uint target, uint value, bytes calldata req) {
+    function unpackStep(Cur memory cur) internal pure returns (uint target, uint resources, bytes calldata req) {
         uint end = cur.enter(Keys.Step, 64 + Sizes.Header, 0);
         target = uint(cur.read32());
-        value = uint(cur.read32());
+        resources = uint(cur.read32());
         req = cur.unpackBytes();
         cur.exit(end);
     }
@@ -1093,12 +1093,12 @@ library Cursors {
     /// The `data` slice is the raw payload of the block's required BYTES child.
     /// @param cur Cursor; advanced past the block.
     /// @return target Target node ID to call.
-    /// @return value Native value to forward with the call.
+    /// @return resources Chain resources assigned to the call.
     /// @return data Raw calldata payload for the target.
-    function unpackCall(Cur memory cur) internal pure returns (uint target, uint value, bytes calldata data) {
+    function unpackCall(Cur memory cur) internal pure returns (uint target, uint resources, bytes calldata data) {
         uint end = cur.enter(Keys.Call, 64 + Sizes.Header, 0);
         target = uint(cur.read32());
-        value = uint(cur.read32());
+        resources = uint(cur.read32());
         data = cur.unpackBytes();
         cur.exit(end);
     }
@@ -1119,50 +1119,50 @@ library Cursors {
         cur.exit(end);
     }
 
-    /// @notice Consume a PIPE block and return its value and context fields.
+    /// @notice Consume a PIPE block and return its resources and context fields.
     /// @param cur Cursor; advanced past the block.
-    /// @return value Native value assigned to the pipe.
+    /// @return resources Chain resources assigned to the pipe.
     /// @return account Command account identifier.
     /// @return state Embedded state block stream.
     /// @return steps Embedded step block stream.
     function unpackPipe(
         Cur memory cur
-    ) internal pure returns (uint value, bytes32 account, bytes calldata state, bytes calldata steps) {
+    ) internal pure returns (uint resources, bytes32 account, bytes calldata state, bytes calldata steps) {
         uint end = cur.enter(Keys.Pipe, 32 + Sizes.Header + 32 + 2 * Sizes.Header, 0);
-        value = uint(cur.read32());
+        resources = uint(cur.read32());
         (account, state, steps) = cur.unpackContext();
         cur.exit(end);
     }
 
-    /// @notice Consume a RELAY block and return its destination chain, resources, and step stream.
-    /// @param cur Cursor; advanced past the block.
-    /// @return chain Destination chain node ID.
-    /// @return resources Chain-adapter-specific resources for the destination pipe.
-    /// @return steps Embedded step block stream.
-    function unpackRelay(
-        Cur memory cur
-    ) internal pure returns (uint chain, uint resources, bytes calldata steps) {
-        uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
-        chain = cur.readUint();
-        resources = cur.readUint();
-        steps = cur.unpackBytes();
-        cur.exit(end);
-    }
-
-    /// @notice Consume a DISPATCH block and return its destination chain, resources, and payload.
-    /// @param cur Cursor; advanced past the block.
-    /// @return chain Destination chain node ID.
-    /// @return resources Chain-adapter-specific resources for the destination dispatch.
-    /// @return payload Encoded cross-chain payload.
-    function unpackDispatch(
-        Cur memory cur
-    ) internal pure returns (uint chain, uint resources, bytes calldata payload) {
-        uint end = cur.enter(Keys.Dispatch, 64 + Sizes.Header, 0);
-        chain = cur.readUint();
-        resources = cur.readUint();
-        payload = cur.unpackBytes();
-        cur.exit(end);
-    }
+    /// @notice Consume a RELAY block and return its destination chain, resources, and step stream.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return resources Chain-adapter-specific resources for the destination pipe.
+    /// @return steps Embedded step block stream.
+    function unpackRelay(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint resources, bytes calldata steps) {
+        uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
+        chain = cur.readUint();
+        resources = cur.readUint();
+        steps = cur.unpackBytes();
+        cur.exit(end);
+    }
+
+    /// @notice Consume a DISPATCH block and return its destination chain, resources, and payload.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return resources Chain-adapter-specific resources for the destination dispatch.
+    /// @return payload Encoded cross-chain payload.
+    function unpackDispatch(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint resources, bytes calldata payload) {
+        uint end = cur.enter(Keys.Dispatch, 64 + Sizes.Header, 0);
+        chain = cur.readUint();
+        resources = cur.readUint();
+        payload = cur.unpackBytes();
+        cur.exit(end);
+    }
 
     // Type-specific validators
 
@@ -1385,6 +1385,27 @@ library Cursors {
         if (uint(bytes32(msg.data[abs + 128:abs + 160])) < amount) revert UnexpectedValue();
     }
 
+    // -------------------------------------------------------------------------
+    // Transform helpers
+    // -------------------------------------------------------------------------
+
+    /// @notice Consume a RELAY block and encode its destination pipe payload.
+    /// @param cur Cursor; advanced past the RELAY block.
+    /// @param account Account identifier to embed in the destination pipe context.
+    /// @param state State block stream to embed in the destination pipe context.
+    /// @return chain Destination chain node ID.
+    /// @return resources Chain resources assigned to the destination pipe.
+    /// @return pipe Encoded PIPE block containing `account`, `state`, and relay steps.
+    function relayToPipe(
+        Cur memory cur,
+        bytes32 account,
+        bytes calldata state
+    ) internal pure returns (uint chain, uint resources, bytes memory pipe) {
+        bytes calldata steps;
+        (chain, resources, steps) = cur.unpackRelay();
+        pipe = toPipeBlock(resources, account, bytes(state), bytes(steps));
+    }
+
     // -------------------------------------------------------------------------
     // Search helpers
     // -------------------------------------------------------------------------

package/blocks/Keys.sol

@@ -37,17 +37,17 @@ library Keys {
     bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
-    /// @dev Sub-command invocation - (uint target, uint value, #bytes as request)
+    /// @dev Sub-command invocation - (uint target, uint resources, #bytes as request)
     bytes4 constant Step = bytes4(keccak256("#step"));
-    /// @dev Cross-chain pipe relay - (uint chain, uint resources, #bytes as steps)
-    bytes4 constant Relay = bytes4(keccak256("#relay"));
-    /// @dev Cross-chain encoded payload dispatch - (uint chain, uint resources, #bytes as payload)
-    bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
-    /// @dev Raw external call - (uint target, uint value, #bytes as payload)
+    /// @dev Cross-chain pipe relay - (uint chain, uint resources, #bytes as steps)
+    bytes4 constant Relay = bytes4(keccak256("#relay"));
+    /// @dev Cross-chain encoded payload dispatch - (uint chain, uint resources, #bytes as payload)
+    bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
+    /// @dev Raw external call - (uint target, uint resources, #bytes as payload)
     bytes4 constant Call = bytes4(keccak256("#call"));
     /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)
     bytes4 constant Context = bytes4(keccak256("#context"));
-    /// @dev Pipeline invocation - (uint value, #context)
+    /// @dev Pipeline invocation - (uint resources, #context)
     bytes4 constant Pipe = bytes4(keccak256("#pipe"));
     /// @dev Authentication proof - (uint cid, uint deadline, #bytes as proof); must appear last in its segment
     bytes4 constant Auth = bytes4(keccak256("#auth"));

package/blocks/Schema.sol

@@ -18,6 +18,9 @@ pragma solidity ^0.8.33;
 // - run items may repeat at top level for batching
 // - `maybe #x { ... }` marks an optional block item
 // - `many #x { ... }` emits one generic list block containing repeated `#x` items
+// - `resources` fields are chain-specific resource words; one chain type may
+//   pack them differently from another, but a given chain type must use one
+//   stable format everywhere. EVM resources use the low 128 bits as native value.
 // - fixed fields are packed in declaration order
 // - blocks have fixed fields followed by a dynamic child-block tail
 // - child block tails are embedded directly, without an extra stream wrapper
@@ -62,11 +65,11 @@ library Schemas {
     string constant Allowance = "#allowance { uint host, bytes32 asset, bytes32 meta, uint amount }";
     string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount }";
     string constant Context = "#context { bytes32 account, #bytes as state, #bytes as request }";
-    string constant Pipe = "#pipe { uint value, #context { bytes32 account, #bytes as state, #bytes as steps } }";
-    string constant Call = "#call { uint target, uint value, #bytes as payload }";
-    string constant Step = "#step { uint target, uint value, #bytes as request }";
-    string constant Relay = "#relay { uint chain, uint resources, #bytes as steps }";
-    string constant Dispatch = "#dispatch { uint chain, uint resources, #bytes as payload }";
+    string constant Pipe = "#pipe { uint resources, #context { bytes32 account, #bytes as state, #bytes as steps } }";
+    string constant Call = "#call { uint target, uint resources, #bytes as payload }";
+    string constant Step = "#step { uint target, uint resources, #bytes as request }";
+    string constant Relay = "#relay { uint chain, uint resources, #bytes as steps }";
+    string constant Dispatch = "#dispatch { uint chain, uint resources, #bytes as payload }";
     string constant Bounty = "#bounty { uint amount, bytes32 relayer }";
     string constant Fee = "#fee { uint amount }";
     string constant Auth = "#auth { uint cid, uint deadline, #bytes as proof }";

package/blocks/Writers.sol

@@ -865,19 +865,19 @@ library Writers {
     /// @notice Append a STEP block with a nested request BYTES payload.
     /// @param writer Destination writer; `i` is advanced by the encoded STEP block length.
     /// @param target Command target identifier.
-    /// @param value Native value forwarded with the step.
+    /// @param resources Chain resources assigned to the step.
     /// @param request Raw nested request payload.
-    function appendStep(Writer memory writer, uint target, uint value, bytes memory request) internal pure {
-        appendBlock64Bytes(writer, Keys.Step, bytes32(target), bytes32(value), request);
+    function appendStep(Writer memory writer, uint target, uint resources, bytes memory request) internal pure {
+        appendBlock64Bytes(writer, Keys.Step, bytes32(target), bytes32(resources), request);
     }
 
     /// @notice Append a CALL block with a nested payload BYTES block.
     /// @param writer Destination writer; `i` is advanced by the encoded CALL block length.
     /// @param target Call target identifier.
-    /// @param value Native value forwarded with the call.
+    /// @param resources Chain resources assigned to the call.
     /// @param data Raw nested call payload.
-    function appendCall(Writer memory writer, uint target, uint value, bytes memory data) internal pure {
-        appendBlock64Bytes(writer, Keys.Call, bytes32(target), bytes32(value), data);
+    function appendCall(Writer memory writer, uint target, uint resources, bytes memory data) internal pure {
+        appendBlock64Bytes(writer, Keys.Call, bytes32(target), bytes32(resources), data);
     }
 
     /// @notice Append a CONTEXT block with nested state/request BYTES payloads.
@@ -891,13 +891,13 @@ library Writers {
 
     /// @notice Append a PIPE block with a nested CONTEXT block.
     /// @param writer Destination writer; `i` is advanced by the encoded PIPE block length.
-    /// @param value Native value assigned to the pipe.
+    /// @param resources Chain resources assigned to the pipe.
     /// @param account Command account identifier.
     /// @param state Raw nested state payload.
     /// @param steps Raw nested step payload.
     function appendPipe(
         Writer memory writer,
-        uint value,
+        uint resources,
         bytes32 account,
         bytes memory state,
         bytes memory steps
@@ -909,7 +909,7 @@ library Writers {
 
         uint p = writeHeader(writer.dst, i, Keys.Pipe, uint32(max32(len)));
         assembly ("memory-safe") {
-            mstore(add(p, 0x08), value)
+            mstore(add(p, 0x08), resources)
         }
 
         writeBlock32BytesBytes(writer.dst, i + Sizes.Header + 32, Keys.Context, account, state, steps);

package/commands/Relay.sol

@@ -8,24 +8,15 @@ import {Budget} from "../utils/Value.sol";
 
 using Cursors for Cur;
 
-abstract contract RelayPayableHook {
-    /// @notice Override to relay `steps` to `chain` with the current account and state.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific destination resources. EVM adapters
-    /// may interpret this as packed execution gas and destination value.
-    /// @param account Command account identifier.
-    /// @param state Current command state block stream.
-    /// @param steps Embedded destination step block stream.
-    /// @param budget Source-chain native-value budget available for transport
-    /// fees and destination resource funding.
-    function relay(
-        uint chain,
-        uint resources,
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata steps,
-        Budget memory budget
-    ) internal virtual;
+abstract contract DispatchPayableHook {
+    /// @notice Override to dispatch an encoded payload to `chain`.
+    /// @param chain Destination chain node ID.
+    /// @param resources Chain-adapter-specific destination resources. EVM adapters
+    /// may interpret this as packed execution gas and destination value.
+    /// @param payload Encoded payload ready for the transport layer.
+    /// @param budget Source-chain native-value budget available for transport
+    /// fees and destination resource funding.
+    function dispatch(uint chain, uint resources, bytes memory payload, Budget memory budget) internal virtual;
 }
 
 /// @title RelayPayable
@@ -33,7 +24,7 @@ abstract contract RelayPayableHook {
 /// Reverts unless the request contains exactly one RELAY block, preventing
 /// the same state from being duplicated across multiple relays.
 /// Produces no output state.
-abstract contract RelayPayable is CommandBase, Payable, RelayPayableHook {
+abstract contract RelayPayable is CommandBase, Payable, DispatchPayableHook {
     string private constant NAME = "relayPayable";
 
     uint internal immutable relayPayableId = commandId(NAME);
@@ -46,12 +37,14 @@ abstract contract RelayPayable is CommandBase, Payable, RelayPayableHook {
     /// @param c Command context; `c.request` must contain exactly one RELAY block.
     /// @return output Empty output state.
     function relayPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory output) {
-        (Cur memory request, ) = Cursors.init(c.request, 0, 1, 1);
-        Budget memory budget = valueBudget();
-
-        (uint chain, uint resources, bytes calldata steps) = request.unpackRelay();
-        relay(chain, resources, c.account, c.state, steps, budget);
-        request.complete();
-        return "";
-    }
-}
+        (Cur memory request, ) = Cursors.init(c.request, 0, 1, 1);
+        Budget memory budget = valueBudget();
+
+        (uint chain, uint resources, bytes memory pipe) = request.relayToPipe(c.account, c.state);
+        dispatch(chain, resources, pipe, budget);
+        
+        settleValue(c.account, budget);
+        request.complete();
+        return "";
+    }
+}

package/commands/admin/Execute.sol

@@ -12,7 +12,7 @@ using Cursors for Cur;
 
 /// @title ExecutePayable
 /// @notice Admin command that forwards raw calldata to one or more target nodes.
-/// Each CALL block specifies a target node ID, native value, and raw calldata payload.
+/// Each CALL block specifies a target node ID, chain resources, and raw calldata payload.
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` remains on this host.
 abstract contract ExecutePayable is CommandBase, Payable, AdminEvent {
@@ -32,9 +32,9 @@ abstract contract ExecutePayable is CommandBase, Payable, AdminEvent {
         Budget memory budget = valueBudget();
 
         while (request.i < request.len) {
-            (uint target, uint value, bytes calldata data) = request.unpackCall();
+            (uint target, uint resources, bytes calldata data) = request.unpackCall();
             address addr = Ids.nodeAddr(target);
-            callAddr(addr, useValue(budget, value), data);
+            callAddr(addr, useValue(budget, resources), data);
         }
 
         request.complete();

package/core/Calls.sol

@@ -28,7 +28,7 @@ abstract contract NodeCalls is AccessControl {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return out Return data from the successful call.
-    function callAddr(address addr, uint value, bytes memory data) internal returns (bytes memory out) {
+    function callAddr(address addr, uint128 value, bytes memory data) internal returns (bytes memory out) {
         bool success;
         (success, out) = payable(addr).call{value: value}(data);
         if (!success) revert FailedCall(addr, bytes4(data), out);
@@ -53,7 +53,7 @@ abstract contract NodeCalls is AccessControl {
     /// @param value Native value to forward in wei.
     /// @param data Encoded calldata to send.
     /// @return out Return data from the successful call.
-    function callTo(uint node, uint value, bytes memory data) internal returns (bytes memory out) {
+    function callTo(uint node, uint128 value, bytes memory data) internal returns (bytes memory out) {
         ensureTrusted(node);
         address addr = Ids.nodeAddr(node);
         return callAddr(addr, value, data);
@@ -76,7 +76,7 @@ abstract contract NodeCalls is AccessControl {
     /// @param value Native value to forward in wei.
     /// @param ctx Command execution context.
     /// @return Decoded command output block stream.
-    function callCommand(uint id, uint value, CommandContext memory ctx) internal returns (bytes memory) {
+    function callCommand(uint id, uint128 value, CommandContext memory ctx) internal returns (bytes memory) {
         bytes4 selector = Ids.commandSelector(id);
         bytes memory data = abi.encodeWithSelector(selector, ctx);
         return abi.decode(callTo(id, value, data), (bytes));

package/core/Payable.sol

@@ -18,20 +18,22 @@ abstract contract Payable {
         return Budget({remaining: msg.value});
     }
 
-    /// @notice Deduct `amount` from the budget and return it.
+    /// @notice Deduct the EVM value lane from a packed resource word and return it.
+    /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param budget Mutable budget to deduct from.
-    /// @param amount Native value to spend.
-    /// @return The same `amount`, ready to forward to a callee.
-    function useValue(Budget memory budget, uint amount) internal pure returns (uint) {
-        return Values.use(budget, amount);
+    /// @param resources Packed chain resources.
+    /// @return value Native value to forward in wei.
+    function useValue(Budget memory budget, uint resources) internal pure returns (uint128 value) {
+        return Values.use(budget, uint128(resources));
     }
 
-    /// @notice Deduct `amount` from the budget and return it as a new sub-budget.
+    /// @notice Deduct the EVM value lane from a packed resource word as a new sub-budget.
+    /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param budget Mutable parent budget to deduct from.
-    /// @param amount Native value to assign to the sub-budget.
-    /// @return A new budget with `amount` remaining.
-    function allocateValue(Budget memory budget, uint amount) internal pure returns (Budget memory) {
-        return Values.allocate(budget, amount);
+    /// @param resources Packed chain resources.
+    /// @return A new budget with the EVM value lane remaining.
+    function allocateValue(Budget memory budget, uint resources) internal pure returns (Budget memory) {
+        return Values.allocate(budget, uint128(resources));
     }
 
     /// @notice Drains the budget and settles any remaining native value.

package/core/Pipeline.sol

@@ -20,14 +20,14 @@ abstract contract Pipeline is Payable {
     /// @param account Account identifier for the piped context.
     /// @param state Current threaded state block stream.
     /// @param request Step request block stream.
-    /// @param value Native value assigned to this step.
+    /// @param value Native EVM value assigned to this step.
     /// @return Updated state block stream for the next step.
     function dispatch(
         uint target,
         bytes32 account,
         bytes memory state,
         bytes calldata request,
-        uint value
+        uint128 value
     ) internal virtual returns (bytes memory);
 
     /// @notice Execute a STEP block stream through the pipeline.
@@ -45,8 +45,8 @@ abstract contract Pipeline is Payable {
         (Cur memory input, , ) = Cursors.init(steps, 0, 1);
 
         while (input.i < input.len) {
-            (uint target, uint value, bytes calldata request) = input.unpackStep();
-            state = dispatch(target, account, state, request, useValue(budget, value));
+            (uint target, uint resources, bytes calldata request) = input.unpackStep();
+            state = dispatch(target, account, state, request, useValue(budget, resources));
         }
 
         if (state.length != 0) revert UnexpectedState();

package/docs/Schema.md

@@ -56,9 +56,9 @@ A block payload has fixed fields first, followed by an optional child-block tail
 Once a child block appears, no more fixed fields may follow.
 
 ```txt
-#call { uint target, uint value, #bytes as payload }
+#call { uint target, uint resources, #bytes as payload }
 #context { bytes32 account, #bytes as state, #bytes as request }
-#pipe { uint value, #context { bytes32 account, #bytes as state, #bytes as request } }
+#pipe { uint resources, #context { bytes32 account, #bytes as state, #bytes as steps } }
 ```
 
 The tail is embedded directly as child block bytes. There is no wrapper around a
@@ -108,7 +108,7 @@ or runtime keys.
 
 ```txt
 maybe #account { bytes32 account } as recipient
-#call { uint target, uint value, #bytes as payload }
+#call { uint target, uint resources, #bytes as payload }
 ```
 
 Aliases may be used on any block item, including child blocks and prime items.
@@ -131,6 +131,13 @@ Integers are encoded big-endian. Signed integers use two's-complement encoding
 for their declared width. `bool` is one byte: `0x00` for false and `0x01` for
 true. `bytesN` values are encoded as exactly `N` bytes with no padding.
 
+## Chain Resources
+
+Fields named `resources` are chain-specific resource words. Different chain
+types may pack these words differently, but a given chain type must use one
+stable format everywhere. For EVM chains, the low 128 bits are native value /
+endowment in wei; higher bits are reserved for execution resources such as gas.
+
 ## Identifiers
 
 Block names, field names, and aliases use lower camelCase ASCII identifiers:
@@ -185,10 +192,10 @@ Common protocol schemas live in `contracts/blocks/Schema.sol`:
 #amount { bytes32 asset, bytes32 meta, uint amount }
 #balance { bytes32 asset, bytes32 meta, uint amount }
 #custody { uint host, bytes32 asset, bytes32 meta, uint amount }
-#call { uint target, uint value, #bytes as payload }
-#step { uint target, uint value, #bytes as request }
+#call { uint target, uint resources, #bytes as payload }
+#step { uint target, uint resources, #bytes as request }
 #context { bytes32 account, #bytes as state, #bytes as request }
-#pipe { uint value, #context { bytes32 account, #bytes as state, #bytes as request } }
+#pipe { uint resources, #context { bytes32 account, #bytes as state, #bytes as steps } }
 #auth { uint cid, uint deadline, #bytes as proof }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",
@@ -8,6 +8,7 @@
   "files": [
     "**/*.sol",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/Schema.md"
   ],

package/peer/Dispatch.sol

@@ -4,24 +4,14 @@ pragma solidity ^0.8.33;
 import { PeerBase } from "./Base.sol";
 import { Payable } from "../core/Payable.sol";
 import { Cursors, Cur, Schemas } from "../Cursors.sol";
+import { DispatchPayableHook } from "../commands/Relay.sol";
 import { Budget } from "../utils/Value.sol";
 
 using Cursors for Cur;
 
-abstract contract PeerDispatchPayableHook {
-    /// @notice Override to dispatch an already encoded payload to `chain`.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific destination resources. EVM adapters
-    /// may interpret this as packed execution gas and destination value.
-    /// @param payload Encoded payload ready for the transport layer.
-    /// @param budget Source-chain native-value budget available for transport
-    /// fees and destination resource funding.
-    function dispatch(uint chain, uint resources, bytes calldata payload, Budget memory budget) internal virtual;
-}
-
 /// @title PeerDispatchPayable
 /// @notice Peer endpoint that forwards DISPATCH blocks to a host-defined dispatch hook.
-abstract contract PeerDispatchPayable is PeerBase, Payable, PeerDispatchPayableHook {
+abstract contract PeerDispatchPayable is PeerBase, Payable, DispatchPayableHook {
     string private constant NAME = "peerDispatchPayable";
     uint internal immutable peerDispatchPayableId = peerId(NAME);
 
@@ -36,14 +26,14 @@ abstract contract PeerDispatchPayable is PeerBase, Payable, PeerDispatchPayableH
     /// @return output Empty response bytes.
     function peerDispatchPayable(bytes calldata request) external payable onlyPeer returns (bytes memory output) {
         (Cur memory input, , ) = Cursors.init(request, 0, 1);
-        Budget memory budget = valueBudget();
-
-        while (input.i < input.len) {
-            (uint chain, uint resources, bytes calldata payload) = input.unpackDispatch();
-            dispatch(chain, resources, payload, budget);
-        }
-
-        input.complete();
+        Budget memory budget = valueBudget();
+
+        while (input.i < input.len) {
+            (uint chain, uint resources, bytes calldata payload) = input.unpackDispatch();
+            dispatch(chain, resources, bytes(payload), budget);
+        }
+
+        input.complete();
         return "";
     }
 

package/peer/Pipe.sol

@@ -10,7 +10,7 @@ using Cursors for Cur;
 
 /// @title PeerPipePayable
 /// @notice Peer that consumes PIPE blocks and executes each context step stream.
-/// Each PIPE block carries a value budget plus a CONTEXT block; the nested
+/// Each PIPE block carries chain resources plus a CONTEXT block; the nested
 /// context steps are passed to the shared pipeline as the step stream.
 abstract contract PeerPipePayable is PeerBase, Pipeline {
     string private constant NAME = "peerPipePayable";
@@ -21,7 +21,7 @@ abstract contract PeerPipePayable is PeerBase, Pipeline {
     }
 
     /// @notice Execute peer-supplied pipes through the shared payable pipe.
-    /// @dev Each pipe receives its own explicit value sub-budget. Any top-level
+    /// @dev Each pipe receives its own explicit EVM value sub-budget. Any top-level
     ///      `msg.value` not assigned to a pipe remains on this host.
     /// @param request PIPE block stream supplied by the trusted peer.
     /// @return Empty response bytes.
@@ -30,8 +30,8 @@ abstract contract PeerPipePayable is PeerBase, Pipeline {
         Budget memory budget = valueBudget();
 
         while (input.i < input.len) {
-            (uint value, bytes32 account, bytes calldata state, bytes calldata steps) = input.unpackPipe();
-            pipe(account, state, steps, allocateValue(budget, value));
+            (uint resources, bytes32 account, bytes calldata state, bytes calldata steps) = input.unpackPipe();
+            pipe(account, state, steps, allocateValue(budget, resources));
         }
 
         input.complete();

package/utils/Value.sol

@@ -18,9 +18,10 @@ library Values {
     /// @param budget Mutable budget to deduct from.
     /// @param amount Native value to spend in wei.
     /// @return The same `amount`, ready to forward to a callee.
-    function use(Budget memory budget, uint amount) internal pure returns (uint) {
-        if (amount > budget.remaining) revert InsufficientValue();
-        budget.remaining -= amount;
+    function use(Budget memory budget, uint128 amount) internal pure returns (uint128) {
+        uint value = uint(amount);
+        if (value > budget.remaining) revert InsufficientValue();
+        budget.remaining -= value;
         return amount;
     }
 
@@ -29,7 +30,7 @@ library Values {
     /// @param budget Mutable parent budget to deduct from.
     /// @param amount Native value to assign to the sub-budget, in wei.
     /// @return A new budget with `amount` remaining.
-    function allocate(Budget memory budget, uint amount) internal pure returns (Budget memory) {
+    function allocate(Budget memory budget, uint128 amount) internal pure returns (Budget memory) {
         return Budget({remaining: use(budget, amount)});
     }
 }