@rootzero/contracts 0.9.8 → 1.0.0

package/Core.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to bring the full rootzero host base layer into scope.
 
 import { AccessControl } from "./core/Access.sol";
-import { Balances } from "./core/Balances.sol";
+import { Balances, InsufficientFunds } from "./core/Balances.sol";
 import { Runtime } from "./core/Runtime.sol";
 import { Host, IHostIntroduction } from "./core/Host.sol";
 import { FailedCall, NodeCalls } from "./core/Calls.sol";

package/Endpoints.sol

@@ -14,8 +14,9 @@ import { Burn, BurnHook } from "./commands/Burn.sol";
 import { CreditAccount, CreditAccountHook } from "./commands/Credit.sol";
 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 { Transfer, TransferHook } from "./commands/Transfer.sol";
+import { RelayPayable, RelayPayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -37,6 +38,7 @@ import { PeerAllowance } from "./peer/Allowance.sol";
 import { PeerBalancePull, BalancePullHook } from "./peer/BalancePull.sol";
 import { PeerDenyAssets } from "./peer/DenyAssets.sol";
 import { PeerPipePayable } from "./peer/Pipe.sol";
+import { PeerDispatchPayable } from "./peer/Dispatch.sol";
 import { PeerSettle } from "./peer/Settle.sol";
 
 // Guard endpoints

package/Events.sol

@@ -8,6 +8,7 @@ import { AdminEvent } from "./events/Admin.sol";
 import { AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
+import { ChainEvent } from "./events/Chain.sol";
 import { CommandEvent } from "./events/Command.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
@@ -21,6 +22,7 @@ import { PeerEvent } from "./events/Peer.sol";
 import { QueryEvent } from "./events/Query.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { SpentEvent } from "./events/Spent.sol";
+import { TransferEvent } from "./events/Transfer.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";
 
 

package/README.md

@@ -8,11 +8,11 @@ It contains the reusable contracts, utilities, cursor parsers, and encoding help
 
 Most consumers should start from the package root entry points:
 
-- `@rootzero/contracts/Core.sol` — host, access control, balances, and validator building blocks
-- `@rootzero/contracts/Endpoints.sol` — command, peer, guard, and query base contracts plus standard endpoint mixins
-- `@rootzero/contracts/Cursors.sol` — cursor reader (`Cur`), block schemas, key constants, typed block helpers, and writers
-- `@rootzero/contracts/Utils.sol` — IDs, assets, accounts, layout, and value helpers
-- `@rootzero/contracts/Events.sol` — reusable event emitters and event contracts
+- `@rootzero/contracts/Core.sol` - host, access control, balances, and validator building blocks
+- `@rootzero/contracts/Endpoints.sol` - command, peer, guard, and query base contracts plus standard endpoint mixins
+- `@rootzero/contracts/Cursors.sol` - cursor reader (`Cur`), block schemas, key constants, typed block helpers, and writers
+- `@rootzero/contracts/Utils.sol` - IDs, assets, accounts, layout, and value helpers
+- `@rootzero/contracts/Events.sol` - reusable event emitters and event contracts
 
 ## Block Wire Format
 
@@ -28,7 +28,7 @@ All request and response data is encoded as a binary block stream. Each block is
 
 Protocol blocks use schema strings and four-byte keys:
 
-- `Schemas` describes semantic protocol blocks such as `#amount`, `#balance`, `#custody`, and `#payout`.
+- `Schemas` describes semantic protocol blocks such as `#amount`, `#balance`, `#custody`, and `#relay`.
 - `Forms` describes reusable structural blocks such as `#accountAsset` and `#accountAmount`, mostly used by queries.
 - `Keys` contains the runtime `bytes4` keys derived from block names.
 
@@ -77,21 +77,21 @@ abstract contract ExampleCommand is CommandBase {
     uint internal immutable myCommandId = commandId(NAME);
 
     constructor() {
-        emit Command(host, myCommandId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false);
+        emit Command(host, myCommandId, NAME, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false, false);
     }
 
     function myCommand(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups) = cursor(c.request, 1);
+        (Cur memory request, uint groups, ) = Cursors.init(c.request, 0, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
-        while (request.i < request.bound) {
+        while (request.i < request.len) {
             (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
             writer.appendBalance(asset, meta, amount);
         }
 
-        request.close();
+        request.complete();
         return writer.finish();
     }
 }
@@ -99,14 +99,15 @@ abstract contract ExampleCommand is CommandBase {
 
 ## Repo Layout
 
-- `contracts/core` — host, access control, balances, operation base, and signature validation
-- `contracts/commands` — standard command building blocks and admin commands
-- `contracts/peer` — peer protocol surfaces for inter-host asset flows and asset allow/deny
-- `contracts/blocks` — block stream schema (`Schema`), cursor parsing (`Cursors`), and writers (`Writers`)
-- `contracts/utils` — shared encoding helpers: IDs, assets, accounts, layout, ECDSA
-- `contracts/events` — protocol event contracts and emitters
-- `contracts/interfaces` — discovery interfaces and shared external protocol surfaces
-- `docs` — introductory documentation
+- `contracts/core` - host, access control, balances, operation base, and signature validation
+- `contracts/commands` - standard command building blocks and admin commands
+- `contracts/peer` - peer protocol surfaces for inter-host asset flows and asset allow/deny
+- `contracts/guards` - guard action surfaces for delegated protection flows
+- `contracts/queries` - read-only query endpoints for protocol state
+- `contracts/blocks` - block stream schema (`Schema`), cursor parsing (`Cursors`), and writers (`Writers`)
+- `contracts/utils` - shared encoding helpers: IDs, assets, accounts, layout, ECDSA
+- `contracts/events` - protocol event contracts and emitters
+- `docs` - introductory documentation
 
 ## Install and Compile
 

package/blocks/Cursors.sol

@@ -6,7 +6,7 @@ import {Sizes} from "./Schema.sol";
 import {Keys} from "./Keys.sol";
 
 /// @notice Zero-copy view into a calldata block stream.
-/// All positions (`i`, `bound`) are byte offsets relative to the start of the source region.
+/// All positions (`i`) are byte offsets relative to the start of the source region.
 /// The absolute calldata location of byte `i` is `offset + i`.
 struct Cur {
     /// @dev Absolute calldata byte offset of the source region start.
@@ -15,9 +15,6 @@ struct Cur {
     uint i;
     /// @dev Total byte length of the source region.
     uint len;
-    /// @dev Exclusive upper bound for the current iteration group, set by `primeRun`.
-    /// Zero until `primeRun` is called.
-    uint bound;
 }
 
 using Cursors for Cur;
@@ -32,11 +29,11 @@ library Cursors {
     error MalformedBlocks();
     /// @dev Current block key does not match the expected key, or payload size is out of range.
     error InvalidBlock();
-    /// @dev `complete` called but the cursor has not consumed exactly up to `bound`.
+    /// @dev `complete` called but the cursor has not consumed exactly to `len`.
     error IncompleteCursor();
-    /// @dev `primeRun` found zero blocks of the expected key; the cursor region is empty.
+    /// @dev `run` found zero blocks of the expected key; the cursor region is empty.
     error ZeroCursor();
-    /// @dev `primeRun` was called with a zero group size.
+    /// @dev `run` was called with a zero group size.
     error ZeroGroup();
     /// @dev An account field was required but the block or fallback was zero.
     error ZeroAccount();
@@ -65,15 +62,50 @@ library Cursors {
         cur.len = source.length;
     }
 
-    /// @notice Create a cursor and prime it for a grouped iteration pass.
-    /// Equivalent to `open(source)` followed by `primeRun(group)`.
-    /// @param source Calldata slice that forms the block stream.
+    /// @notice Create a cursor backed by `source[i:]`.
+    /// @param source Calldata slice that forms the parent block stream.
+    /// @param i Start byte offset within `source`.
+    /// @return cur Cursor positioned at the beginning of `source[i:]`.
+    function open(bytes calldata source, uint i) internal pure returns (Cur memory cur) {
+        return open(source[i:]);
+    }
+
+    /// @notice Create a cursor over `source[i:]` and restrict it to its first grouped run.
+    /// Equivalent to `open(source, i)`, reading the current key, then `run(key, group)`.
+    /// @param source Calldata slice that forms the parent block stream.
+    /// @param i Start byte offset within `source`.
     /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
-    /// @return cur Cursor with `bound` set to the end of the first run.
-    /// @return groups Number of block groups in the run (`prime block count / group`).
-    function init(bytes calldata source, uint group) internal pure returns (Cur memory cur, uint groups) {
-        cur = open(source);
-        (, groups) = cur.primeRun(group);
+    /// @return cur Cursor with `len` truncated to the end of the first run in `source[i:]`.
+    /// @return groups Number of block groups in the run (`block count / group`).
+    /// @return next Byte offset immediately after the run, relative to `source`.
+    function init(
+        bytes calldata source,
+        uint i,
+        uint group
+    ) internal pure returns (Cur memory cur, uint groups, uint next) {
+        cur = open(source, i);
+        if (cur.i == cur.len) revert ZeroCursor();
+        (bytes4 key, ) = cur.peek(cur.i);
+        groups = cur.run(key, group);
+        next = i + cur.len;
+    }
+
+    /// @notice Create a cursor over `source[i:]`, restrict it to its first grouped run, and require an exact group count.
+    /// @param source Calldata slice that forms the parent block stream.
+    /// @param i Start byte offset within `source`.
+    /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
+    /// @param expectedGroups Required number of groups in the run.
+    /// @return cur Cursor with `len` truncated to the end of the first run in `source[i:]`.
+    /// @return next Byte offset immediately after the run, relative to `source`.
+    function init(
+        bytes calldata source,
+        uint i,
+        uint group,
+        uint expectedGroups
+    ) internal pure returns (Cur memory cur, uint next) {
+        uint groups;
+        (cur, groups, next) = init(source, i, group);
+        if (groups != expectedGroups) revert BadRatio();
     }
 
     /// @notice Move the cursor to an absolute position within the source region.
@@ -119,7 +151,7 @@ library Cursors {
     }
 
     /// @notice Return the full cursor region as a calldata slice.
-    /// Does not advance the cursor; `cur.i` and `cur.bound` are ignored.
+    /// Does not advance the cursor; `cur.i` is ignored.
     /// @param cur Cursor whose backing region should be returned.
     /// @return data Calldata view over `[cur.offset, cur.offset + cur.len)`.
     function raw(Cur memory cur) internal pure returns (bytes calldata data) {
@@ -128,7 +160,7 @@ library Cursors {
     }
 
     /// @notice Return a sub-range of the cursor region as a calldata slice.
-    /// Does not advance the cursor; `cur.i` and `cur.bound` are ignored.
+    /// Does not advance the cursor; `cur.i` is ignored.
     /// @param cur Source cursor.
     /// @param from Start byte offset within the source region (inclusive).
     /// @param to End byte offset within the source region (exclusive).
@@ -267,21 +299,19 @@ library Cursors {
         }
     }
 
-    /// @notice Initialise the cursor for a grouped iteration pass.
-    /// Reads the key of the first block, counts the consecutive run of that key,
-    /// stores the run end in `cur.bound`, validates that the count is a
-    /// multiple of `group`, and returns the run key and normalized group count.
-    /// @param cur Cursor to prime; `cur.bound` is updated in place.
+    /// @notice Restrict the cursor to the consecutive run of `key` at its current position.
+    /// Counts the run, truncates `cur.len` to the run end, and validates that the
+    /// count is a multiple of `group`.
+    /// @param cur Cursor to restrict; `cur.len` is updated in place.
+    /// @param key Expected block type identifier of the run.
     /// @param group Expected group size (e.g. 1 for single-asset, 2 for paired input/output).
-    /// @return key Block type identifier of the run.
     /// @return groups Number of groups represented by the run (`block count / group`).
-    function primeRun(Cur memory cur, uint group) internal pure returns (bytes4 key, uint groups) {
+    function run(Cur memory cur, bytes4 key, uint group) internal pure returns (uint groups) {
         if (group == 0) revert ZeroGroup();
-        key = cur.i + 4 > cur.len ? bytes4(0) : bytes4(msg.data[cur.offset + cur.i:cur.offset + cur.i + 4]);
-        uint count;
-        (count, cur.bound) = countRun(cur, cur.i, key);
+        (uint count, uint next) = countRun(cur, cur.i, key);
         if (count == 0) revert ZeroCursor();
         if (count % group != 0) revert BadRatio();
+        cur.len = next;
         groups = count / group;
     }
 
@@ -361,17 +391,6 @@ library Cursors {
         return maybeTake(cur, Keys.Data);
     }
 
-    /// @notice Enter a List block, prime its member run, and return the group count.
-    /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
-    /// @param group Expected block group size for the list item stream.
-    /// @return groups Number of block groups in the list payload.
-    /// @return next Byte offset immediately after the list payload.
-    function list(Cur memory cur, uint group) internal pure returns (uint groups, uint next) {
-        next = list(cur);
-        (, groups) = cur.primeRun(group);
-        if (cur.bound != next) revert IncompleteCursor();
-    }
-
     /// @notice Exit a nested region at an exact boundary.
     /// Reverts with `IncompleteCursor` if `end` exceeds the cursor region length
     /// or `cur.i != end`.
@@ -381,13 +400,6 @@ library Cursors {
         if (end > cur.len || cur.i != end) revert IncompleteCursor();
     }
 
-    /// @notice Assert that the cursor has consumed exactly up to `bound`.
-    /// Reverts with `IncompleteCursor` if `bound` is zero or `cur.i != cur.bound`.
-    /// @param cur Cursor to check.
-    function close(Cur memory cur) internal pure {
-        if (cur.bound == 0 || cur.i != cur.bound) revert IncompleteCursor();
-    }
-
     /// @notice Assert that the cursor has consumed its entire source region.
     /// Reverts with `IncompleteCursor` when `cur.i != cur.len`.
     /// @param cur Cursor to check.
@@ -527,7 +539,11 @@ library Cursors {
     /// @param state Embedded state block stream.
     /// @param request Embedded request block stream.
     /// @return Encoded CONTEXT block bytes.
-    function toContextBlock(bytes32 account, bytes memory state, bytes memory request) internal pure returns (bytes memory) {
+    function toContextBlock(
+        bytes32 account,
+        bytes memory state,
+        bytes memory request
+    ) internal pure returns (bytes memory) {
         return createBlock(Keys.Context, bytes.concat(account, toBytesBlock(state), toBytesBlock(request)));
     }
 
@@ -535,15 +551,33 @@ library Cursors {
     /// @param value Native value assigned to the pipe.
     /// @param account Command account identifier.
     /// @param state Embedded state block stream.
-    /// @param request Embedded request block stream.
+    /// @param steps Embedded step block stream.
     /// @return Encoded PIPE block bytes.
     function toPipeBlock(
         uint value,
         bytes32 account,
         bytes memory state,
-        bytes memory request
+        bytes memory steps
     ) internal pure returns (bytes memory) {
-        return createBlock(Keys.Pipe, bytes.concat(bytes32(value), toContextBlock(account, state, request)));
+        return createBlock(Keys.Pipe, bytes.concat(bytes32(value), toContextBlock(account, state, steps)));
+    }
+
+    /// @notice Encode a RELAY block.
+    /// @param chain Destination chain node ID.
+    /// @param endowment Native value requested for the destination pipe.
+    /// @param steps Nested step block stream.
+    /// @return Encoded RELAY block bytes.
+    function toRelayBlock(uint chain, uint endowment, bytes memory steps) internal pure returns (bytes memory) {
+        return createBlock(Keys.Relay, bytes.concat(bytes32(chain), bytes32(endowment), toBytesBlock(steps)));
+    }
+
+    /// @notice Encode a DISPATCH block.
+    /// @param chain Destination chain node ID.
+    /// @param endowment Native value requested for the destination dispatch.
+    /// @param payload Encoded cross-chain payload.
+    /// @return Encoded DISPATCH block bytes.
+    function toDispatchBlock(uint chain, uint endowment, bytes memory payload) internal pure returns (bytes memory) {
+        return createBlock(Keys.Dispatch, bytes.concat(bytes32(chain), bytes32(endowment), toBytesBlock(payload)));
     }
 
     // -------------------------------------------------------------------------
@@ -902,38 +936,6 @@ library Cursors {
         (value.asset, value.meta, value.amount) = unpackAssetAmount(cur, Keys.Balance);
     }
 
-    /// @notice Consume a MINIMUM block and return its fields as separate values.
-    /// @param cur Cursor; advanced past the block.
-    /// @return asset Asset identifier.
-    /// @return meta Asset metadata slot.
-    /// @return amount Minimum acceptable amount.
-    function unpackMinimum(Cur memory cur) internal pure returns (bytes32 asset, bytes32 meta, uint amount) {
-        return unpackAssetAmount(cur, Keys.Minimum);
-    }
-
-    /// @notice Consume a MINIMUM block and return its fields as a struct.
-    /// @param cur Cursor; advanced past the block.
-    /// @return value Decoded asset, meta, and minimum amount.
-    function unpackMinimumValue(Cur memory cur) internal pure returns (AssetAmount memory value) {
-        (value.asset, value.meta, value.amount) = unpackAssetAmount(cur, Keys.Minimum);
-    }
-
-    /// @notice Consume a MAXIMUM block and return its fields as separate values.
-    /// @param cur Cursor; advanced past the block.
-    /// @return asset Asset identifier.
-    /// @return meta Asset metadata slot.
-    /// @return amount Maximum allowable spend.
-    function unpackMaximum(Cur memory cur) internal pure returns (bytes32 asset, bytes32 meta, uint amount) {
-        return unpackAssetAmount(cur, Keys.Maximum);
-    }
-
-    /// @notice Consume a MAXIMUM block and return its fields as a struct.
-    /// @param cur Cursor; advanced past the block.
-    /// @return value Decoded asset, meta, and maximum amount.
-    function unpackMaximumValue(Cur memory cur) internal pure returns (AssetAmount memory value) {
-        (value.asset, value.meta, value.amount) = unpackAssetAmount(cur, Keys.Maximum);
-    }
-
     /// @notice Consume a HOST_ACCOUNT_ASSET form block and return its fields as separate values.
     /// @param cur Cursor; advanced past the block.
     /// @return host Host node ID.
@@ -953,25 +955,6 @@ library Cursors {
         (value.host, value.account, value.asset, value.meta) = unpackHostAccountAsset(cur, Keys.HostAccountAsset);
     }
 
-    /// @notice Consume a PAYOUT block and return its fields as separate values.
-    /// @param cur Cursor; advanced past the block.
-    /// @return account Account identifier.
-    /// @return asset Asset identifier.
-    /// @return meta Asset metadata slot.
-    /// @return amount Token amount.
-    function unpackPayout(
-        Cur memory cur
-    ) internal pure returns (bytes32 account, bytes32 asset, bytes32 meta, uint amount) {
-        return unpackAccountAmount(cur, Keys.Payout);
-    }
-
-    /// @notice Consume a PAYOUT block and return its fields as a struct.
-    /// @param cur Cursor; advanced past the block.
-    /// @return value Decoded account, asset, meta, and amount.
-    function unpackPayoutValue(Cur memory cur) internal pure returns (AccountAmount memory value) {
-        (value.account, value.asset, value.meta, value.amount) = unpackAccountAmount(cur, Keys.Payout);
-    }
-
     /// @notice Consume an ACCOUNT_AMOUNT form block and return its fields as separate values.
     /// @param cur Cursor; advanced past the block.
     /// @return account Account identifier.
@@ -1102,7 +1085,9 @@ library Cursors {
     /// @return account Command account identifier.
     /// @return state Embedded state block stream.
     /// @return request Embedded request block stream.
-    function unpackContext(Cur memory cur) internal pure returns (bytes32 account, bytes calldata state, bytes calldata request) {
+    function unpackContext(
+        Cur memory cur
+    ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata request) {
         uint end = cur.enter(Keys.Context, 32 + 2 * Sizes.Header, 0);
         account = cur.read32();
         state = cur.unpackBytes();
@@ -1115,13 +1100,43 @@ library Cursors {
     /// @return value Native value assigned to the pipe.
     /// @return account Command account identifier.
     /// @return state Embedded state block stream.
-    /// @return request Embedded request 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 request) {
+    ) internal pure returns (uint value, 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());
-        (account, state, request) = cur.unpackContext();
+        (account, state, steps) = cur.unpackContext();
+        cur.exit(end);
+    }
+
+    /// @notice Consume a RELAY block and return its destination chain, endowment, and step stream.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return endowment Native value requested for the destination pipe.
+    /// @return steps Embedded step block stream.
+    function unpackRelay(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint endowment, bytes calldata steps) {
+        uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
+        chain = uint(cur.read32());
+        endowment = uint(cur.read32());
+        steps = cur.unpackBytes();
+        cur.exit(end);
+    }
+
+    /// @notice Consume a DISPATCH block and return its destination chain, endowment, and payload.
+    /// @param cur Cursor; advanced past the block.
+    /// @return chain Destination chain node ID.
+    /// @return endowment Native value requested for the destination dispatch.
+    /// @return payload Encoded cross-chain payload.
+    function unpackDispatch(
+        Cur memory cur
+    ) internal pure returns (uint chain, uint endowment, bytes calldata payload) {
+        uint end = cur.enter(Keys.Dispatch, 64 + Sizes.Header, 0);
+        chain = uint(cur.read32());
+        endowment = uint(cur.read32());
+        payload = cur.unpackBytes();
         cur.exit(end);
     }
 
@@ -1194,15 +1209,6 @@ library Cursors {
         if (uint(bytes32(msg.data[abs + 64:abs + 96])) != 1) revert UnexpectedValue();
     }
 
-    /// @notice Consume a MINIMUM block and assert it matches the expected asset and meta.
-    /// @param cur Cursor; advanced past the block.
-    /// @param asset Expected asset identifier.
-    /// @param meta Expected metadata slot.
-    /// @return amount Minimum amount from the block.
-    function requireMinimum(Cur memory cur, bytes32 asset, bytes32 meta) internal pure returns (uint amount) {
-        return requireAssetAmount(cur, Keys.Minimum, asset, meta);
-    }
-
     /// @notice Consume a host amount block and assert it matches the expected host.
     /// @param cur Cursor; advanced past the block.
     /// @param key Expected block type key.
@@ -1324,7 +1330,39 @@ library Cursors {
     }
 
     // -------------------------------------------------------------------------
-    // Trailing-block helpers (search after bound)
+    // ensure* - validate constraint blocks against provided values
+    // -------------------------------------------------------------------------
+
+    /// @notice Consume a BALANCE_LIMIT block and assert all constraint fields match the provided balance.
+    /// @param cur Cursor; advanced past the block.
+    /// @param asset Expected asset identifier.
+    /// @param meta Expected metadata slot.
+    /// @param amount Amount that must fall within the encoded min/max range.
+    function ensureBalanceLimit(Cur memory cur, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        uint abs = consume(cur, 0, Keys.BalanceLimit, 128, 128);
+        if (bytes32(msg.data[abs:abs + 32]) != asset) revert UnexpectedValue();
+        if (bytes32(msg.data[abs + 32:abs + 64]) != meta) revert UnexpectedValue();
+        if (uint(bytes32(msg.data[abs + 64:abs + 96])) > amount) revert UnexpectedValue();
+        if (uint(bytes32(msg.data[abs + 96:abs + 128])) < amount) revert UnexpectedValue();
+    }
+
+    /// @notice Consume a CUSTODY_LIMIT block and assert all constraint fields match the provided custody.
+    /// @param cur Cursor; advanced past the block.
+    /// @param host Expected host node ID.
+    /// @param asset Expected asset identifier.
+    /// @param meta Expected metadata slot.
+    /// @param amount Amount that must fall within the encoded min/max range.
+    function ensureCustodyLimit(Cur memory cur, uint host, bytes32 asset, bytes32 meta, uint amount) internal pure {
+        uint abs = consume(cur, 0, Keys.CustodyLimit, 160, 160);
+        if (uint(bytes32(msg.data[abs:abs + 32])) != host) revert UnexpectedValue();
+        if (bytes32(msg.data[abs + 32:abs + 64]) != asset) revert UnexpectedValue();
+        if (bytes32(msg.data[abs + 64:abs + 96]) != meta) revert UnexpectedValue();
+        if (uint(bytes32(msg.data[abs + 96:abs + 128])) > amount) revert UnexpectedValue();
+        if (uint(bytes32(msg.data[abs + 128:abs + 160])) < amount) revert UnexpectedValue();
+    }
+
+    // -------------------------------------------------------------------------
+    // Search helpers
     // -------------------------------------------------------------------------
 
     /// @notice Look for a NODE block anywhere in a calldata source and return its value.
@@ -1364,52 +1402,4 @@ library Cursors {
         (uint abs, ) = expect(cur, i, 0, Keys.Account, 32, 32);
         return bytes32(msg.data[abs:abs + 32]);
     }
-
-    /// @notice Look for a NODE block after the current run boundary and return its value.
-    /// Searches from `cur.bound` to the end of the source region.
-    /// @param cur Source cursor; `bound` marks the end of the primary run.
-    /// @param backup Value to return if no NODE block is found.
-    /// @return node Node ID from the NODE block, or `backup` if absent.
-    function nodeAfter(Cur memory cur, uint backup) internal pure returns (uint node) {
-        uint i = find(cur, cur.bound, Keys.Node);
-        if (i == cur.len) return backup;
-
-        (uint abs, ) = expect(cur, i, 0, Keys.Node, 32, 32);
-        return uint(bytes32(msg.data[abs:abs + 32]));
-    }
-
-    /// @notice Look for an ACCOUNT block after the current run boundary and return its value.
-    /// Searches from `cur.bound` to the end of the source region.
-    /// @param cur Source cursor; `bound` marks the end of the primary run.
-    /// @param backup Account to return if no ACCOUNT block is found.
-    /// @return account Account from the ACCOUNT block, or `backup` if absent.
-    function accountAfter(Cur memory cur, bytes32 backup) internal pure returns (bytes32 account) {
-        uint i = find(cur, cur.bound, Keys.Account);
-        if (i == cur.len) return backup;
-
-        (uint abs, ) = expect(cur, i, 0, Keys.Account, 32, 32);
-        return bytes32(msg.data[abs:abs + 32]);
-    }
-
-    /// @notice Parse the trailing AUTH block and compute the signed message hash.
-    /// The AUTH block must occupy the final `Sizes.Auth` bytes of the source region
-    /// and must begin after `cur.bound`.
-    /// The signed slice covers from `cur.i` up to (but not including) the AUTH proof bytes.
-    /// @param cur Source cursor; `bound` marks the end of the primary data region.
-    /// @param cid Command ID that the signature must be bound to.
-    /// @return digest keccak256 of the signed message slice.
-    /// @return deadline Expiry timestamp from the AUTH block.
-    /// @return proof Raw proof bytes (layout: `[bytes20 signer][bytes65 sig]`).
-    function authLast(
-        Cur memory cur,
-        uint cid
-    ) internal pure returns (bytes32 digest, uint deadline, bytes calldata proof) {
-        if (cur.len - cur.i < Sizes.Auth) revert MalformedBlocks();
-
-        uint i = cur.len - Sizes.Auth;
-        if (i < cur.bound) revert MalformedBlocks();
-
-        (deadline, proof) = expectAuth(cur, i, cid);
-        digest = cur.hash(cur.i, cur.len - Sizes.Proof);
-    }
 }

package/blocks/Keys.sol

@@ -7,20 +7,22 @@ pragma solidity ^0.8.33;
 library Keys {
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
+    /// @dev Wildcard key used in discovery when any block stream is accepted.
+    bytes4 constant Any = 0xffffffff;
     /// @dev Input amount - (bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Balance = bytes4(keccak256("#balance"));
+    /// @dev Balance constraint - (bytes32 asset, bytes32 meta, uint min, uint max)
+    bytes4 constant BalanceLimit = bytes4(keccak256("#balanceLimit"));
     /// @dev Host-scoped request amount - (uint host, bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Allocation = bytes4(keccak256("#allocation"));
     /// @dev Host-scoped allowance cap - (uint host, bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Allowance = bytes4(keccak256("#allowance"));
     /// @dev Cross-host custody state - (uint host, bytes32 asset, bytes32 meta, uint amount)
     bytes4 constant Custody = bytes4(keccak256("#custody"));
-    /// @dev Minimum acceptable output - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Minimum = bytes4(keccak256("#minimum"));
-    /// @dev Maximum allowable spend - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Maximum = bytes4(keccak256("#maximum"));
+    /// @dev Cross-host custody constraint - (uint host, bytes32 asset, bytes32 meta, uint min, uint max)
+    bytes4 constant CustodyLimit = bytes4(keccak256("#custodyLimit"));
     /// @dev Fee amount - (uint amount)
     bytes4 constant Fee = bytes4(keccak256("#fee"));
     /// @dev List wrapper; payload is an embedded repeated block stream
@@ -33,12 +35,14 @@ library Keys {
     bytes4 constant Bytes = bytes4(keccak256("#bytes"));
     /// @dev Account identifier - (bytes32 account)
     bytes4 constant Account = bytes4(keccak256("#account"));
-    /// @dev Transfer payout request - (bytes32 account, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Payout = bytes4(keccak256("#payout"));
     /// @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)
     bytes4 constant Step = bytes4(keccak256("#step"));
+    /// @dev Cross-chain pipe relay - (uint chain, uint endowment, #bytes as steps)
+    bytes4 constant Relay = bytes4(keccak256("#relay"));
+    /// @dev Cross-chain encoded payload dispatch - (uint chain, uint endowment, #bytes as payload)
+    bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
     /// @dev Raw external call - (uint target, uint value, #bytes as payload)
     bytes4 constant Call = bytes4(keccak256("#call"));
     /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)