@rootzero/contracts 1.28.0 → 1.30.0

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.28.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)

package/utils/Nodes.sol

@@ -6,21 +6,6 @@ import {InvalidId} from "./Errors.sol";
 import {Ids} from "./Ids.sol";
 import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
 
-/// @notice Validate and unpack a command node into its ABI selector and target address.
-/// @dev Validates only the command type prefix; chain locality and authorization are caller concerns.
-/// @param cmd Command node ID to unpack.
-/// @return selector ABI selector stored in bits [191:160].
-/// @return target Contract address stored in bits [159:0].
-function unpackCommand(uint cmd) pure returns (bytes4 selector, address target) {
-    uint32 command = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
-    if (uint32(cmd >> 224) != command) revert InvalidId();
-
-    assembly ("memory-safe") {
-        selector := shl(224, and(shr(160, cmd), 0xffffffff))
-        target := and(cmd, 0xffffffffffffffffffffffffffffffffffffffff)
-    }
-}
-
 /// @title Nodes
 /// @notice Encoding and decoding helpers for 256-bit node identifiers.
 ///
@@ -36,20 +21,20 @@ function unpackCommand(uint cmd) pure returns (bytes4 selector, address target)
 ///
 /// The helpers in this library validate and deconstruct structured node IDs.
 library Nodes {
-    /// @dev 24-bit family tag shared by all node types (Evm + Node category).
-    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Node);
+    /// @dev 16-bit family tag shared by all node types (Evm + Node category).
+    uint16 constant Family = (uint16(Layout.Evm) << 8) | uint16(Layout.Node);
     /// @dev Full 4-byte type prefix for chain/domain nodes.
-    uint32 constant Chain = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Chain);
+    uint32 constant Chain = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Chain) << 8);
     /// @dev Full 4-byte type prefix for host nodes.
-    uint32 constant Host = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Host);
+    uint32 constant Host = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Host) << 8);
     /// @dev Full 4-byte type prefix for command nodes.
-    uint32 constant Command = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
+    uint32 constant Command = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Command) << 8);
     /// @dev Full 4-byte type prefix for port nodes.
-    uint32 constant Port = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Port);
+    uint32 constant Port = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Port) << 8);
     /// @dev Full 4-byte type prefix for query nodes.
-    uint32 constant Query = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Query);
+    uint32 constant Query = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Query) << 8);
     /// @dev Full 4-byte type prefix for guard action nodes.
-    uint32 constant Guard = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Guard);
+    uint32 constant Guard = (uint32(Layout.Evm) << 24) | (uint32(Layout.Node) << 16) | (uint32(Layout.Guard) << 8);
 
     /// @notice Return true if `node` is a host node ID.
     function isHost(uint node) internal pure returns (bool) {
@@ -58,22 +43,22 @@ library Nodes {
 
     /// @notice Return true if `node` is a command node ID.
     function isCommand(uint node) internal pure returns (bool) {
-        return uint32(node >> 224) == Command;
+        return (uint32(node >> 224) & 0xffffff00) == Command;
     }
 
     /// @notice Return true if `node` is a port node ID.
     function isPort(uint node) internal pure returns (bool) {
-        return uint32(node >> 224) == Port;
+        return (uint32(node >> 224) & 0xffffff00) == Port;
     }
 
     /// @notice Return true if `node` is a query node ID.
     function isQuery(uint node) internal pure returns (bool) {
-        return uint32(node >> 224) == Query;
+        return (uint32(node >> 224) & 0xffffff00) == Query;
     }
 
     /// @notice Return true if `node` is a guard action node ID.
     function isGuard(uint node) internal pure returns (bool) {
-        return uint32(node >> 224) == Guard;
+        return (uint32(node >> 224) & 0xffffff00) == Guard;
     }
 
     /// @notice Return true if `node` belongs to the EVM node family.
@@ -210,7 +195,12 @@ library Nodes {
     /// @param target Command contract address.
     /// @return node Command node ID embedding both the selector and address.
     function toCommand(string memory name, address target) internal view returns (uint node) {
-        node = toLocalBase(Command) | uint(uint160(target));
+        return toCommand(name, target, 0);
+    }
+
+    /// @notice Build a chain-local command ID carrying endpoint behavior flags.
+    function toCommand(string memory name, address target, uint8 flags) internal view returns (uint node) {
+        node = toLocalBase(Command | uint32(flags)) | uint(uint160(target));
         node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 
@@ -219,7 +209,12 @@ library Nodes {
     /// @param target Port contract address.
     /// @return node Port node ID embedding both the selector and address.
     function toPort(string memory name, address target) internal view returns (uint node) {
-        node = toLocalBase(Port) | uint(uint160(target));
+        return toPort(name, target, 0);
+    }
+
+    /// @notice Build a chain-local port ID carrying endpoint behavior flags.
+    function toPort(string memory name, address target, uint8 flags) internal view returns (uint node) {
+        node = toLocalBase(Port | uint32(flags)) | uint(uint160(target));
         node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 
@@ -228,7 +223,12 @@ library Nodes {
     /// @param target Query contract address.
     /// @return node Query node ID embedding both the selector and address.
     function toQuery(string memory name, address target) internal view returns (uint node) {
-        node = toLocalBase(Query) | uint(uint160(target));
+        return toQuery(name, target, 0);
+    }
+
+    /// @notice Build a chain-local query ID carrying endpoint behavior flags.
+    function toQuery(string memory name, address target, uint8 flags) internal view returns (uint node) {
+        node = toLocalBase(Query | uint32(flags)) | uint(uint160(target));
         node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 
@@ -237,7 +237,12 @@ library Nodes {
     /// @param target Guard action contract address.
     /// @return node Guard action node ID embedding both the selector and address.
     function toGuard(string memory name, address target) internal view returns (uint node) {
-        node = toLocalBase(Guard) | uint(uint160(target));
+        return toGuard(name, target, 0);
+    }
+
+    /// @notice Build a chain-local guard ID carrying endpoint behavior flags.
+    function toGuard(string memory name, address target, uint8 flags) internal view returns (uint node) {
+        node = toLocalBase(Guard | uint32(flags)) | uint(uint160(target));
         node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 

package/utils/Utils.sol

@@ -207,13 +207,13 @@ function toUnspecifiedBase(uint32 prefix) pure returns (uint) {
     return uint(prefix) << 224;
 }
 
-/// @notice Check whether `value` belongs to the given 24-bit family.
-/// Only tests the top 3 bytes (bits [255:232]); does not check chainid.
+/// @notice Check whether `value` belongs to the given 16-bit representation/category family.
+/// Only tests the top 2 bytes (bits [255:240]); does not check subtype, flags, or chainid.
 /// @param value ID to test.
 /// @param family Expected family tag.
-/// @return True if the top 3 bytes of `value` match `family`.
-function isFamily(uint value, uint24 family) pure returns (bool) {
-    return uint24(value >> 232) == family;
+/// @return True if the top 2 bytes of `value` match `family`.
+function isFamily(uint value, uint16 family) pure returns (bool) {
+    return uint16(value >> 240) == family;
 }
 
 /// @notice Check whether two IDs share the same 64-bit base (type tag + chainid).