@rootzero/contracts 0.8.0 → 0.9.0

package/queries/Positions.sol

@@ -1,49 +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";
 
-abstract contract AssetPositionHook {
-    /// @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 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, AssetPositionHook {
-    uint public immutable getAssetPositionId = queryId(NAME);
+/// @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, NAME, Schemas.Asset, output, getAssetPositionId);
+        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

@@ -27,14 +27,71 @@ library Assets {
     /// @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;
+    }
+
     /// @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 bytes1(asset) == 0x40;
+        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.
@@ -64,52 +121,12 @@ library Assets {
         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 or ERC-1155 token IDs), the key is
-    /// `keccak256(asset ++ meta)`.
-    /// 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) 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 Extract the ERC-20 contract address from an asset ID.
     /// Reverts if `asset` is not a local ERC-20 asset.
     /// @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.
@@ -127,8 +144,7 @@ library Assets {
     /// @param asset ERC-721 asset identifier.
     /// @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));
+        return address(uint160(uint(erc721(asset)) >> 32));
     }
 
     /// @notice Assert that `asset` is a local ERC-721 for `collection` and return it unchanged.
@@ -146,8 +162,7 @@ library Assets {
     /// @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));
+        return address(uint160(uint(erc1155(asset)) >> 32));
     }
 
     /// @notice Assert that `asset` is a local ERC-1155 for `collection` and return it unchanged.
@@ -159,6 +174,21 @@ library Assets {
         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));
+    }
 }
 
 /// @title Amounts
@@ -191,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;
     }
@@ -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

@@ -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;
 
     // -------------------------------------------------------------------------

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) {