@rootzero/contracts 1.29.0 → 1.30.0

package/core/Pipeline.sol

@@ -2,11 +2,11 @@
 pragma solidity ^0.8.33;
 
 import {Blocks} from "../codec/Blocks.sol";
+import {Keys} from "../codec/Keys.sol";
 import {TrustAccess} from "./Access.sol";
-import {rawCommandCall} from "./Calls.sol";
-import {Cursors} from "../utils/Cursors.sol";
 import {InsufficientValue, OutOfBounds, UnexpectedState} from "../utils/Errors.sol";
-import {unpackCommand} from "../utils/Nodes.sol";
+import {Nodes} from "../utils/Nodes.sol";
+import {Flags} from "../utils/Flags.sol";
 
 /// @notice Hook implemented by hosts that execute encoded step streams.
 abstract contract PipeHook {
@@ -24,7 +24,9 @@ abstract contract ExecuteHook {
     /// @notice Try to execute one command whose node ID targets the current host.
     /// @dev Implementations returning `handled = true` are responsible for
     /// authorizing the command. Return false without side effects to delegate to
-    /// the trusted normal external entrypoint. Implementations may revert instead.
+    /// the trusted normal external entrypoint. Handoff commands must be delegated
+    /// because this hook receives ordinary input without the continuation that
+    /// Pipeline adds to the RELAY envelope. Implementations may revert instead.
     function execute(
         uint cmd,
         bytes32 account,
@@ -36,22 +38,171 @@ abstract contract ExecuteHook {
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
+/// @dev This gas-sensitive implementation intentionally inlines the command ID
+/// layout and the CONTEXT, BYTES, and RELAY block encodings. Changes to command
+/// selector, target, or flag placement, or to those block layouts, must update
+/// the corresponding assembly and packed-cursor logic here.
 abstract contract Pipeline is TrustAccess, PipeHook, ExecuteHook {
-    function run(
+    /// @dev Private pipeline cursor layout:
+    /// bits 0-31 current STEP offset, 32-63 stream end,
+    /// 64-95 command-input offset, 96-127 command-input length.
+    function unpackBytes(uint abs) private pure returns (uint input, uint end) {
+        uint body;
+        (body, end) = Blocks.expectKey(abs, Keys.Bytes);
+        // `expectKey` constructs `end` as `body + uint32(length)`.
+        unchecked {
+            input = uint32(body) | ((end - body) << 32);
+        }
+    }
+
+    function takeStep(uint cursor) private pure returns (uint cmd, uint value, uint updated) {
+        uint abs = uint32(cursor);
+        uint limit;
+        (abs, limit) = Blocks.expectKey(abs, Keys.Step);
+        assembly ("memory-safe") {
+            cmd := calldataload(abs)
+            value := calldataload(add(abs, 0x20))
+        }
+
+        (uint input, uint end) = unpackBytes(abs + 64);
+        if (end != limit) revert Blocks.InvalidBlock();
+        if (end > uint32(cursor >> 32)) revert OutOfBounds();
+
+        updated = uint32(end) | (uint64(cursor) & (uint(type(uint32).max) << 32)) | (input << 64);
+    }
+
+    function rawInput(uint cursor) private pure returns (bytes calldata input) {
+        assembly ("memory-safe") {
+            input.offset := and(shr(64, cursor), 0xffffffff)
+            input.length := and(shr(96, cursor), 0xffffffff)
+        }
+    }
+
+    /// @dev Execute the prepared command call and strictly decode `(bytes, uint)`.
+    function invokeCommand(
         uint cmd,
+        uint value,
         bytes32 account,
         bytes memory state,
-        bytes calldata input,
-        uint value
+        uint input
     ) private returns (bytes memory output, uint credit) {
-        (bytes4 selector, address target) = unpackCommand(cmd);
-        if (target == address(this)) {
+        assembly ("memory-safe") {
+            let scratch := mload(0x40)
+            let ctxlen
+            switch iszero(shr(64, input))
+            case 1 {
+                let statelen := mload(state)
+                let inputlen := and(shr(32, input), 0xffffffff)
+                ctxlen := add(56, add(statelen, inputlen))
+
+                mstore(scratch, shl(224, and(shr(160, cmd), 0xffffffff)))
+                mstore(add(scratch, 0x04), 0x20)
+                mstore(add(scratch, 0x24), ctxlen)
+
+                let p := add(scratch, 0x44)
+                mstore(p, or(shl(224, 0xc5769e23), shl(192, sub(ctxlen, 8))))
+                mstore(add(p, 0x08), account)
+                p := add(p, 0x28)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, statelen)))
+                mcopy(add(p, 0x08), add(state, 0x20), statelen)
+                p := add(add(p, 0x08), statelen)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, inputlen)))
+                calldatacopy(add(p, 0x08), and(input, 0xffffffff), inputlen)
+            }
+            default {
+                let statelen := mload(state)
+                let inputlen := and(shr(96, input), 0xffffffff)
+                let stepslen := sub(and(shr(32, input), 0xffffffff), and(input, 0xffffffff))
+                let relaylen := add(16, add(inputlen, stepslen))
+                ctxlen := add(64, add(statelen, relaylen))
+
+                mstore(scratch, shl(224, and(shr(160, cmd), 0xffffffff)))
+                mstore(add(scratch, 0x04), 0x20)
+                mstore(add(scratch, 0x24), ctxlen)
+
+                let p := add(scratch, 0x44)
+                mstore(p, or(shl(224, 0xc5769e23), shl(192, sub(ctxlen, 8))))
+                mstore(add(p, 0x08), account)
+                p := add(p, 0x28)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, statelen)))
+                mcopy(add(p, 0x08), add(state, 0x20), statelen)
+
+                p := add(add(p, 0x08), statelen)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, add(8, relaylen))))
+                p := add(p, 0x08)
+                mstore(p, or(shl(224, 0xc34cc52a), shl(192, relaylen)))
+                p := add(p, 0x08)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, inputlen)))
+                calldatacopy(add(p, 0x08), and(shr(64, input), 0xffffffff), inputlen)
+                p := add(add(p, 0x08), inputlen)
+                mstore(p, or(shl(224, 0x6911b332), shl(192, stepslen)))
+                calldatacopy(add(p, 0x08), and(input, 0xffffffff), stepslen)
+            }
+            ctxlen := add(68, and(add(ctxlen, 0x1f), not(0x1f)))
+            let inputend := and(add(add(scratch, ctxlen), 0x1f), not(0x1f))
+            let success := call(
+                gas(),
+                and(cmd, 0xffffffffffffffffffffffffffffffffffffffff),
+                value,
+                scratch,
+                ctxlen,
+                0,
+                0
+            )
+            let retlen := returndatasize()
+            if iszero(success) {
+                mstore(scratch, shl(224, 0x20577b07))
+                mstore(add(scratch, 0x04), and(cmd, 0xffffffffffffffffffffffffffffffffffffffff))
+                mstore(add(scratch, 0x24), shl(224, and(shr(160, cmd), 0xffffffff)))
+                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)
+            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)
+        }
+    }
+
+    function run(
+        uint cmd,
+        bytes32 account,
+        bytes memory state,
+        uint value,
+        uint cursor
+    ) private returns (bytes memory output, uint credit, uint updated) {
+        if (address(uint160(cmd)) == address(this)) {
             bool handled;
-            (handled, output, credit) = execute(cmd, account, state, input, value);
-            if (handled) return (output, credit);
+            (handled, output, credit) = execute(cmd, account, state, rawInput(cursor), value);
+            if (handled) return (output, credit, cursor);
         }
-        ensureTrusted(cmd);
-        return rawCommandCall(selector, target, value, account, state, input);
+        ensureTrusted(Nodes.command(cmd));
+        bool handoff = uint8(cmd >> 224) & Flags.Handoff != 0;
+        (output, credit) = invokeCommand(cmd, value, account, state, handoff ? cursor : cursor >> 64);
+        updated = handoff ? (cursor & ~uint(type(uint32).max)) | uint32(cursor >> 32) : cursor;
     }
 
     /// @notice Execute a STEP block stream through the pipeline.
