@rootzero/contracts 1.4.0 → 1.6.0

package/utils/Accounts.sol

@@ -2,7 +2,8 @@
 pragma solidity ^0.8.33;
 
 import {Layout} from "./Layout.sol";
-import {isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
+import {Ids} from "./Ids.sol";
+import {ensureAddr, isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
 
 /// @title Accounts
 /// @notice Encoding and decoding helpers for 256-bit account identifiers.
@@ -11,18 +12,24 @@ import {isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
 ///   - `Admin`    — chain-local EVM address in bits [191:32]
 ///   - `Guardian` — chain-local EVM address in bits [191:32]
 ///   - `User`     — chain-agnostic EVM address in bits [191:32]
+///
+/// If the first byte is zero, the account is an opaque
+/// `0x00 || bytes31(hash)` ID. The full account identity must be supplied by
+/// lookup or witness data when native account metadata is needed.
+///
+/// The helpers in this library validate and deconstruct structured account IDs.
 library Accounts {
     /// @dev Thrown when an account ID does not belong to the EVM family.
     error InvalidAccount();
 
     /// @dev 24-bit family tag shared by all EVM-backed account types.
-    uint24 constant Family = (uint24(Layout.Evm32) << 8) | uint24(Layout.Account);
+    uint24 constant Family = (uint24(Layout.Evm) << 8) | uint24(Layout.Account);
     /// @dev Full 4-byte type prefix for admin accounts (chain-local EVM address).
-    uint32 constant Admin = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Admin);
+    uint32 constant Admin = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Admin);
     /// @dev Full 4-byte type prefix for guardian accounts (chain-local EVM address).
-    uint32 constant Guardian = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Guardian);
+    uint32 constant Guardian = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.Guardian);
     /// @dev Full 4-byte type prefix for user accounts (chain-agnostic EVM address).
