@rootzero/contracts 0.7.2 → 0.9.0

package/queries/Assets.sol

@@ -1,44 +1,46 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cur, Cursors, Writer, Writers, Keys} from "../Cursors.sol";
-import {Schemas} from "../blocks/Schema.sol";
+import {Cur, Cursors, Writer, Writers} from "../Cursors.sol";
+import {Forms, Schemas} from "../blocks/Schema.sol";
 import {QueryBase} from "./Base.sol";
 
 using Cursors for Cur;
+using Writers for Writer;
 
 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 {
+/// The response returns one `STATUS` form block per query entry, preserving request order.
+abstract contract IsAllowedAsset is QueryBase, IsAllowedAssetHook {
     uint public immutable isAllowedAssetId = queryId(NAME);
 
     constructor() {
-        emit Query(host, NAME, Schemas.Asset, OUTPUT, isAllowedAssetId);
+        emit Query(host, isAllowedAssetId, NAME, Schemas.Asset, Forms.Status);
     }
 
-    /// @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.
+    /// @return Block-stream response containing one `status(ok)` per asset block.
     function isAllowedAsset(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint count, ) = cursor(request, 1);
-        Writer memory response = Writers.alloc32s(count);
+        Writer memory response = Writers.allocStatuses(count);
 
         while (query.i < query.bound) {
             (bytes32 asset, bytes32 meta) = query.unpackAsset();
             bool allowed = isAllowedAsset(asset, meta);
-            Writers.appendBool(response, Keys.Response, allowed);
+            response.appendStatus(allowed);
         }
 
         return query.complete(response);

package/queries/Balances.sol

@@ -1,25 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cur, Cursors, Schemas, Writer, Writers} from "../Cursors.sol";
+import {Cur, Cursors, Forms, Writer, Writers} from "../Cursors.sol";
 import {QueryBase} from "./Base.sol";
 
 using Cursors for Cur;
+using Writers for Writer;
 
 string constant NAME = "getBalances";
-string constant INPUT = "query(bytes32 account, bytes32 asset, bytes32 meta)";
-
-/// @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 {
-    uint public immutable getBalancesId = queryId(NAME);
-
-    constructor() {
-        emit Query(host, NAME, INPUT, Schemas.Balance, getBalancesId);
-    }
 
+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.
@@ -27,18 +17,30 @@ abstract contract GetBalances is QueryBase {
     /// @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 `ACCOUNT_ASSET` form blocks.
+/// The response returns one `ACCOUNT_AMOUNT` form block per requested position, preserving request order.
+abstract contract GetBalances is QueryBase, GetBalancesHook {
+    uint public immutable getBalancesId = queryId(NAME);
+
+    constructor() {
+        emit Query(host, getBalancesId, NAME, Forms.AccountAsset, Forms.AccountAmount);
+    }
 
     /// @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.
+    /// @param request Block-stream request consisting of `accountAsset(account, asset, meta)*`.
+    /// @return Block-stream response containing one `accountAmount(account, asset, meta, amount)` block per request block.
     function getBalances(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint count, ) = cursor(request, 1);
-        Writer memory response = Writers.allocBalances(count);
+        Writer memory response = Writers.allocAccountAmounts(count);
 
         while (query.i < query.bound) {
-            (bytes32 account, bytes32 asset, bytes32 meta) = query.unpackQuery96();
-            uint balance = getBalance(account, asset, meta);
-            Writers.appendBalance(response, asset, meta, balance);
+            (bytes32 account, bytes32 asset, bytes32 meta) = query.unpackAccountAsset();
+            uint amount = getBalance(account, asset, meta);
+            response.appendAccountAmount(account, asset, meta, amount);
         }
 
         return query.complete(response);

package/queries/Base.sol

@@ -1,8 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CursorBase } from "../core/CursorBase.sol";
-import { HostBound } from "../core/HostBound.sol";
+import { RootZeroContext } from "../core/Context.sol";
 import { QueryEvent } from "../events/Query.sol";
 import { Ids, Selectors } from "../utils/Ids.sol";
 
@@ -21,7 +20,7 @@ function encodeQueryCall(uint target, bytes calldata request) pure returns (byte
 /// @notice Abstract base for rootzero query contracts.
 /// Queries are view-only entry points that consume a block-stream request and
 /// return a block-stream response.
-abstract contract QueryBase is CursorBase, HostBound, QueryEvent {
+abstract contract QueryBase is RootZeroContext, QueryEvent {
 
     /// @notice Derive the deterministic node ID for a named query on this contract.
     /// The ID encodes the ABI selector of `name(bytes)` and `address(this)`,

package/queries/Positions.sol

@@ -1,47 +1,55 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cur, Cursors, Writer, Writers, Keys} from "../Cursors.sol";
-import {Schemas} from "../blocks/Schema.sol";
+import {Cur, Cursors, Writer, Writers} from "../Cursors.sol";
+import {Forms} from "../blocks/Schema.sol";
 import {QueryBase} from "./Base.sol";
 
 using Cursors for Cur;
 
-string constant NAME = "getAssetPosition";
+string constant NAME = "getPosition";
 
-/// @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 {
-    uint public immutable getAssetPositionId = queryId(NAME);
-    uint internal immutable positionResponseSize;
-
-    constructor(string memory output, uint responseSize) {
-        positionResponseSize = responseSize;
-        emit Query(host, NAME, Schemas.Asset, output, getAssetPositionId);
-    }
-
-    /// @notice Resolve the position payload for one requested asset tuple.
+abstract contract GetPositionHook {
+    /// @notice Resolve the position payload for one requested position.
     /// Concrete implementations must append exactly one `RESPONSE` block whose payload
     /// length matches `positionResponseSize`.
+    /// @param account Requested account identifier.
     /// @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;
+    function appendPosition(
+        bytes32 account,
+        bytes32 asset,
+        bytes32 meta,
+        Writer memory response
+    ) internal view virtual;
+}
+
+/// @title GetPosition
+/// @notice Rootzero query that resolves one dynamic position response for each requested position.
+/// The request is a run of `ACCOUNT_ASSET` form blocks.
+/// The response returns one dynamic `RESPONSE` block per position entry, preserving request order.
+abstract contract GetPosition is QueryBase, GetPositionHook {
+    uint public immutable getPositionId = queryId(NAME);
+    uint internal immutable positionResponseSize;
+
+    constructor(string memory output, uint responseSize) {
+        positionResponseSize = responseSize;
+        emit Query(host, getPositionId, NAME, Forms.AccountAsset, output);
+    }
 
-    /// @notice Resolve positions for a run of requested `(asset, meta)` tuples.
+    /// @notice Resolve positions for a run of requested `(account, 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.
-    /// @param request Block-stream request consisting of `asset(asset, meta)*`.
-    /// @return Block-stream response containing one `response(bytes data)` block per asset block.
-    function getAssetPosition(bytes calldata request) external view returns (bytes memory) {
+    /// @param request Block-stream request consisting of `accountAsset(account, asset, meta)*`.
+    /// @return Block-stream response containing one `response(bytes data)` block per position block.
+    function getPosition(bytes calldata request) external view returns (bytes memory) {
         (Cur memory query, uint count, ) = cursor(request, 1);
         Writer memory response = Writers.allocBytes(count, positionResponseSize);
 
         while (query.i < query.bound) {
-            (bytes32 asset, bytes32 meta) = query.unpackAsset();
-            appendAssetPosition(asset, meta, response);
+            (bytes32 account, bytes32 asset, bytes32 meta) = query.unpackAccountAsset();
+            appendPosition(account, asset, meta, response);
         }
 
         return query.complete(response);

package/utils/Accounts.sol

@@ -10,7 +10,6 @@ import {isFamily, toLocalBase, toUnspecifiedBase} from "./Utils.sol";
 /// Account IDs embed a 4-byte type tag in bits [255:224]:
 ///   - `Admin` — chain-local EVM address in bits [191:32]
 ///   - `User`  — chain-agnostic EVM address in bits [191:32]
-///   - `Keccak` — 28-byte keccak hash of an arbitrary key
 library Accounts {
     /// @dev Thrown when an account ID does not belong to the EVM family.
     error InvalidAccount();
@@ -31,12 +30,21 @@ 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` is an admin account.
     function isAdmin(bytes32 account) internal pure returns (bool) {
         return prefix(account) == Admin;
     }
 
-    /// @notice Return true if `account` is a keccak account.
+    /// @notice Return true if `account` is a user account.
+    function isUser(bytes32 account) internal pure returns (bool) {
+        return prefix(account) == User;
+    }
+
     function isKeccak(bytes32 account) internal pure returns (bool) {
         return prefix(account) == Keccak;
     }
@@ -55,19 +63,12 @@ library Accounts {
         return bytes32(toUnspecifiedBase(User) | (uint(uint160(addr)) << 32));
     }
 
-    /// @notice Encode arbitrary calldata as a keccak account ID.
-    /// The lower 28 bytes of the ID hold the lower 28 bytes of `keccak256(raw)`.
-    /// @param raw Arbitrary key bytes to hash.
-    /// @return Keccak account ID.
-    function toKeccak(bytes calldata raw) internal pure returns (bytes32) {
-        return bytes32(toUnspecifiedBase(Keccak) | uint224(uint256(keccak256(raw))));
+    function toKeccak(bytes32 head, bytes32 meta) internal pure returns (bytes32) {
+        return bytes32(toUnspecifiedBase(Keccak) | uint224(uint256(keccak256(bytes.concat(head, meta)))));
     }
 
-    /// @notice Return true if `account` is the keccak account ID of `raw`.
-    /// @param account Account ID to compare.
-    /// @param raw Raw key bytes to hash and compare against.
-    function matchesKeccak(bytes32 account, bytes calldata raw) internal pure returns (bool) {
-        return account == toKeccak(raw);
+    function matchesKeccak(bytes32 account, bytes32 head, bytes32 meta) internal pure returns (bool) {
+        return account == toKeccak(head, meta);
     }
 
     /// @notice Assert that `account` uses the Account layout tag and return it unchanged.

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,11 +23,75 @@ 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 Asset category tag in the type field.
+    function isAsset(bytes32 asset) internal pure returns (bool) {
+        return uint8(uint(asset) >> 232) == Layout.Asset;
+    }
+
+    /// @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;
+        return isAsset(asset) && 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 isAsset(asset) && bytes1(asset) == 0x40;
+    }
+
+    /// @notice Return true if `asset` is the local native value asset.
+    function isValue(bytes32 asset) internal view returns (bool) {
+        return asset == toValue();
+    }
+
+    /// @notice Return true if `asset` is a local ERC-20 asset.
+    function isErc20(bytes32 asset) internal view returns (bool) {
+        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 `input` is the local native value asset and return it unchanged.
+    /// @param input Asset identifier to validate.
+    /// @return asset The same `input` if it is the local native value asset.
+    function value(bytes32 input) internal view returns (bytes32 asset) {
+        if (!isValue(input)) revert InvalidAsset();
+        return input;
+    }
+
+    /// @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 `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 Create a chain-local native value asset ID.
@@ -42,49 +107,18 @@ 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 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
-    /// `keccak256(asset ++ meta)`.
-    /// Reverts if `asset` is zero, or if it is a 32-byte asset but `meta` is non-zero.
-    /// @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();
-        return bytes1(asset) == 0x20 ? asset : keccak256(bytes.concat(asset, meta));
-    }
-
-    /// @notice Return true when two local ERC-20 assets are already in canonical token-address order.
-    /// Useful for pair-style integrations that require a stable token ordering
-    /// regardless of the caller's input order.
-    /// Reverts if either asset is not a local ERC-20 asset.
-    /// @param a First ERC-20 asset identifier.
-    /// @param b Second ERC-20 asset identifier.
-    /// @return ordered Whether `a`'s token address is lower than `b`'s token address.
-    function isSortedErc20(bytes32 a, bytes32 b) internal view returns (bool ordered) {
-        return erc20Addr(a) < erc20Addr(b);
-    }
-
-    /// @notice Extract the token addresses for two local ERC-20 assets and report whether they are already ordered.
-    /// The returned addresses preserve the original input order.
-    /// Reverts if either asset is not a local ERC-20 asset.
-    /// @param a First ERC-20 asset identifier.
-    /// @param b Second ERC-20 asset identifier.
-    /// @return addrA Token address extracted from `a`.
-    /// @return addrB Token address extracted from `b`.
-    /// @return ordered Whether `addrA` is lower than `addrB`.
-    function erc20Addrs(bytes32 a, bytes32 b) internal view returns (address addrA, address addrB, bool ordered) {
-        addrA = erc20Addr(a);
-        addrB = erc20Addr(b);
-        ordered = addrA < addrB;
+    /// @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 Extract the ERC-20 contract address from an asset ID.
@@ -92,17 +126,68 @@ 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) {
-        if (!matchesBase(asset, toLocalBase(Erc20))) revert InvalidAsset();
-        return address(uint160(uint(asset) >> 32));
+        return address(uint160(uint(erc20(asset)) >> 32));
+    }
+
+    /// @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 issuer address from an asset ID.
+    /// @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) {
-        if (!matchesBase(asset, toLocalBase(Erc721))) revert InvalidAsset();
-        return address(uint160(uint(asset) >> 32));
+    /// @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 EVM 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));
     }
 }
 
@@ -136,16 +221,6 @@ library Amounts {
         return amount;
     }
 
-    /// @notice Assert non-zero amount and derive the storage key for the (asset, meta) pair.
-    /// @param asset Asset identifier.
-    /// @param meta Asset metadata slot.
-    /// @param amount Amount to validate (must be non-zero).
-    /// @return key_ Storage key from `Assets.key(asset, meta)`.
-    function ensureKey(bytes32 asset, bytes32 meta, uint amount) internal pure returns (bytes32 key_) {
-        ensure(amount);
-        return Assets.key(asset, meta);
-    }
-
     /// @notice Clamp `available` to `[min, max]`.
     /// Uses all of `available` if it does not exceed `max`; reverts if the result
     /// would fall below `min`.

package/utils/Ids.sol

@@ -81,8 +81,8 @@ library Ids {
 
     /// @notice Assert that `id` is a query ID and return it unchanged.
     /// @param id Node ID to validate.
-    /// @return qid The same `id` value if it is a query.
-    function query(uint id) internal pure returns (uint qid) {
+    /// @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;
     }
@@ -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;
     }
 
@@ -163,8 +163,8 @@ library Ids {
 /// @title Selectors
 /// @notice ABI-selector derivation helpers for command, peer, and query dispatch.
 library Selectors {
-    /// @dev ABI argument encoding for command entry points: `((uint256,bytes32,bytes,bytes))`.
-    string constant CommandArgs = "((uint256,bytes32,bytes,bytes))";
+    /// @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)`.

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;
 
     // -------------------------------------------------------------------------
@@ -39,7 +39,7 @@ library Layout {
     uint8 constant Admin = 0x01;
     /// @dev User account — chain-agnostic, backed by an EVM address.
     uint8 constant User = 0x02;
-    /// @dev Keccak account — opaque 28-byte hash of an arbitrary key.
+    /// @dev Keccak account — opaque 28-byte keccak commitment.
     uint8 constant Keccak = 0x03;
 
     // -------------------------------------------------------------------------
@@ -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;
 }

package/utils/Utils.sol

@@ -92,6 +92,16 @@ function addrOr(address addr, address or) pure returns (address) {
     return addr == address(0) ? or : 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));
+}
+
+/// @notice Convert a 32-byte two's-complement representation to a signed integer.
+function bytes32ToInt(bytes32 value) pure returns (int) {
+    return int(uint(value));
+}
+
 /// @notice Convert a null-terminated `bytes32` value to a Solidity string.
 /// Stops at the first zero byte and returns only the meaningful prefix.
 function bytes32ToString(bytes32 value) pure returns (string memory result) {