@@ -68,18 +219,21 @@ abstract contract Pipeline is TrustAccess, PipeHook, ExecuteHook {
         bytes calldata steps,
         uint budget
     ) internal virtual override returns (uint remaining) {
-        (uint abs, uint end) = Cursors.bounds(steps);
+        uint cursor;
+        assembly ("memory-safe") {
+            cursor := or(steps.offset, shl(32, add(steps.offset, steps.length)))
+        }
 
-        while (abs < end) {
-            (uint cmd, uint value, bytes calldata input, uint next) = Blocks.unpackStep(abs);
-            if (next > end) revert OutOfBounds();
+        while (uint32(cursor) < uint32(cursor >> 32)) {
+            uint cmd;
+            uint value;
+            (cmd, value, cursor) = takeStep(cursor);
             if (value > budget) revert InsufficientValue();
             unchecked {
                 budget -= value;
             }
-            (state, value) = run(cmd, account, state, input, value);
+            (state, value, cursor) = run(cmd, account, state, value, cursor);
             budget += value;
-            abs = next;
         }
 
         if (state.length != 0) revert UnexpectedState();

package/core/Settlement.sol

@@ -44,7 +44,7 @@ abstract contract SettleHook {
 
 /// @title Settlement
 /// @notice Default account-hook implementation for transaction posting and position settlement.
-abstract contract Settlement is PostHook, SettleHook, RepayHook, DebitAccountHook, CreditAccountHook {
+abstract contract Settlement is PostHook, DebitAccountHook, CreditAccountHook, SettleHook, RepayHook {
     /// @notice Post one transaction by debiting its source and crediting its destination.
     /// Returns without calling either hook when `amount` is zero and skips either
     /// operation when the corresponding account is zero.

package/execution/Execution.sol

@@ -71,29 +71,29 @@ library Executions {
         return exec.decoders.absolute();
     }
 
-    /// @dev Return the complete bounded calldata source for a decoder lane.
-    /// @dev Does not consume or depend on the lane's current position. A lane
-    /// absent because its descriptor is EMPTY returns an empty calldata slice.
+    /// @dev Return the unread bounded calldata source for a decoder lane.
+    /// A lane absent because its descriptor is EMPTY returns an empty calldata slice.
     /// @param exec Execution whose input or state source is requested.
-    /// @return data Complete calldata region represented by the lane.
+    /// @return data Unread calldata region from the lane's current position.
     function raw(Execution memory exec, uint8 lane) private pure returns (bytes calldata data) {
         if (!exec.decoders.contains(lane)) return msg.data[0:0];
 
         uint cur = exec.decoders.select(lane);
         if (uint8(cur >> 96) == 0) return msg.data[0:0];
-        (uint abs, uint end) = cur.bounds();
-        if (end > msg.data.length) revert Blocks.MalformedBlocks();
-        return msg.data[abs:end];
+        (uint i, uint offset, uint len) = cur.decode();
+        if (len > msg.data.length || offset > msg.data.length - len) {
+            revert Blocks.MalformedBlocks();
+        }
+        return msg.data[offset + i:offset + len];
     }
 
-    /// @notice Return the complete bounded command state without consuming it.
-    /// @dev Remains the complete original state after the state cursor advances.
+    /// @notice Return the unread bounded command state without consuming it.
     function rawState(Execution memory exec) internal pure returns (bytes calldata) {
         return raw(exec, Lanes.State);
     }
 
-    /// @notice Return the complete state lane and mark it fully consumed.
-    /// @dev Intended for commands that forward their state intact without decoding it.
+    /// @notice Return the unread state lane and mark it fully consumed.
+    /// @dev Intended for commands that forward their remaining state without decoding it.
     /// A lane declared EMPTY is returned empty and remains unconsumed so close
     /// still rejects any state supplied against the descriptor.
     function takeRawState(Execution memory exec) internal pure returns (bytes calldata data) {
@@ -106,14 +106,13 @@ library Executions {
         exec.decoders = cur.seek(len);
     }
 
-    /// @notice Return the complete bounded endpoint input without consuming it.
-    /// @dev Remains the complete original input after the input cursor advances.
+    /// @notice Return the unread bounded endpoint input without consuming it.
     function rawInput(Execution memory exec) internal pure returns (bytes calldata) {
         return raw(exec, Lanes.Input);
     }
 
-    /// @notice Return the complete input lane and mark it fully consumed.
-    /// @dev Intended for endpoints that forward their input intact without decoding it.
+    /// @notice Return the unread input lane and mark it fully consumed.
+    /// @dev Intended for endpoints that forward their remaining input without decoding it.
     /// A lane declared EMPTY is returned empty and remains unconsumed so close
     /// still rejects any input supplied against the descriptor.
     function takeRawInput(Execution memory exec) internal pure returns (bytes calldata data) {
@@ -330,15 +329,6 @@ library Executions {
         node = Blocks.unpackNode(abs);
     }
 
-    /// @notice Decode and consume one CASHOUT block from the active lane.
-    /// @param exec Execution whose decoder is advanced.
-    /// @return amount Native-asset amount to withdraw.
-    function unpackCashout(Execution memory exec) internal pure returns (uint amount) {
-        uint abs;
-        (exec.decoders, abs) = exec.decoders.consume(Sizes.Cashout);
-        amount = Blocks.unpackCashout(abs);
-    }
-
     /// @notice Decode and consume one BOOTSTRAP block from the active lane.
     /// @param exec Execution whose decoder is advanced.
     /// @return asset Decoded asset identifier.
@@ -664,13 +654,12 @@ library Executions {
 
     /// @notice Decode and consume one RELAY block from the active lane.
     /// @param exec Execution whose decoder is advanced.
-    /// @return portal Decoded destination portal.
-    /// @return resources Decoded packed resources.
     /// @return input Decoded nested input.
-    function unpackRelay(Execution memory exec) internal pure returns (uint portal, uint resources, bytes calldata input) {
+    /// @return steps Decoded remaining pipeline steps.
+    function unpackRelay(Execution memory exec) internal pure returns (bytes calldata input, bytes calldata steps) {
         uint cur = exec.decoders;
         uint end;
-        (portal, resources, input, end) = Blocks.unpackRelay(cur.absolute());
+        (input, steps, end) = Blocks.unpackRelay(cur.absolute());
         exec.decoders = cur.seekAbs(end);
     }
 
@@ -1048,13 +1037,12 @@ library Executions {
 
     /// @notice Append a RELAY block to execution output.
     /// @param exec Execution receiving the block.
-    /// @param portal Destination portal to encode.
-    /// @param resources Packed resources to encode.
     /// @param input Relay input to encode.
-    function outputRelay(Execution memory exec, uint portal, uint resources, bytes memory input) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + input.length;
+    /// @param steps Remaining pipeline steps to encode.
+    function outputRelay(Execution memory exec, bytes memory input, bytes memory steps) internal pure {
+        uint size = 3 * Sizes.Header + input.length + steps.length;
         uint i = reserve(exec, size);
-        Blocks.writeRelay(exec.output, i, portal, resources, input);
+        Blocks.writeRelay(exec.output, i, input, steps);
     }
 
     /// @notice Append a DISPATCH block to execution output.
@@ -1177,11 +1165,11 @@ library Executions {
         Blocks.copyCall(exec.output, i, target, resources, payload);
     }
 
-    /// @notice Append a RELAY block to execution output by copying its nested input from calldata.
-    function outputCopyRelay(Execution memory exec, uint portal, uint resources, bytes calldata input) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + input.length;
+    /// @notice Append a RELAY block to execution output by copying its nested streams from calldata.
+    function outputCopyRelay(Execution memory exec, bytes calldata input, bytes calldata steps) internal pure {
+        uint size = 3 * Sizes.Header + input.length + steps.length;
         uint i = reserve(exec, size);
-        Blocks.copyRelay(exec.output, i, portal, resources, input);
+        Blocks.copyRelay(exec.output, i, input, steps);
     }
 
     /// @notice Append a DISPATCH block to execution output by copying its nested payload from calldata.

package/package.json

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

package/ports/Allowance.sol

@@ -2,34 +2,24 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
+import {AllowanceHook} from "../commands/admin/Allowance.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions} from "../execution/Execution.sol";
 
 using Executions for Execution;
 
-/// @notice Hook implemented by hosts that handle allowance requests from peers.
-abstract contract RequestAllowanceHook {
-    /// @notice Override to handle one allowance request from a peer host.
-    /// @dev The implementation is responsible for validating the request and
-    /// deciding what allowance, if any, to grant.
-    /// @param peer Peer host node ID requesting the allowance.
-    /// @param asset Asset identifier supplied by the peer.
-    /// @param amount Allowance amount requested in the asset's native units.
-    function requestAllowance(uint peer, bytes32 asset, uint amount) internal virtual;
-}
-
 /// @title RequestAllowancePort
-/// @notice Port that lets trusted peers request their own asset allowances.
-/// Each AMOUNT block is scoped to the caller and passed unchanged to
-/// `requestAllowance(peer, asset, amount)`.
-abstract contract RequestAllowancePort is PortBase, RequestAllowanceHook {
+/// @notice Port that lets trusted peers set their own asset allowances.
+/// Each AMOUNT block is scoped to the authenticated caller and applied through
+/// the shared authoritative allowance hook.
+abstract contract RequestAllowancePort is PortBase, AllowanceHook {
     uint private immutable descriptor;
 
     constructor() {
         (, descriptor) = port("portRequestAllowance", Specs.Amount, Specs.Empty, 0);
     }
 
-    /// @notice Request asset allowances for the calling peer.
+    /// @notice Set asset allowances for the calling peer.
     /// @param data AMOUNT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portRequestAllowance(bytes calldata data) external onlyPeer returns (bytes memory) {
@@ -38,7 +28,7 @@ abstract contract RequestAllowancePort is PortBase, RequestAllowanceHook {
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount();
-            requestAllowance(peer, asset, amount);
+            allowance(peer, asset, amount);
         }
 
         return "";

package/ports/Base.sol

@@ -12,6 +12,9 @@ import { Descriptors } from "../codec/Descriptors.sol";
 /// @notice Abstract base for peer-facing rootzero ports.
 /// Ports handle inter-host operations between cooperating hosts.
 /// Access is restricted to trusted peer callers via `onlyPeer`.
+/// @dev By convention, trusting a peer authorizes it to use every port exposed
+/// by the host without an additional policy decision in each port. Hosts that
+/// need narrower capabilities may enforce them in hooks or custom port bases.
 abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
 
     /// @dev Restrict execution to trusted callers, excluding the commander.
@@ -55,7 +58,7 @@ abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
         string memory name,
         uint descriptor
     ) internal returns (uint id, uint published) {
-        id = Nodes.toPort(name, address(this));
+        id = Nodes.toPort(name, address(this), uint8(descriptor));
         published = endpoint(id, name, descriptor);
     }
 }

package/ports/Dispatch.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {Flags} from "../codec/Descriptors.sol";
+import {Flags} from "../utils/Flags.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions} from "../execution/Execution.sol";
 

package/ports/Pipe.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {Flags} from "../codec/Descriptors.sol";
+import {Flags} from "../utils/Flags.sol";
 import {PipeHook} from "../core/Pipeline.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions} from "../execution/Execution.sol";

package/queries/Base.sol

@@ -38,7 +38,7 @@ abstract contract QueryBase is InputEndpointBase {
         string memory name,
         uint descriptor
     ) internal returns (uint id, uint published) {
-        id = Nodes.toQuery(name, address(this));
+        id = Nodes.toQuery(name, address(this), uint8(descriptor));
         published = endpoint(id, name, descriptor);
     }
 }

package/utils/Accounts.sol

@@ -19,12 +19,12 @@ import {ensureAddr, isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol"
 ///
 /// The helpers in this library validate and deconstruct structured account IDs.
 library Accounts {
-    /// @dev 24-bit family tag shared by all EVM-backed account types.
-    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Account);
+    /// @dev 16-bit family tag shared by all EVM-backed account types.
+    uint16 constant Family = (uint16(Layout.Evm) << 8) | uint16(Layout.Account);
     /// @dev Full 4-byte type prefix for admin accounts (chain-local EVM address).
-    uint32 constant Admin = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Admin);
+    uint32 constant Admin = (uint32(Layout.Evm) << 24) | (uint32(Layout.Account) << 16) | (uint32(Layout.Admin) << 8);
     /// @dev Full 4-byte type prefix for user accounts (chain-agnostic EVM address).
-    uint32 constant User = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
+    uint32 constant User = (uint32(Layout.Evm) << 24) | (uint32(Layout.Account) << 16) | (uint32(Layout.User) << 8);
 
     /// @notice Extract the 4-byte type prefix from an account ID.
     /// @param account Account identifier.

package/utils/Assets.sol

@@ -21,12 +21,12 @@ import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
 ///
 /// All asset IDs are chain-local (include `block.chainid` in bits [223:192]).
 library Assets {
-    /// @dev 24-bit family tag shared by all EVM-backed asset types.
-    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Asset);
+    /// @dev 16-bit family tag shared by all EVM-backed asset types.
+    uint16 constant Family = (uint16(Layout.Evm) << 8) | uint16(Layout.Asset);
     /// @dev Full 4-byte type prefix for the native chain coin/token asset.
-    uint32 constant Native = (uint32(Layout.Evm) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Native);
+    uint32 constant Native = (uint32(Layout.Evm) << 24) | (uint32(Layout.Asset) << 16) | (uint32(Layout.Native) << 8);
     /// @dev Full 4-byte type prefix for ERC-20 assets.
-    uint32 constant Erc20 = (uint32(Layout.Evm) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc20);
+    uint32 constant Erc20 = (uint32(Layout.Evm) << 24) | (uint32(Layout.Asset) << 16) | (uint32(Layout.Erc20) << 8);
 
     /// @notice Return true if `asset` belongs to the EVM asset family.
     function isEvm(bytes32 asset) internal pure returns (bool) {
@@ -126,7 +126,6 @@ library Assets {
         if (erc20Addr(asset) != token) revert InvalidAsset();
         return asset;
     }
-
 }
 
 /// @title Amounts

package/utils/Cursors.sol

@@ -81,7 +81,30 @@ library Cursors {
         end = abs + uint32(cur >> 64);
     }
 
-    /// @notice Create a cursor backed by a calldata slice.
+    /// @notice Return the unread calldata region represented by the lower cursor.
+    /// @dev DANGER: This trusts the packed cursor and does not validate the frame
+    /// against `msg.data`. Assumes the cursor invariant `i <= len`; any upper
+    /// cursor is ignored.
+    /// @param cur Packed cursor or cursor pair whose unread region is returned.
+    /// @return data Lower-cursor calldata from its current position through its end.
+    function raw(uint cur) internal pure returns (bytes calldata data) {
+        assembly ("memory-safe") {
+            let i := and(cur, 0xffffffff)
+            data.offset := add(and(shr(32, cur), 0xffffffff), i)
+            data.length := sub(and(shr(64, cur), 0xffffffff), i)
+        }
+    }
+
+    /// @notice Create an untagged cursor backed by a calldata slice.
+    /// @param source Calldata slice represented by the cursor.
+    /// @return cur Packed cursor positioned at the slice beginning.
+    function wrap(bytes calldata source) internal pure returns (uint cur) {
+        assembly ("memory-safe") {
+            cur := or(shl(32, source.offset), shl(64, source.length))
+        }
+    }
+
+    /// @notice Create a tagged cursor backed by a calldata slice.
     /// @param source Calldata slice represented by the cursor.
     /// @param tag Cursor identity tag.
     /// @return cur Packed cursor positioned at the slice beginning.

package/utils/Flags.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @title Flags
+/// @notice Shared endpoint behavior flags encoded in both endpoint IDs and descriptors.
+/// @dev Bit 6 is reserved for endpoint-defined custom behavior.
+library Flags {
+    /// @dev Endpoint accepts nonzero native value.
+    uint8 internal constant Funded = 1 << 0;
+    /// @dev Endpoint is restricted to the admin account.
+    uint8 internal constant Admin = 1 << 1;
+    /// @dev Endpoint accepts nonzero native value and is restricted to the admin account.
+    uint8 internal constant AdminFunded = Admin | Funded;
+    /// @dev Endpoint takes ownership of the remaining pipeline steps.
+    uint8 internal constant Handoff = 1 << 7;
+    /// @dev Endpoint accepts nonzero native value and takes ownership of the remaining pipeline steps.
+    uint8 internal constant HandoffFunded = Handoff | Funded;
+}

package/utils/Layout.sol

@@ -7,7 +7,7 @@ pragma solidity ^0.8.33;
 ///
 /// IDs are structured as:
 ///   `[uint32 type][uint32 chainid][192-bit payload]`
-/// where `type` is `[uint16 representation][uint8 category][uint8 subtype]`.
+/// where `type` is `[uint8 representation][uint8 category][uint8 subtype][uint8 flags]`.
 ///
 /// Values whose first byte is zero are opaque IDs:
 ///   `[0x00][bytes31 truncated hash]`
@@ -17,11 +17,11 @@ pragma solidity ^0.8.33;
 /// Values whose first byte is nonzero follow the structured layout above.
 library Layout {
     // -------------------------------------------------------------------------
-    // Representation tags (top 2 bytes of the ID type field)
+    // Representation tags (first byte of the ID type field)
     // -------------------------------------------------------------------------
 
     /// @dev EVM-compatible ID; lower 20 payload bytes hold an address when present.
-    uint16 constant Evm = 0x0120;
+    uint8 constant Evm = 0x01;
 
     // -------------------------------------------------------------------------
     // Category tags (uint8, third byte of the ID type field)