-    uint32 constant User = (uint32(Layout.Evm32) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
+    uint32 constant User = (uint32(Layout.Evm) << 16) | (uint32(Layout.Account) << 8) | uint32(Layout.User);
 
     /// @notice Extract the 4-byte type prefix from an account ID.
     /// @param account Account identifier.
@@ -31,9 +38,14 @@ library Accounts {
         return uint32(uint(account) >> 224);
     }
 
-    /// @notice Return true if `account` uses the Account category tag in the type field.
-    function isAccount(bytes32 account) internal pure returns (bool) {
-        return uint8(uint(account) >> 232) == Layout.Account;
+    /// @notice Return true if `account` belongs to the EVM account family.
+    function isEvm(bytes32 account) internal pure returns (bool) {
+        return isFamily(uint(account), Family);
+    }
+
+    /// @notice Return true if `account` is opaque.
+    function isOpaque(bytes32 account) internal pure returns (bool) {
+        return Ids.isOpaque(account);
     }
 
     /// @notice Return true if `account` is an admin account.
@@ -51,82 +63,88 @@ library Accounts {
         return prefix(account) == User;
     }
 
-    /// @notice Assert that `input` is an account and return it unchanged.
-    /// @param input Account identifier to validate.
-    /// @return account The same `input` if it is an account.
-    function ensure(bytes32 input) internal pure returns (bytes32 account) {
-        if (!isAccount(input)) revert InvalidAccount();
-        return input;
+    /// @notice Assert that `value` belongs to the EVM account family and return it unchanged.
+    /// @param value Account identifier to validate.
+    /// @return account The same `value` if it is an EVM account.
+    function evm(bytes32 value) internal pure returns (bytes32 account) {
+        if (!isEvm(value)) revert InvalidAccount();
+        return value;
     }
 
-    /// @notice Assert that `input` is an admin account and return it unchanged.
-    /// @param input Account identifier to validate.
-    /// @return account The same `input` if it is an admin account.
-    function admin(bytes32 input) internal pure returns (bytes32 account) {
-        if (!isAdmin(input)) revert InvalidAccount();
-        return input;
+    /// @notice Assert that `value` is an opaque account and return it unchanged.
+    /// @param value Account identifier to validate.
+    /// @return account The same `value` if it is opaque.
+    function opaque(bytes32 value) internal pure returns (bytes32 account) {
+        if (!Ids.isOpaque(value)) revert InvalidAccount();
+        return value;
     }
 
-    /// @notice Assert that `input` is a guardian account and return it unchanged.
-    /// @param input Account identifier to validate.
-    /// @return account The same `input` if it is a guardian account.
-    function guardian(bytes32 input) internal pure returns (bytes32 account) {
-        if (!isGuardian(input)) revert InvalidAccount();
-        return input;
+    /// @notice Assert that `value` is an admin account and return it unchanged.
+    /// @param value Account identifier to validate.
+    /// @return account The same `value` if it is an admin account.
+    function admin(bytes32 value) internal pure returns (bytes32 account) {
+        if (!isAdmin(value)) revert InvalidAccount();
+        return value;
     }
 
-    /// @notice Assert that `input` is a user account and return it unchanged.
-    /// @param input Account identifier to validate.
-    /// @return account The same `input` if it is a user account.
-    function user(bytes32 input) internal pure returns (bytes32 account) {
-        if (!isUser(input)) revert InvalidAccount();
-        return input;
+    /// @notice Assert that `value` is a guardian account and return it unchanged.
+    /// @param value Account identifier to validate.
+    /// @return account The same `value` if it is a guardian account.
+    function guardian(bytes32 value) internal pure returns (bytes32 account) {
+        if (!isGuardian(value)) revert InvalidAccount();
+        return value;
+    }
+
+    /// @notice Assert that `value` is a user account and return it unchanged.
+    /// @param value Account identifier to validate.
+    /// @return account The same `value` if it is a user account.
+    function user(bytes32 value) internal pure returns (bytes32 account) {
+        if (!isUser(value)) revert InvalidAccount();
+        return value;
     }
 
     /// @notice Encode an EVM address as a chain-local admin account ID.
-    /// @param addr EVM address to embed.
+    /// @param account EVM address to embed.
     /// @return Admin account ID bound to the current chain.
-    function toAdmin(address addr) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Admin) | (uint(uint160(addr)) << 32));
+    function toAdmin(address account) internal view returns (bytes32) {
+        return bytes32(toLocalBase(Admin) | (uint(uint160(account)) << 32));
     }
 
     /// @notice Encode an EVM address as a chain-local guardian account ID.
-    /// @param addr EVM address to embed.
+    /// @param account EVM address to embed.
     /// @return Guardian account ID bound to the current chain.
-    function toGuardian(address addr) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Guardian) | (uint(uint160(addr)) << 32));
+    function toGuardian(address account) internal view returns (bytes32) {
+        return bytes32(toLocalBase(Guardian) | (uint(uint160(account)) << 32));
     }
 
     /// @notice Encode an EVM address as a chain-agnostic user account ID.
-    /// @param addr EVM address to embed.
+    /// @param account EVM address to embed.
     /// @return User account ID without a chain binding.
-    function toUser(address addr) internal pure returns (bytes32) {
-        return bytes32(toUnspecifiedBase(User) | (uint(uint160(addr)) << 32));
+    function toUser(address account) internal pure returns (bytes32) {
+        return bytes32(toUnspecifiedBase(User) | (uint(uint160(account)) << 32));
     }
 
-    /// @notice Assert that `account` belongs to the EVM account family and return it unchanged.
-    /// @param account Account ID to validate.
-    /// @return The same `account` value if valid.
-    function ensureEvm(bytes32 account) internal pure returns (bytes32) {
-        if (!isFamily(uint(account), Family)) {
-            revert InvalidAccount();
-        }
-        return account;
+    /// @notice Derive an opaque account ID from a keccak preimage.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return account `0x00 || bytes31(keccak256(preimage))`.
+    function toKeccak(bytes memory preimage) internal pure returns (bytes32 account) {
+        return Ids.toKeccak(preimage);
     }
 
-    /// @notice Assert that `account` is not an admin account and return it unchanged.
-    /// @param account Account ID to validate.
-    /// @return The same `account` value if valid.
-    function ensureNotAdmin(bytes32 account) internal pure returns (bytes32) {
-        if (isAdmin(account)) revert InvalidAccount();
+    /// @notice Assert that `account` matches the opaque keccak ID for `preimage`.
+    /// @param account Opaque account ID to validate.
+    /// @param preimage Preimage whose first byte is `0x01`.
+    /// @return The same `account` value if it matches.
+    function matchKeccak(bytes32 account, bytes memory preimage) internal pure returns (bytes32) {
+        if (account != Ids.toKeccak(preimage)) revert InvalidAccount();
         return account;
     }
 
-    /// @notice Extract the EVM address embedded in an EVM-family account ID.
+    /// @notice Extract the address embedded in an EVM-family account ID.
     /// Reverts if `account` is not an EVM-family account.
     /// @param account EVM-family account ID.
-    /// @return Embedded EVM address (bits [191:32] of the ID).
-    function addrEvm(bytes32 account) internal pure returns (address) {
-        return address(uint160(uint(ensureEvm(account)) >> 32));
+    /// @return Embedded address (bits [191:32] of the ID).
+    function addr(bytes32 account) internal pure returns (address) {
+        return ensureAddr(address(uint160(uint(evm(account)) >> 32)));
     }
 }

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