@rootzero/contracts 1.3.0 → 1.5.0

package/utils/Assets.sol

@@ -2,7 +2,8 @@
 pragma solidity ^0.8.33;
 
 import {Layout} from "./Layout.sol";
-import {matchesBase, toLocalBase} from "./Utils.sol";
+import {Ids} from "./Ids.sol";
+import {ensureAddr, isFamily, matchesBase, toLocalBase} from "./Utils.sol";
 
 /// @title Assets
 /// @notice Encoding and decoding helpers for 256-bit asset identifiers.
@@ -10,8 +11,12 @@ import {matchesBase, toLocalBase} from "./Utils.sol";
 /// Asset IDs embed a 4-byte type tag in bits [255:224]:
 ///   - `Native` - native chain coin/token; no address payload
 ///   - `Erc20` - ERC-20 token; contract address in bits [191:32]
-///   - `Erc721` - ERC-721 collection; collection address in bits [191:32]
-///   - `Erc1155` - ERC-1155 collection; collection address in bits [191:32]
+///
+/// If the first byte is zero, the asset is an opaque
+/// `0x00 || bytes31(hash)` ID. The full asset metadata must be supplied by
+/// lookup or witness data when native token handling needs it.
+///
+/// The helpers in this library validate and deconstruct structured asset IDs.
 ///
 /// All asset IDs are chain-local (include `block.chainid` in bits [223:192]).
 library Assets {
@@ -20,28 +25,21 @@ library Assets {
     /// @dev Thrown when an asset is not authorized for the requested operation.
     error UnauthorizedAsset();
 
+    /// @dev 24-bit family tag shared by all EVM-backed asset types.
+    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Asset);
     /// @dev Full 4-byte type prefix for the native chain coin/token asset.
-    uint32 constant Native = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Native);
+    uint32 constant Native = (uint32(Layout.Evm) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Native);
     /// @dev Full 4-byte type prefix for ERC-20 assets.
-    uint32 constant Erc20 = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc20);
-    /// @dev Full 4-byte type prefix for ERC-721 assets.
-    uint32 constant Erc721 = (uint32(Layout.Evm64) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc721);
-    /// @dev Full 4-byte type prefix for ERC-1155 assets.
-    uint32 constant Erc1155 = (uint32(Layout.Evm64) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc1155);
-
-    /// @notice Return true if `asset` uses the Asset category tag in the type field.
-    function isAsset(bytes32 asset) internal pure returns (bool) {
-        return uint8(uint(asset) >> 232) == Layout.Asset;
-    }
+    uint32 constant Erc20 = (uint32(Layout.Evm) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc20);
 
