@rootzero/contracts 0.7.2 → 0.8.0

package/queries/Assets.sol

@@ -10,24 +10,26 @@ using Cursors for Cur;
 string constant NAME = "isAllowedAsset";
 string constant OUTPUT = "response(uint allowed)";
 
+abstract contract IsAllowedAssetHook {
+    /// @notice Resolve whether one asset tuple is allowed.
+    /// Concrete implementations define the allowlist policy.
+    /// @param asset Requested asset identifier.
+    /// @param meta Requested asset metadata slot.
+    /// @return allowed Whether the asset tuple is allowed.
+    function isAllowedAsset(bytes32 asset, bytes32 meta) internal view virtual returns (bool allowed);
+}
+
 /// @title IsAllowedAsset
 /// @notice Rootzero query that checks whether one or more `(asset, meta)` tuples are allowed.
 /// The request is a run of `ASSET` blocks.
 /// The response returns one `RESPONSE` block per query entry, preserving request order.
-abstract contract IsAllowedAsset is QueryBase {
+abstract contract IsAllowedAsset is QueryBase, IsAllowedAssetHook {
     uint public immutable isAllowedAssetId = queryId(NAME);
 
     constructor() {
         emit Query(host, NAME, Schemas.Asset, OUTPUT, isAllowedAssetId);
     }
 
-    /// @notice Resolve whether one asset tuple is allowed.
-    /// Concrete implementations define the allowlist policy.
-    /// @param asset Requested asset identifier.
-    /// @param meta Requested asset metadata slot.
-    /// @return allowed Whether the asset tuple is allowed.
-    function isAllowedAsset(bytes32 asset, bytes32 meta) internal view virtual returns (bool allowed);
-
     /// @notice Resolve allowlist status for a run of requested `(asset, meta)` tuples.
     /// @param request Block-stream request consisting of `asset(asset, meta)*`.
     /// @return Block-stream response containing one `response(allowed)` per asset block.

package/queries/Balances.sol

@@ -9,25 +9,27 @@ using Cursors for Cur;
 string constant NAME = "getBalances";
 string constant INPUT = "query(bytes32 account, bytes32 asset, bytes32 meta)";
 
+abstract contract GetBalancesHook {
+    /// @notice Resolve one account's balance for one supported asset.
+    /// Concrete implementations define how assets are resolved.
+    /// @param account Account identifier carried by the query payload.
+    /// @param asset Requested asset identifier.
+    /// @param meta Requested asset metadata slot.
+    /// @return amount Current balance in the asset's native units.
+    function getBalance(bytes32 account, bytes32 asset, bytes32 meta) internal view virtual returns (uint amount);
+}
+
 /// @title GetBalances
 /// @notice Rootzero query that resolves balances for one or more `(account, asset, meta)` tuples.
 /// The request is a run of `QUERY` blocks, each encoding `(bytes32 account, bytes32 asset, bytes32 meta)`.
 /// The response returns one `BALANCE` block per query entry, preserving request order.
-abstract contract GetBalances is QueryBase {
+abstract contract GetBalances is QueryBase, GetBalancesHook {
     uint public immutable getBalancesId = queryId(NAME);
 
     constructor() {
         emit Query(host, NAME, INPUT, Schemas.Balance, getBalancesId);
     }
 
-    /// @notice Resolve one account's balance for one supported asset.
-    /// Concrete implementations define how assets are resolved.
-    /// @param account Account identifier carried by the query payload.
-    /// @param asset Requested asset identifier.
-    /// @param meta Requested asset metadata slot.
-    /// @return amount Current balance in the asset's native units.
-    function getBalance(bytes32 account, bytes32 asset, bytes32 meta) internal view virtual returns (uint amount);
-
     /// @notice Resolve balances for a run of requested `(account, asset, meta)` tuples.
     /// @param request Block-stream request consisting of `query(account, asset, meta)*`.
     /// @return Block-stream response containing one `balance(asset, meta, amount)` per query block.

package/queries/Positions.sol

@@ -9,11 +9,21 @@ using Cursors for Cur;
 
 string constant NAME = "getAssetPosition";
 
+abstract contract AssetPositionHook {
+    /// @notice Resolve the position payload for one requested asset tuple.
+    /// Concrete implementations must append exactly one `RESPONSE` block whose payload
+    /// length matches `positionResponseSize`.
+    /// @param asset Requested asset identifier.
+    /// @param meta Requested asset metadata slot.
+    /// @param response Destination writer for the response stream.
+    function appendAssetPosition(bytes32 asset, bytes32 meta, Writer memory response) internal view virtual;
+}
+
 /// @title PositionsQuery
 /// @notice Rootzero query that resolves one dynamic position response for each requested asset tuple.
 /// The request is a run of `ASSET` blocks.
 /// The response returns one dynamic `RESPONSE` block per asset entry, preserving request order.
-abstract contract AssetPosition is QueryBase {
+abstract contract AssetPosition is QueryBase, AssetPositionHook {
     uint public immutable getAssetPositionId = queryId(NAME);
     uint internal immutable positionResponseSize;
 
@@ -22,14 +32,6 @@ abstract contract AssetPosition is QueryBase {
         emit Query(host, NAME, Schemas.Asset, output, getAssetPositionId);
     }
 
-    /// @notice Resolve the position payload for one requested asset tuple.
-    /// Concrete implementations must append exactly one `RESPONSE` block whose payload
-    /// length matches `positionResponseSize`.
-    /// @param asset Requested asset identifier.
-    /// @param meta Requested asset metadata slot.
-    /// @param response Destination writer for the response stream.
-    function appendAssetPosition(bytes32 asset, bytes32 meta, Writer memory response) internal view virtual;
-
     /// @notice Resolve positions for a run of requested `(asset, meta)` tuples.
     /// @dev Allocates from the configured fixed response payload length so each hook call
     ///      can append one `RESPONSE` block directly into the output stream.

package/utils/Assets.sol

@@ -10,7 +10,8 @@ import {matchesBase, toLocalBase} from "./Utils.sol";
 /// Asset IDs embed a 4-byte type tag in bits [255:224]:
 ///   - `Value`  — native chain value (ETH); no address payload
 ///   - `Erc20`  — ERC-20 token; contract address in bits [191:32]
-///   - `Erc721` — ERC-721 collection; issuer 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]
 ///
 /// All asset IDs are chain-local (include `block.chainid` in bits [223:192]).
 library Assets {
@@ -22,13 +23,20 @@ library Assets {
     /// @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.Evm32) << 16) | (uint32(Layout.Asset) << 8) | uint32(Layout.Erc721);
+    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 32-byte EVM layout (top byte is `0x20`).
+    /// @notice Return true if `asset` uses the 32-byte asset layout with no metadata identity (top byte is `0x20`).
     function is32(bytes32 asset) internal pure returns (bool) {
         return bytes1(asset) == 0x20;
     }
 
+    /// @notice Return true if `asset` uses the 64-byte asset layout with metadata-backed identity (top byte is `0x40`).
+    function is64(bytes32 asset) internal pure returns (bool) {
+        return bytes1(asset) == 0x40;
+    }
+
     /// @notice Create a chain-local native value asset ID.
     /// @return Asset ID for the native token on the current chain.
     function toValue() internal view returns (bytes32) {
@@ -42,23 +50,31 @@ library Assets {
         return bytes32(toLocalBase(Erc20) | (uint(uint160(addr)) << 32));
     }
 
-    /// @notice Create a chain-local ERC-721 asset ID for `issuer`.
-    /// @param issuer ERC-721 collection contract address.
-    /// @return Asset ID with `issuer` embedded in bits [191:32].
-    function toErc721(address issuer) internal view returns (bytes32) {
-        return bytes32(toLocalBase(Erc721) | (uint(uint160(issuer)) << 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 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 Derive a storage key for an (asset, meta) pair.
     /// For 32-byte EVM assets (no meta), the key is the asset ID itself.
-    /// For assets with metadata (e.g. ERC-721 token IDs), the key is
+    /// For assets with metadata (e.g. ERC-721 or ERC-1155 token IDs), the key is
     /// `keccak256(asset ++ meta)`.
-    /// Reverts if `asset` is zero, or if it is a 32-byte asset but `meta` is non-zero.
+    /// Reverts only if `asset` is zero.
+    /// For 32-byte assets, `meta` is ignored and does not affect the derived key.
     /// @param asset Asset identifier.
     /// @param meta Asset metadata slot (e.g. token ID context).
     /// @return Storage key for the (asset, meta) combination.
     function key(bytes32 asset, bytes32 meta) internal pure returns (bytes32) {
-        if (asset == 0 || (bytes1(asset) == 0x20 && meta != 0)) revert InvalidAsset();
+        if (asset == 0) revert InvalidAsset();
         return bytes1(asset) == 0x20 ? asset : keccak256(bytes.concat(asset, meta));
     }
 
@@ -96,14 +112,53 @@ library Assets {
         return address(uint160(uint(asset) >> 32));
     }
 
-    /// @notice Extract the ERC-721 issuer address from an asset ID.
+    /// @notice Assert that `asset` is a local ERC-20 for `token` and return it unchanged.
+    /// Reverts if `asset` is not a local ERC-20 asset or if its token address differs.
+    /// @param asset ERC-20 asset identifier.
+    /// @param token Expected token contract address.
+    /// @return The same `asset` value if valid.
+    function matchErc20(bytes32 asset, address token) internal view returns (bytes32) {
+        if (erc20Addr(asset) != token) revert InvalidAsset();
+        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 Issuer contract address embedded in bits [191:32].
-    function erc721Issuer(bytes32 asset) internal view returns (address) {
+    /// @return Collection contract address embedded in bits [191:32].
+    function erc721Collection(bytes32 asset) internal view returns (address) {
         if (!matchesBase(asset, toLocalBase(Erc721))) revert InvalidAsset();
         return address(uint160(uint(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) {
+        if (!matchesBase(asset, toLocalBase(Erc1155))) revert InvalidAsset();
+        return address(uint160(uint(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;
+    }
 }
 
 /// @title Amounts

package/utils/Ids.sol

@@ -95,12 +95,12 @@ library Ids {
         return bytes4(uint32(id >> 160));
     }
 
-    /// @notice Assert that `id` is the host ID of `target` on the current chain.
+    /// @notice Assert that `id` is the host ID of `addr` on the current chain.
     /// @param id Node ID to validate.
-    /// @param target Expected host contract address.
-    /// @return hid The same `id` value if it matches `target`.
-    function host(uint id, address target) internal view returns (uint hid) {
-        if (id != toHost(target)) revert InvalidId();
+    /// @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;
     }
 

package/utils/Layout.sol

@@ -17,7 +17,7 @@ library Layout {
     uint16 constant Opaque32 = 0x2000;
     /// @dev 32-byte EVM-compatible value; lower 20 bytes hold an address.
     uint16 constant Evm32 = 0x2001;
-    /// @dev 64-byte EVM-compatible value (reserved for extended IDs).
+    /// @dev 64-byte EVM-compatible value; used when a paired metadata word completes the identity.
     uint16 constant Evm64 = 0x4001;
 
     // -------------------------------------------------------------------------
@@ -63,6 +63,8 @@ library Layout {
     uint8 constant Value = 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 issuer address.
+    /// @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;
 }