@rootzero/contracts 1.4.0 → 1.5.0

package/utils/Ids.sol

@@ -1,250 +1,50 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Layout} from "./Layout.sol";
-import {isLocalFamily, matchesBase, toLocalBase} from "./Utils.sol";
-
 /// @title Ids
-/// @notice Encoding and decoding helpers for 256-bit node identifiers.
+/// @notice Shared helpers for the protocol-wide 256-bit ID convention.
+///
+/// IDs whose first byte is zero are opaque:
+///   `[0x00][bytes31 truncated hash]`
 ///
-/// Node IDs share a common layout:
-///   - bits [255:224] — 4-byte type prefix (`Host`, `Command`, or `Peer`)
-///   - bits [223:192] — current `block.chainid` (makes IDs chain-local)
-///   - bits [191:160] — 4-byte ABI selector (commands and peers only)
-///   - bits [159:0]   — 160-bit EVM contract address
+/// Opaque keccak preimages start with `0x01`, and the ID is derived as:
+///   `0x00 || bytes31(keccak256(preimage))`
 library Ids {
-    /// @dev Thrown when an ID does not match the expected node type or chain.
+    /// @dev Thrown when an ID does not match the expected convention.
     error InvalidId();
+    /// @dev Thrown when an opaque ID preimage is missing or uses an unsupported format/hash tag.
+    error InvalidPreimage();
 
-    /// @dev 24-bit family tag shared by all node types (Evm32 + Node category).
-    uint24 constant Node = (uint24(Layout.Evm32) << 8) | uint24(Layout.Node);
-    /// @dev Full 4-byte type prefix for chain/domain nodes.
-    uint32 constant Chain = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Chain);
-    /// @dev Full 4-byte type prefix for host nodes.
-    uint32 constant Host = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Host);
-    /// @dev Full 4-byte type prefix for command nodes.
-    uint32 constant Command = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
-    /// @dev Full 4-byte type prefix for peer nodes.
-    uint32 constant Peer = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Peer);
-    /// @dev Full 4-byte type prefix for query nodes.
-    uint32 constant Query = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Query);
-    /// @dev Full 4-byte type prefix for guard action nodes.
-    uint32 constant Guard = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Guard);
-
-    /// @notice Return true if `id` is a host node ID.
-    function isHost(uint id) internal pure returns (bool) {
-        return uint32(id >> 224) == Host;
-    }
-
-    /// @notice Return true if `id` is a command node ID.
-    function isCommand(uint id) internal pure returns (bool) {
-        return uint32(id >> 224) == Command;
-    }
-
-    /// @notice Return true if `id` is a peer node ID.
-    function isPeer(uint id) internal pure returns (bool) {
-        return uint32(id >> 224) == Peer;
-    }
-
-    /// @notice Return true if `id` is a query node ID.
-    function isQuery(uint id) internal pure returns (bool) {
-        return uint32(id >> 224) == Query;
-    }
-
-    /// @notice Return true if `id` is a guard action node ID.
-    function isGuard(uint id) internal pure returns (bool) {
-        return uint32(id >> 224) == Guard;
-    }
-
-    /// @notice Return true if `id` is a local node ID for this contract.
-    function isLocalNode(uint id) internal view returns (bool) {
-        return uint32(id >> 224) != Chain && isLocalFamily(id, Node) && address(uint160(id)) == address(this);
-    }
-
-    /// @notice Assert that `id` is a command ID and return it unchanged.
-    /// @param id Node ID to validate.
-    /// @return cid The same `id` value if it is a command.
-    function command(uint id) internal pure returns (uint cid) {
-        if (!isCommand(id)) revert InvalidId();
-        return id;
-    }
-
-    /// @notice Assert that `id` is a peer ID and return it unchanged.
-    /// @param id Node ID to validate.
-    /// @return pid The same `id` value if it is a peer.
-    function peer(uint id) internal pure returns (uint pid) {
-        if (!isPeer(id)) revert InvalidId();
-        return id;
-    }
-
-    /// @notice Assert that `id` is a query ID and return it unchanged.
-    /// @param id Node ID to validate.
-    /// @return queryId The same `id` value if it is a query.
-    function query(uint id) internal pure returns (uint queryId) {
-        if (!isQuery(id)) revert InvalidId();
-        return id;
-    }
-
-    /// @notice Assert that `id` is a guard action ID and return it unchanged.
-    /// @param id Node ID to validate.
-    /// @return guardId The same `id` value if it is a guard action.
-    function guard(uint id) internal pure returns (uint guardId) {
-        if (!isGuard(id)) revert InvalidId();
-        return id;
-    }
-
-    /// @notice Assert that `id` is a command ID and return its embedded ABI selector.
-    /// @param id Node ID to validate.
-    /// @return selector 4-byte command selector stored in bits [191:160].
-    function commandSelector(uint id) internal pure returns (bytes4 selector) {
-        return bytes4(uint32(command(id) >> 160));
-    }
-
-    /// @notice Assert that `id` is a peer ID and return its embedded ABI selector.
-    /// @param id Node ID to validate.
-    /// @return selector 4-byte peer selector stored in bits [191:160].
-    function peerSelector(uint id) internal pure returns (bytes4 selector) {
-        return bytes4(uint32(peer(id) >> 160));
-    }
-
-    /// @notice Assert that `id` is a query ID and return its embedded ABI selector.
-    /// @param id Node ID to validate.
-    /// @return selector 4-byte query selector stored in bits [191:160].
-    function querySelector(uint id) internal pure returns (bytes4 selector) {
-        return bytes4(uint32(query(id) >> 160));
-    }
-
-    /// @notice Assert that `id` is a guard action ID and return its embedded ABI selector.
-    /// @param id Node ID to validate.
-    /// @return selector 4-byte guard selector stored in bits [191:160].
-    function guardSelector(uint id) internal pure returns (bytes4 selector) {
-        return bytes4(uint32(guard(id) >> 160));
-    }
-
-    /// @notice Assert that `id` is the host ID of `addr` on the current chain.
-    /// @param id Node ID to validate.
-    /// @param addr Expected host contract address.
-    /// @return hid The same `id` value if it matches `addr`.
-    function matchHost(uint id, address addr) internal view returns (uint hid) {
-        if (id != toHost(addr)) revert InvalidId();
-        return id;
-    }
-
-    /// @notice Build the chain node ID for the current chain.
-    /// @return Chain node ID with the Chain prefix and `block.chainid` payload.
-    function localChain() internal view returns (uint) {
-        uint id = block.chainid;
-        if (id >> 224 != 0) revert InvalidId();
-        return (uint(Chain) << 224) | id;
-    }
-
-    /// @notice Build a chain-local host ID for `target`.
-    /// @param target Host contract address.
-    /// @return Host node ID on the current chain.
-    function toHost(address target) internal view returns (uint) {
-        return toLocalBase(Host) | uint(uint160(target));
-    }
-
-    /// @notice Build a chain-local command ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the command entry point.
-    /// @param target Command contract address.
-    /// @return Command node ID embedding both the selector and address.
-    function toCommand(bytes4 selector, address target) internal view returns (uint) {
-        uint id = toLocalBase(Command) | uint(uint160(target));
-        id |= uint(uint32(selector)) << 160;
-        return id;
-    }
-
-    /// @notice Build a chain-local peer ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the peer entry point.
-    /// @param target Peer contract address.
-    /// @return Peer node ID embedding both the selector and address.
-    function toPeer(bytes4 selector, address target) internal view returns (uint) {
-        uint id = toLocalBase(Peer) | uint(uint160(target));
-        id |= uint(uint32(selector)) << 160;
-        return id;
-    }
-
-    /// @notice Build a chain-local query ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the query entry point.
-    /// @param target Query contract address.
-    /// @return Query node ID embedding both the selector and address.
-    function toQuery(bytes4 selector, address target) internal view returns (uint) {
-        uint id = toLocalBase(Query) | uint(uint160(target));
-        id |= uint(uint32(selector)) << 160;
-        return id;
-    }
-
-    /// @notice Build a chain-local guard action ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the guard action entry point.
-    /// @param target Guard action contract address.
-    /// @return Guard action node ID embedding both the selector and address.
-    function toGuard(bytes4 selector, address target) internal view returns (uint) {
-        uint id = toLocalBase(Guard) | uint(uint160(target));
-        id |= uint(uint32(selector)) << 160;
-        return id;
-    }
-
-    /// @notice Extract the contract address from any local node ID.
-    /// Reverts if `id` does not belong to the local node family.
-    /// @param id Node ID (host, command, or peer).
-    /// @return Contract address in the lower 160 bits of `id`.
-    function nodeAddr(uint id) internal view returns (address) {
-        if (uint32(id >> 224) == Chain || !isLocalFamily(id, Node)) revert InvalidId();
-        return address(uint160(id));
-    }
-
-    /// @notice Extract the contract address from a local host ID.
-    /// Reverts if `id` does not match the local host base.
-    /// @param id Host node ID.
-    /// @return Host contract address in the lower 160 bits of `id`.
-    function hostAddr(uint id) internal view returns (address) {
-        if (!matchesBase(bytes32(id), toLocalBase(Host))) revert InvalidId();
-        return address(uint160(id));
-    }
-}
-
-/// @title Selectors
-/// @notice ABI-selector derivation helpers for command, peer, and query dispatch.
-library Selectors {
-    /// @dev ABI argument encoding for command entry points: `((bytes32,bytes,bytes))`.
-    string constant CommandArgs = "((bytes32,bytes,bytes))";
-    /// @dev ABI argument encoding for peer entry points: `(bytes)`.
-    string constant PeerArgs = "(bytes)";
-    /// @dev ABI argument encoding for query entry points: `(bytes)`.
-    string constant QueryArgs = "(bytes)";
-    /// @dev ABI argument encoding for guard action entry points: `(bytes)`.
-    string constant GuardArgs = "(bytes)";
+    /// @dev Preimage format/hash tag for keccak256-derived opaque IDs.
+    uint8 constant Keccak = 0x01;
 
-    /// @notice Derive the 4-byte ABI selector for a named command.
-    /// The selector is `keccak256(name ++ CommandArgs)[0:4]`.
-    /// @param name Command function name (without arguments).
-    /// @return 4-byte selector.
-    function command(string memory name) internal pure returns (bytes4) {
-        return bytes4(keccak256(bytes.concat(bytes(name), bytes(CommandArgs))));
+    /// @notice Return true if `id` is opaque.
+    function isOpaque(bytes32 id) internal pure returns (bool) {
+        return uint8(uint(id) >> 248) == 0;
     }
 
-    /// @notice Derive the 4-byte ABI selector for a named peer.
-    /// The selector is `keccak256(name ++ PeerArgs)[0:4]`.
-    /// @param name Peer function name (without arguments).
-    /// @return 4-byte selector.
-    function peer(string memory name) internal pure returns (bytes4) {
-        return bytes4(keccak256(bytes.concat(bytes(name), bytes(PeerArgs))));
+    /// @notice Assert that `value` is opaque and return it unchanged.
+    /// @param value ID to validate.
+    /// @return id The same `value` if it is opaque.
+    function opaque(bytes32 value) internal pure returns (bytes32 id) {
+        if (!isOpaque(value)) revert InvalidId();
+        return value;
     }
 
-    /// @notice Derive the 4-byte ABI selector for a named query.
-    /// The selector is `keccak256(name ++ QueryArgs)[0:4]`.
-    /// @param name Query function name (without arguments).
-    /// @return 4-byte selector.
-    function query(string memory name) internal pure returns (bytes4) {
-        return bytes4(keccak256(bytes.concat(bytes(name), bytes(QueryArgs))));
+    /// @notice Derive an opaque ID from a keccak preimage.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return id `0x00 || bytes31(keccak256(preimage))`.
+    function toKeccak(bytes memory preimage) internal pure returns (bytes32 id) {
+        if (preimage.length == 0 || uint8(preimage[0]) != Keccak) revert InvalidPreimage();
+        return bytes32(uint(keccak256(preimage)) >> 8);
     }
 
-    /// @notice Derive the 4-byte ABI selector for a named guard action.
-    /// The selector is `keccak256(name ++ GuardArgs)[0:4]`.
-    /// @param name Guard action function name (without arguments).
-    /// @return 4-byte selector.
-    function guard(string memory name) internal pure returns (bytes4) {
-        return bytes4(keccak256(bytes.concat(bytes(name), bytes(GuardArgs))));
+    /// @notice Assert that `value` matches the opaque keccak ID for `preimage`.
+    /// @param value Opaque ID to validate.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return id The same `value` if it matches.
+    function matchKeccak(bytes32 value, bytes memory preimage) internal pure returns (bytes32 id) {
+        if (value != toKeccak(preimage)) revert InvalidId();
+        return value;
     }
 }

package/utils/Layout.sol

@@ -7,23 +7,21 @@ pragma solidity ^0.8.33;
 ///
 /// IDs are structured as:
 ///   `[uint32 type][uint32 chainid][192-bit payload]`
-/// where `type` is `[uint8 vm][uint8 width][uint8 category][uint8 subtype]`.
+/// where `type` is `[uint16 representation][uint8 category][uint8 subtype]`.
+///
+/// Values whose first byte is zero are opaque IDs:
+///   `[0x00][bytes31 truncated hash]`
+/// They require lookup or witness data when the native preimage is needed.
+/// Opaque preimages start with a one-byte format/hash tag. `0x01` means the ID
+/// is `0x00 || bytes31(keccak256(preimage))`; remaining bytes are host/domain-specific.
+/// Values whose first byte is nonzero follow the structured layout above.
 library Layout {
     // -------------------------------------------------------------------------
-    // VM and data-width tags (top 2 bytes of the ID type field)
+    // Representation tags (top 2 bytes of the ID type field)
     // -------------------------------------------------------------------------
 
-    /// @dev EVM-compatible value; payloads are built around 20-byte addresses.
-    uint8 constant Evm = 0x01;
-    /// @dev 32-byte ID; no paired metadata word is required.
-    uint8 constant Width32 = 0x20;
-    /// @dev 64-byte ID; a paired metadata word completes the identity.
-    uint8 constant Width64 = 0x40;
-
-    /// @dev 32-byte EVM-compatible value; lower 20 bytes hold an address.
-    uint16 constant Evm32 = (uint16(Evm) << 8) | uint16(Width32);
-    /// @dev 64-byte EVM-compatible value; used when a paired metadata word completes the identity.
-    uint16 constant Evm64 = (uint16(Evm) << 8) | uint16(Width64);
+    /// @dev EVM-compatible ID; lower 20 payload bytes hold an address when present.
+    uint16 constant Evm = 0x0120;
 
     // -------------------------------------------------------------------------
     // Category tags (uint8, third byte of the ID type field)
@@ -71,8 +69,4 @@ library Layout {
     uint8 constant Native = 0x01;
     /// @dev ERC-20 fungible token; lower 20 bytes of the ID hold the contract address.
     uint8 constant Erc20 = 0x02;
-    /// @dev ERC-721 non-fungible token; lower 20 bytes of the ID hold the collection address.
-    uint8 constant Erc721 = 0x03;
-    /// @dev ERC-1155 multi-token asset; lower 20 bytes of the ID hold the collection address.
-    uint8 constant Erc1155 = 0x04;
 }

package/utils/Nodes.sol

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Layout} from "./Layout.sol";
+import {Ids} from "./Ids.sol";
+import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
+
+/// @title Nodes
+/// @notice Encoding and decoding helpers for 256-bit node identifiers.
+///
+/// Node IDs share a common layout:
+///   - bits [255:224] — 4-byte type prefix (`Host`, `Command`, or `Peer`)
+///   - bits [223:192] — current `block.chainid` (makes IDs chain-local)
+///   - bits [191:160] — 4-byte ABI selector (commands and peers only)
+///   - bits [159:0]   — 160-bit EVM contract address
+///
+/// If the first byte is zero, the node is an opaque
+/// `0x00 || bytes31(hash)` ID. The callable target must be resolved by lookup
+/// or witness data before dispatch.
+///
+/// The helpers in this library validate and deconstruct structured node IDs.
+library Nodes {
+    /// @dev Thrown when an ID does not match the expected node type or chain.
+    error InvalidId();
+
+    /// @dev 24-bit family tag shared by all node types (Evm + Node category).
+    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(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);
+    /// @dev Full 4-byte type prefix for host nodes.
+    uint32 constant Host = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Host);
+    /// @dev Full 4-byte type prefix for command nodes.
+    uint32 constant Command = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Command);
+    /// @dev Full 4-byte type prefix for peer nodes.
+    uint32 constant Peer = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Peer);
+    /// @dev Full 4-byte type prefix for query nodes.
+    uint32 constant Query = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Query);
+    /// @dev Full 4-byte type prefix for guard action nodes.
+    uint32 constant Guard = (uint32(Layout.Evm) << 16) | (uint32(Layout.Node) << 8) | uint32(Layout.Guard);
+
+    /// @notice Return true if `node` is a host node ID.
+    function isHost(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Host;
+    }
+
+    /// @notice Return true if `node` is a command node ID.
+    function isCommand(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Command;
+    }
+
+    /// @notice Return true if `node` is a peer node ID.
+    function isPeer(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == Peer;
+    }
+
+    /// @notice Return true if `node` is a query node ID.
+    function isQuery(uint node) internal pure returns (bool) {
+        return uint32(node >> 224) == 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;
+    }
+
+    /// @notice Return true if `node` belongs to the EVM node family.
+    function isEvm(uint node) internal pure returns (bool) {
+        return isFamily(node, Family);
+    }
+
+    /// @notice Return true if `node` is opaque.
+    function isOpaque(uint node) internal pure returns (bool) {
+        return Ids.isOpaque(bytes32(node));
+    }
+
+    /// @notice Return true if `node` belongs to the EVM node family on the current chain.
+    function isLocal(uint node) internal view returns (bool) {
+        return isEvm(node) && uint32(node >> 192) == block.chainid;
+    }
+
+    /// @notice Assert that `value` is a host node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a host node.
+    function host(uint value) internal pure returns (uint node) {
+        if (!isHost(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a command node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a command node.
+    function command(uint value) internal pure returns (uint node) {
+        if (!isCommand(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a peer node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a peer node.
+    function peer(uint value) internal pure returns (uint node) {
+        if (!isPeer(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a query node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a query node.
+    function query(uint value) internal pure returns (uint node) {
+        if (!isQuery(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a guard action node ID and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is a guard action node.
+    function guard(uint value) internal pure returns (uint node) {
+        if (!isGuard(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` belongs to the EVM node family and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is an EVM node.
+    function evm(uint value) internal pure returns (uint node) {
+        if (!isEvm(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` is an opaque node and return it unchanged.
+    /// @param value Node ID to validate.
+    /// @return node The same `value` if it is opaque.
+    function opaque(uint value) internal pure returns (uint node) {
+        if (!Ids.isOpaque(bytes32(value))) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `value` belongs to the EVM node family on the current chain and return it as a node.
+    /// @param value Value to validate.
+    /// @return node The same `value` if it is local.
+    function local(uint value) internal view returns (uint node) {
+        if (!isLocal(value)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Assert that `node` is a command ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte command selector stored in bits [191:160].
+    function commandSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(command(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a peer ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte peer selector stored in bits [191:160].
+    function peerSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(peer(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a query ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte query selector stored in bits [191:160].
+    function querySelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(query(node) >> 160));
+    }
+
+    /// @notice Assert that `node` is a guard action ID and return its embedded ABI selector.
+    /// @param node Node ID to validate.
+    /// @return selector 4-byte guard selector stored in bits [191:160].
+    function guardSelector(uint node) internal pure returns (bytes4 selector) {
+        return bytes4(uint32(guard(node) >> 160));
+    }
+
+    /// @notice Assert that `value` is the host node of `target` on the current chain.
+    /// @param value Value to validate.
+    /// @param target Expected host contract address.
+    /// @return node The same `value` if it matches `target`.
+    function matchHost(uint value, address target) internal view returns (uint node) {
+        if (value != toHost(target)) revert InvalidId();
+        return value;
+    }
+
+    /// @notice Build the chain node ID for the current chain.
+    /// @return node Chain node ID with zero selector and `address(0)` payload.
+    function localChain() internal view returns (uint node) {
+        return toLocalBase(Chain);
+    }
+
+    /// @notice Build a chain-local host ID for `target`.
+    /// @param target Host contract address.
+    /// @return node Host node ID on the current chain.
+    function toHost(address target) internal view returns (uint node) {
+        return toLocalBase(Host) | uint(uint160(target));
+    }
+
+    /// @notice Build a chain-local command ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the command entry point.
+    /// @param target Command contract address.
+    /// @return node Command node ID embedding both the selector and address.
+    function toCommand(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Command) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local peer ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the peer entry point.
+    /// @param target Peer contract address.
+    /// @return node Peer node ID embedding both the selector and address.
+    function toPeer(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Peer) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local query ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the query entry point.
+    /// @param target Query contract address.
+    /// @return node Query node ID embedding both the selector and address.
+    function toQuery(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Query) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Build a chain-local guard action ID for the given selector and contract.
+    /// @param selector 4-byte ABI selector of the guard action entry point.
+    /// @param target Guard action contract address.
+    /// @return node Guard action node ID embedding both the selector and address.
+    function toGuard(bytes4 selector, address target) internal view returns (uint node) {
+        node = toLocalBase(Guard) | uint(uint160(target));
+        node |= uint(uint32(selector)) << 160;
+    }
+
+    /// @notice Derive an opaque node ID from a keccak preimage.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return node `0x00 || bytes31(keccak256(preimage))`.
+    function toKeccak(bytes memory preimage) internal pure returns (uint node) {
+        return uint(Ids.toKeccak(preimage));
+    }
+
+    /// @notice Assert that `node` matches the opaque keccak ID for `preimage`.
+    /// @param node Opaque node ID to validate.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return The same `node` value if it matches.
+    function matchKeccak(uint node, bytes memory preimage) internal pure returns (uint) {
+        if (node != uint(Ids.toKeccak(preimage))) revert InvalidId();
+        return node;
+    }
+
+    /// @notice Extract the contract address from any local node ID.
+    /// Reverts if `node` does not belong to the local node family or carries `address(0)`.
+    /// @param node Node ID.
+    /// @return Contract address in the lower 160 bits of `node`.
+    function addr(uint node) internal view returns (address) {
+        return ensureAddr(address(uint160(local(node))));
+    }
+
+    /// @notice Extract the contract address from a local host ID.
+    /// Reverts if `node` does not match the local host base or carries `address(0)`.
+    /// @param node Host node ID.
+    /// @return Host contract address in the lower 160 bits of `node`.
+    function hostAddr(uint node) internal view returns (address) {
+        if (!matchesBase(bytes32(node), toLocalBase(Host))) revert InvalidId();
+        return ensureAddr(address(uint160(node)));
+    }
+}

package/utils/Utils.sol

@@ -8,6 +8,8 @@ uint16 constant MAX_BPS = 10_000;
 error ValueOverflow();
 /// @dev Thrown by `divisible` when `n` is not evenly divisible by `divisor`.
 error NotDivisible();
+/// @dev Thrown when an ID claims to carry an address but the embedded address is zero.
+error ZeroAddress();
 
 /// @notice Assert that `value` fits in uint8 and return it unchanged.
 function max8(uint value) pure returns (uint) {
@@ -92,6 +94,12 @@ function addrOr(address addr, address or) pure returns (address) {
     return addr == address(0) ? or : addr;
 }
 
+/// @notice Assert that `addr` is non-zero and return it unchanged.
+function ensureAddr(address addr) pure returns (address) {
+    if (addr == address(0)) revert ZeroAddress();
+    return addr;
+}
+
 /// @notice Convert a signed integer to its 32-byte two's-complement representation.
 function intToBytes32(int value) pure returns (bytes32) {
     return bytes32(uint(value));
@@ -136,20 +144,12 @@ function retryTicket(bytes32 account, bytes calldata state) pure returns (bytes3
 
 /// @notice Build the chain-local base prefix for a 256-bit ID.
 /// Embeds the current `block.chainid` so IDs are not portable across chains.
-/// @param prefix Four-byte type tag (e.g. `Ids.Host`, `Ids.Command`).
+/// @param prefix Four-byte type tag (e.g. `Nodes.Host`, `Nodes.Command`).
 /// @return Base value with the type tag in bits [255:224] and chainid in bits [223:192].
 function toLocalBase(uint32 prefix) view returns (uint) {
     return (uint(prefix) << 224) | (uint(max32(block.chainid)) << 192);
 }
 
-/// @notice Build the chain-local family prefix for a 256-bit ID.
-/// Uses a 24-bit family tag (the top 3 bytes of the type field).
-/// @param family Three-byte family tag.
-/// @return Family prefix with the family in bits [255:232] and chainid in bits [223:192].
-function toLocalFamily(uint24 family) view returns (uint) {
-    return (uint(family) << 232) | (uint(max32(block.chainid)) << 192);
-}
-
 /// @notice Build a chain-unspecified base prefix (no chainid embedded).
 /// Used for IDs that must be portable across chains (e.g. user accounts).
 /// @param prefix Four-byte type tag.
@@ -167,21 +167,6 @@ function isFamily(uint value, uint24 family) pure returns (bool) {
     return uint24(value >> 232) == family;
 }
 
-/// @notice Check whether `value` was created on the current chain.
-/// @param value ID to test.
-/// @return True if bits [223:192] of `value` equal `block.chainid`.
-function isLocalChain(uint value) view returns (bool) {
-    return uint32(value >> 192) == block.chainid;
-}
-
-/// @notice Check whether `value` belongs to the given family and was created on the current chain.
-/// @param value ID to test.
-/// @param family Expected 24-bit family tag.
-/// @return True if both the family and chainid fields match.
-function isLocalFamily(uint value, uint24 family) view returns (bool) {
-    return isFamily(value, family) && isLocalChain(value);
-}
-
 /// @notice Check whether two IDs share the same 64-bit base (type tag + chainid).
 /// Used to verify that an ID matches a locally-constructed base without comparing
 /// the lower 192-bit payload.