-    /// @notice Return true if `asset` uses a 32-byte asset layout with no metadata identity.
-    function is32(bytes32 asset) internal pure returns (bool) {
-        return isAsset(asset) && uint8(uint(asset) >> 240) == Layout.Width32;
+    /// @notice Return true if `asset` belongs to the EVM asset family.
+    function isEvm(bytes32 asset) internal pure returns (bool) {
+        return isFamily(uint(asset), Family);
     }
 
-    /// @notice Return true if `asset` uses a 64-byte asset layout with metadata-backed identity.
-    function is64(bytes32 asset) internal pure returns (bool) {
-        return isAsset(asset) && uint8(uint(asset) >> 240) == Layout.Width64;
+    /// @notice Return true if `asset` is opaque.
+    function isOpaque(bytes32 asset) internal pure returns (bool) {
+        return Ids.isOpaque(asset);
     }
 
     /// @notice Return true if `asset` is the local native chain coin/token asset.
@@ -54,46 +52,36 @@ library Assets {
         return matchesBase(asset, toLocalBase(Erc20));
     }
 
-    /// @notice Return true if `asset` is a local ERC-721 asset.
-    function isErc721(bytes32 asset) internal view returns (bool) {
-        return matchesBase(asset, toLocalBase(Erc721));
-    }
-
-    /// @notice Return true if `asset` is a local ERC-1155 asset.
-    function isErc1155(bytes32 asset) internal view returns (bool) {
-        return matchesBase(asset, toLocalBase(Erc1155));
+    /// @notice Assert that `value` belongs to the EVM asset family and return it unchanged.
+    /// @param value Asset identifier to validate.
+    /// @return asset The same `value` if it is an EVM asset.
+    function evm(bytes32 value) internal pure returns (bytes32 asset) {
+        if (!isEvm(value)) revert InvalidAsset();
+        return value;
     }
 
-    /// @notice Assert that `input` is the local native chain coin/token asset and return it unchanged.
-    /// @param input Asset identifier to validate.
-    /// @return asset The same `input` if it is the local native asset.
-    function native(bytes32 input) internal view returns (bytes32 asset) {
-        if (!isNative(input)) revert InvalidAsset();
-        return input;
+    /// @notice Assert that `value` is an opaque asset and return it unchanged.
+    /// @param value Asset identifier to validate.
+    /// @return asset The same `value` if it is opaque.
+    function opaque(bytes32 value) internal pure returns (bytes32 asset) {
+        if (!Ids.isOpaque(value)) revert InvalidAsset();
+        return value;
     }
 
-    /// @notice Assert that `input` is a local ERC-20 asset and return it unchanged.
-    /// @param input Asset identifier to validate.
-    /// @return asset The same `input` if it is a local ERC-20 asset.
-    function erc20(bytes32 input) internal view returns (bytes32 asset) {
-        if (!isErc20(input)) revert InvalidAsset();
-        return input;
+    /// @notice Assert that `value` is the local native chain coin/token asset and return it unchanged.
+    /// @param value Asset identifier to validate.
+    /// @return asset The same `value` if it is the local native asset.
+    function native(bytes32 value) internal view returns (bytes32 asset) {
+        if (!isNative(value)) revert InvalidAsset();
+        return value;
     }
 
-    /// @notice Assert that `input` is a local ERC-721 asset and return it unchanged.
-    /// @param input Asset identifier to validate.
-    /// @return asset The same `input` if it is a local ERC-721 asset.
-    function erc721(bytes32 input) internal view returns (bytes32 asset) {
-        if (!isErc721(input)) revert InvalidAsset();
-        return input;
-    }
-
-    /// @notice Assert that `input` is a local ERC-1155 asset and return it unchanged.
-    /// @param input Asset identifier to validate.
-    /// @return asset The same `input` if it is a local ERC-1155 asset.
-    function erc1155(bytes32 input) internal view returns (bytes32 asset) {
-        if (!isErc1155(input)) revert InvalidAsset();
-        return input;
+    /// @notice Assert that `value` is a local ERC-20 asset and return it unchanged.
+    /// @param value Asset identifier to validate.
+    /// @return asset The same `value` if it is a local ERC-20 asset.
+    function erc20(bytes32 value) internal view returns (bytes32 asset) {
+        if (!isErc20(value)) revert InvalidAsset();
+        return value;
     }
 
     /// @notice Create a chain-local native coin/token asset ID.
@@ -109,18 +97,20 @@ library Assets {
         return bytes32(toLocalBase(Erc20) | (uint(uint160(addr)) << 32));
     }
 
-    /// @notice Create a chain-local ERC-721 asset ID for `collection`.
-    /// @param collection ERC-721 collection contract address.
-    /// @return Asset ID with `collection` embedded in bits [191:32].
-    function toErc721(address collection) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Erc721) | (uint(uint160(collection)) << 32));
+    /// @notice Derive an opaque asset ID from a keccak preimage.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return asset `0x00 || bytes31(keccak256(preimage))`.
+    function toKeccak(bytes memory preimage) internal pure returns (bytes32 asset) {
+        return Ids.toKeccak(preimage);
     }
 
-    /// @notice Create a chain-local ERC-1155 asset ID for `collection`.
-    /// @param collection ERC-1155 collection contract address.
-    /// @return Asset ID with `collection` embedded in bits [191:32].
-    function toErc1155(address collection) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Erc1155) | (uint(uint160(collection)) << 32));
+    /// @notice Assert that `asset` matches the opaque keccak ID for `preimage`.
+    /// @param asset Opaque asset ID to validate.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return The same `asset` value if it matches.
+    function matchKeccak(bytes32 asset, bytes memory preimage) internal pure returns (bytes32) {
+        if (asset != Ids.toKeccak(preimage)) revert InvalidAsset();
+        return asset;
     }
 
     /// @notice Extract the ERC-20 contract address from an asset ID.
@@ -128,7 +118,7 @@ library Assets {
     /// @param asset ERC-20 asset identifier.
     /// @return Token contract address embedded in bits [191:32].
     function erc20Addr(bytes32 asset) internal view returns (address) {
-        return address(uint160(uint(erc20(asset)) >> 32));
+        return ensureAddr(address(uint160(uint(erc20(asset)) >> 32)));
     }
 
     /// @notice Assert that `asset` is a local ERC-20 for `token` and return it unchanged.
@@ -141,56 +131,6 @@ library Assets {
         return asset;
     }
 
-    /// @notice Extract the ERC-721 collection address from an asset ID.
-    /// Reverts if `asset` is not a local ERC-721 asset.
-    /// @param asset ERC-721 asset identifier.
-    /// @return Collection contract address embedded in bits [191:32].
-    function erc721Collection(bytes32 asset) internal view returns (address) {
-        return address(uint160(uint(erc721(asset)) >> 32));
-    }
-
-    /// @notice Assert that `asset` is a local ERC-721 for `collection` and return it unchanged.
-    /// Reverts if `asset` is not a local ERC-721 asset or if its collection address differs.
-    /// @param asset ERC-721 asset identifier.
-    /// @param collection Expected ERC-721 collection address.
-    /// @return The same `asset` value if valid.
-    function matchErc721(bytes32 asset, address collection) internal view returns (bytes32) {
-        if (erc721Collection(asset) != collection) revert InvalidAsset();
-        return asset;
-    }
-
-    /// @notice Extract the ERC-1155 collection address from an asset ID.
-    /// Reverts if `asset` is not a local ERC-1155 asset.
-    /// @param asset ERC-1155 asset identifier.
-    /// @return Collection contract address embedded in bits [191:32].
-    function erc1155Collection(bytes32 asset) internal view returns (address) {
-        return address(uint160(uint(erc1155(asset)) >> 32));
-    }
-
-    /// @notice Assert that `asset` is a local ERC-1155 for `collection` and return it unchanged.
-    /// Reverts if `asset` is not a local ERC-1155 asset or if its collection address differs.
-    /// @param asset ERC-1155 asset identifier.
-    /// @param collection Expected ERC-1155 collection address.
-    /// @return The same `asset` value if valid.
-    function matchErc1155(bytes32 asset, address collection) internal view returns (bytes32) {
-        if (erc1155Collection(asset) != collection) revert InvalidAsset();
-        return asset;
-    }
-
-    /// @notice Derive a storage slot for an (asset, meta) pair.
-    /// For 32-byte assets (no meta), the slot is the asset ID itself.
-    /// For assets with metadata (e.g. ERC-721 or ERC-1155 token IDs), the slot is
-    /// `keccak256(asset ++ meta)`.
-    /// Reverts only if `asset` is zero.
-    /// For 32-byte assets, `meta` is ignored and does not affect the derived slot.
-    /// @param asset Asset identifier.
-    /// @param meta Asset metadata slot (e.g. token ID context).
-    /// @return Storage slot for the (asset, meta) combination.
-    function slot(bytes32 asset, bytes32 meta) internal pure returns (bytes32) {
-        if (is32(asset)) return asset;
-        if (meta == 0 || !is64(asset)) revert InvalidAsset();
-        return keccak256(bytes.concat(asset, meta));
-    }
 }
 
 /// @title Amounts

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;
 }