@rootzero/contracts 0.7.1 → 0.8.0

package/Commands.sol

@@ -6,33 +6,33 @@ pragma solidity ^0.8.33;
 
 import { CommandBase, CommandContext, CommandPayable, encodeCommandCall } from "./commands/Base.sol";
 import { State } from "./utils/State.sol";
-import { Burn } from "./commands/Burn.sol";
-import { Create } from "./commands/Create.sol";
-import { CreditAccount } from "./commands/Credit.sol";
-import { DebitAccount } from "./commands/Debit.sol";
-import { Deposit, DepositPayable } from "./commands/Deposit.sol";
-import { Remove } from "./commands/Remove.sol";
-import { PipePayable } from "./commands/Pipe.sol";
-import { Provision, ProvisionPayable, ProvisionFromBalance } from "./commands/Provision.sol";
+import { Burn, BurnHook } from "./commands/Burn.sol";
+import { Create, CreateHook } from "./commands/Create.sol";
+import { CreditAccount, CreditAccountHook } from "./commands/Credit.sol";
+import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
+import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
+import { Remove, RemoveHook } from "./commands/Remove.sol";
+import { PipePayable, PipePayableHook } from "./commands/Pipe.sol";
+import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook, ProvisionFromBalance } from "./commands/Provision.sol";
 import { Settle } from "./commands/Settle.sol";
-import { StakeCustodyToPosition } from "./commands/Stake.sol";
-import { Supply } from "./commands/Supply.sol";
-import { Transfer } from "./commands/Transfer.sol";
-import { Withdraw } from "./commands/Withdraw.sol";
+import { StakeCustodyToPosition, StakeCustodyToPositionHook } from "./commands/Stake.sol";
+import { Supply, SupplyHook } from "./commands/Supply.sol";
+import { Transfer, TransferHook } from "./commands/Transfer.sol";
+import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
-import { Destroy } from "./commands/admin/Destroy.sol";
+import { Destroy, DestroyHook } from "./commands/admin/Destroy.sol";
 import { Authorize } from "./commands/admin/Authorize.sol";
 import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
-import { Init } from "./commands/admin/Init.sol";
+import { Init, InitHook } from "./commands/admin/Init.sol";
 import { RelocatePayable } from "./commands/admin/Relocate.sol";
-import { Allocate } from "./commands/admin/Allocate.sol";
+import { Allocate, AllocateHook } from "./commands/admin/Allocate.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 import { PeerBase, encodePeerCall } from "./peer/Base.sol";
-import { PeerAssetPull } from "./peer/AssetPull.sol";
+import { PeerAssetPull, PeerAssetPullHook } from "./peer/AssetPull.sol";
 import { PeerAllowAssets } from "./peer/AllowAssets.sol";
 import { PeerDenyAssets } from "./peer/DenyAssets.sol";
-import { PeerPull } from "./peer/Pull.sol";
-import { PeerPush } from "./peer/Push.sol";
+import { PeerPull, PeerPullHook } from "./peer/Pull.sol";
+import { PeerPush, PeerPushHook } from "./peer/Push.sol";
 import { PeerSettle } from "./peer/Settle.sol";
 
 

package/Cursors.sol

@@ -7,7 +7,10 @@ pragma solidity ^0.8.33;
 import { HostAmount, UserAmount, HostAsset, Tx, AssetAmount, Sizes } from "./blocks/Schema.sol";
 import { Keys } from "./blocks/Keys.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { Cursors, Cur } from "./blocks/Cursors.sol";
+import { Cursors, Cur } from "./blocks/cursors/Core.sol";
+import { Erc20Cursors } from "./blocks/cursors/Erc20.sol";
+import { Erc1155Cursors } from "./blocks/cursors/Erc1155.sol";
+import { Erc721Cursors } from "./blocks/cursors/Erc721.sol";
 import { Writer, Writers } from "./blocks/Writers.sol";
 
 

package/Queries.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports query abstractions and reusable query bases.
 // Import this file to build rootzero query contracts without managing individual paths.
 
-import { IsAllowedAsset } from "./queries/Assets.sol";
-import { AssetPosition } from "./queries/Positions.sol";
-import { GetBalances } from "./queries/Balances.sol";
+import { IsAllowedAsset, IsAllowedAssetHook } from "./queries/Assets.sol";
+import { AssetPosition, AssetPositionHook } from "./queries/Positions.sol";
+import { GetBalances, GetBalancesHook } from "./queries/Balances.sol";
 import { QueryBase, encodeQueryCall } from "./queries/Base.sol";

package/blocks/Keys.sol

@@ -28,6 +28,7 @@ library Keys {
     bytes4 constant Break = bytes4(keccak256("break()"));
     /// @dev Bundle wrapper — (bytes data); payload is an embedded block stream
     bytes4 constant Bundle = bytes4(keccak256("bundle(bytes data)"));
+    bytes4 constant List = bytes4(keccak256("list(bytes data)"));
     /// @dev Extensible routing field — (bytes data); layout is command-defined
     bytes4 constant Route = bytes4(keccak256("route(bytes data)"));
     /// @dev Extensible query field - (bytes data); layout is query-defined, key is always `Keys.Query`

package/blocks/Schema.sol

@@ -67,10 +67,13 @@ library Schemas {
 // Schema DSL:
 // - `;` separates top-level sibling blocks
 // - `&` bundles adjacent blocks into one bundle block
+// - a bundle may optionally be named in the form `name = a & b`
+// - postfix `[]` marks a repeated list in the simple suffix form, e.g. `asset(...)[]`
+// - a list of bundled items must use an inline named form `name[] = a & b`
 // - bundled blocks preserve member order, so `a & b` differs from `b & a`
 // - a bundle block's self payload is an embedded normal block stream of its bundled members
 // - bundled members keep their ordinary block encoding, so dynamic blocks are allowed inside bundles
-// - `->` separates request and response shapes, appears at most once, and is omitted when no output is modeled
+// - a list block's self payload is an embedded normal block stream representing the repeated items
 // - top-level blocks of the same type should be grouped together
 // - primary / driving blocks should appear before auxiliary blocks
 // - `route(<fields...>)`, `query(<fields...>)`, and `response(<fields...>)` are reserved
@@ -79,6 +82,10 @@ library Schemas {
 // - these extensible forms work like dynamic `bytes` blocks: they may carry arbitrary
 //   payload bytes while keeping one fixed key per semantic block type
 // - `&` compiles to a `Keys.Bundle` block whose self payload is the bundled member block stream
+// - `[]` compiles to a `Keys.List` block whose self payload is the repeated item block stream
+// - `asset(...)[]` means a list whose repeated item is the block `asset(...)`
+// - `steps[] = asset(...) & recipient(...)` means a named list whose repeated item is the bundle
+//   `asset(...) & recipient(...)`
 // - canonical blocks are `amount(...)` for request amounts, `balance(...)` for state balances,
 //   `minimum(...)` for result floors, `maximum(...)` for spend ceilings, and `quantity(...)`
 //   for plain scalar amounts

package/blocks/{Cursors.sol → cursors/Core.sol}

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {HostAsset, AssetAmount, HostAmount, Tx, Keys, Sizes} from "./Schema.sol";
-import {ALLOC_SCALE, Writer, Writers} from "./Writers.sol";
+import {HostAsset, AssetAmount, HostAmount, Tx, Keys, Sizes} from "../Schema.sol";
+import {ALLOC_SCALE, Writer, Writers} from "../Writers.sol";
 
 /// @notice Zero-copy view into a calldata block stream.
 /// All positions (`i`, `bound`) are byte offsets relative to the start of the source region.
@@ -74,6 +74,18 @@ library Cursors {
         return cur;
     }
 
+    /// @notice Create a subcursor over the half-open range `[from, to)` within the source region.
+    /// The returned cursor starts at position zero within that sliced region.
+    /// @param cur Source cursor.
+    /// @param from Start byte offset within the source region (inclusive).
+    /// @param to End byte offset within the source region (exclusive).
+    /// @return out Cursor scoped to the requested sub-range.
+    function slice(Cur memory cur, uint from, uint to) internal pure returns (Cur memory out) {
+        if (from > to || to > cur.len) revert MalformedBlocks();
+        out.offset = cur.offset + from;
+        out.len = to - from;
+    }
+
     /// @notice Read a block header at position `i` without advancing the cursor.
     /// @param cur Source cursor.
     /// @param i Byte offset of the block header within the source region.
@@ -141,7 +153,7 @@ library Cursors {
     /// @return quotient Number of groups represented by the run (`count / group`).
     function primeRun(Cur memory cur, uint group) internal pure returns (bytes4 key, uint count, uint quotient) {
         if (group == 0) revert ZeroGroup();
-        key = cur.len < 4 ? bytes4(0) : bytes4(msg.data[cur.offset:cur.offset + 4]);
+        key = cur.i + 4 > cur.len ? bytes4(0) : bytes4(msg.data[cur.offset + cur.i:cur.offset + cur.i + 4]);
         (count, cur.bound) = countRun(cur, cur.i, key);
         if (count == 0) revert ZeroCursor();
         if (count % group != 0) revert BadRatio();
@@ -182,16 +194,48 @@ library Cursors {
         cur.i = next;
     }
 
-    /// @notice Parse a Bundle block at the current position and return an inner cursor.
-    /// Advances `cur.i` past the bundle block.
-    /// @param cur Outer cursor; advanced by one bundle block.
-    /// @return out Inner cursor scoped to the bundle's embedded block stream.
-    function bundle(Cur memory cur) internal pure returns (Cur memory out) {
-        (uint abs, uint next) = expect(cur, cur.i, Keys.Bundle, 0, 0);
-        uint len = next - (abs - cur.offset);
-        out.offset = abs;
-        out.len = len;
-        cur.i = next;
+    /// @notice Enter a Bundle block at the current position and return the next offset.
+    /// Advances `cur.i` past the bundle header so the bundled members can be parsed
+    /// directly from the same cursor. The returned `next` is the byte offset
+    /// immediately after the bundle payload, relative to the current cursor region.
+    /// @param cur Cursor positioned at a bundle block; advanced past the 8-byte header.
+    /// @return next Byte offset immediately after the bundle payload.
+    function bundle(Cur memory cur) internal pure returns (uint next) {
+        (, next) = expect(cur, cur.i, Keys.Bundle, 0, 0);
+        cur.i += 8;
+    }
+
+    /// @notice Enter a List block at the current position and return the next offset.
+    /// Advances `cur.i` past the list header so the list members can be parsed
+    /// directly from the same cursor. The returned `next` is the byte offset
+    /// immediately after the list payload, relative to the current cursor region.
+    /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
+    /// @return next Byte offset immediately after the list payload.
+    function list(Cur memory cur) internal pure returns (uint next) {
+        (, next) = expect(cur, cur.i, Keys.List, 0, 0);
+        cur.i += 8;
+    }
+
+    /// @notice Enter a List block, prime its member run, and return the raw block count.
+    /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
+    /// @param group Expected block group size for the list item stream.
+    /// @return count Total number of blocks in the list payload (a multiple of `group`).
+    /// @return next Byte offset immediately after the list payload.
+    function list(Cur memory cur, uint group) internal pure returns (uint count, uint next) {
+        next = list(cur);
+        (, count, ) = cur.primeRun(group);
+        if (cur.bound != next) revert IncompleteCursor();
+    }
+
+    /// @notice Enter a List block, prime its member run, and require an exact raw block count.
+    /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
+    /// @param group Expected block group size for the list item stream.
+    /// @param requiredCount Required number of blocks in the list payload.
+    /// @return next Byte offset immediately after the list payload.
+    function list(Cur memory cur, uint group, uint requiredCount) internal pure returns (uint next) {
+        uint count;
+        (count, next) = list(cur, group);
+        if (count != requiredCount) revert BadRatio();
     }
 
     /// @notice Assert that the cursor has consumed exactly up to `bound`.
@@ -201,6 +245,32 @@ library Cursors {
         if (cur.bound == 0 || cur.i != cur.bound) revert IncompleteCursor();
     }
 
+    /// @notice Assert that the cursor has consumed its entire source region.
+    /// Reverts with `IncompleteCursor` when `cur.i != cur.len`.
+    /// @param cur Cursor to check.
+    function end(Cur memory cur) internal pure {
+        if (cur.i != cur.len) revert IncompleteCursor();
+    }
+
+    /// @notice Resume parsing after a nested region delimited by `resumeAt`.
+    /// Reverts with `IncompleteCursor` if `cur.i` has advanced past `resumeAt` or `resumeAt`
+    /// exceeds the cursor region length. Otherwise moves `cur.i` to `end`.
+    /// @param cur Cursor to advance.
+    /// @param resumeAt Relative end offset of the nested region to resume after.
+    function resume(Cur memory cur, uint resumeAt) internal pure {
+        if (resumeAt > cur.len || cur.i > resumeAt) revert IncompleteCursor();
+        cur.i = resumeAt;
+    }
+
+    /// @notice Ensure that parsing has reached an exact nested-region boundary.
+    /// Reverts with `IncompleteCursor` if `ensureAt` exceeds the cursor region length
+    /// or `cur.i != ensureAt`.
+    /// @param cur Cursor to check.
+    /// @param ensureAt Relative offset that `cur.i` must match exactly.
+    function ensure(Cur memory cur, uint ensureAt) internal pure {
+        if (ensureAt > cur.len || cur.i != ensureAt) revert IncompleteCursor();
+    }
+
     /// @notice Assert completion and finalise a writer in one step.
     /// @param cur Cursor to check.
     /// @param writer Writer to finalise.

package/blocks/cursors/Erc1155.sol

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Cur, Cursors } from "./Core.sol";
+import { Keys } from "../Keys.sol";
+import { Assets } from "../../utils/Assets.sol";
+
+using Assets for bytes32;
+
+/// @title Erc1155Cursors
+/// @notice ERC-1155-aware cursor helpers layered on top of generic block parsing.
+library Erc1155Cursors {
+    /// @notice Validate an AMOUNT block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the block is not AMOUNT, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the AMOUNT block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Amount from the block.
+    function expectErc1155Amount(Cur memory cur, uint i, address collection) internal view returns (bytes32 meta, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Amount, 96, 96);
+        bytes32(msg.data[abs:abs + 32]).matchErc1155(collection);
+        meta = bytes32(msg.data[abs + 32:abs + 64]);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a BALANCE block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the block is not BALANCE, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the BALANCE block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Balance amount from the block.
+    function expectErc1155Balance(Cur memory cur, uint i, address collection) internal view returns (bytes32 meta, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Balance, 96, 96);
+        bytes32(msg.data[abs:abs + 32]).matchErc1155(collection);
+        meta = bytes32(msg.data[abs + 32:abs + 64]);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a MINIMUM block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the block is not MINIMUM, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the MINIMUM block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Minimum amount from the block.
+    function expectErc1155Minimum(Cur memory cur, uint i, address collection) internal view returns (bytes32 meta, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Minimum, 96, 96);
+        bytes32(msg.data[abs:abs + 32]).matchErc1155(collection);
+        meta = bytes32(msg.data[abs + 32:abs + 64]);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a MAXIMUM block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the block is not MAXIMUM, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the MAXIMUM block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Maximum amount from the block.
+    function expectErc1155Maximum(Cur memory cur, uint i, address collection) internal view returns (bytes32 meta, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Maximum, 96, 96);
+        bytes32(msg.data[abs:abs + 32]).matchErc1155(collection);
+        meta = bytes32(msg.data[abs + 32:abs + 64]);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a CUSTODY block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the block is not CUSTODY, the host differs, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the CUSTODY block.
+    /// @param host Expected host node ID from the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Custodied amount from the block.
+    function expectErc1155Custody(
+        Cur memory cur,
+        uint i,
+        uint host,
+        address collection
+    ) internal view returns (bytes32 meta, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Custody, 128, 128);
+        if (uint(bytes32(msg.data[abs:abs + 32])) != host) revert Cursors.UnexpectedValue();
+        bytes32(msg.data[abs + 32:abs + 64]).matchErc1155(collection);
+        meta = bytes32(msg.data[abs + 64:abs + 96]);
+        amount = uint(bytes32(msg.data[abs + 96:abs + 128]));
+    }
+
+    /// @notice Consume an AMOUNT block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the current block is not AMOUNT, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Cursor; advanced past the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Amount from the block.
+    function requireErc1155Amount(Cur memory cur, address collection) internal view returns (bytes32 meta, uint amount) {
+        (meta, amount) = expectErc1155Amount(cur, cur.i, collection);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a BALANCE block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the current block is not BALANCE, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Cursor; advanced past the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Balance amount from the block.
+    function requireErc1155Balance(Cur memory cur, address collection) internal view returns (bytes32 meta, uint amount) {
+        (meta, amount) = expectErc1155Balance(cur, cur.i, collection);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a MINIMUM block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the current block is not MINIMUM, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Cursor; advanced past the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Minimum amount from the block.
+    function requireErc1155Minimum(Cur memory cur, address collection) internal view returns (bytes32 meta, uint amount) {
+        (meta, amount) = expectErc1155Minimum(cur, cur.i, collection);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a MAXIMUM block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the current block is not MAXIMUM, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Cursor; advanced past the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Maximum amount from the block.
+    function requireErc1155Maximum(Cur memory cur, address collection) internal view returns (bytes32 meta, uint amount) {
+        (meta, amount) = expectErc1155Maximum(cur, cur.i, collection);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a CUSTODY block for a specific local ERC-1155 collection and return its token id and amount.
+    /// Reverts if the current block is not CUSTODY, the host differs, the asset is not a local ERC-1155, or the collection differs.
+    /// @param cur Cursor; advanced past the block.
+    /// @param host Expected host node ID from the block.
+    /// @param collection Expected local ERC-1155 collection.
+    /// @return meta Asset metadata slot from the block.
+    /// @return amount Custodied amount from the block.
+    function requireErc1155Custody(
+        Cur memory cur,
+        uint host,
+        address collection
+    ) internal view returns (bytes32 meta, uint amount) {
+        (meta, amount) = expectErc1155Custody(cur, cur.i, host, collection);
+        cur.i += 136;
+    }
+}

package/blocks/cursors/Erc20.sol

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Cur, Cursors } from "./Core.sol";
+import { Keys } from "../Keys.sol";
+import { Assets } from "../../utils/Assets.sol";
+
+using Assets for bytes32;
+
+/// @title Erc20Cursors
+/// @notice ERC-20-aware cursor helpers layered on top of generic block parsing.
+library Erc20Cursors {
+    function erc20AddrAt(uint abs) private view returns (address) {
+        return Assets.erc20Addr(bytes32(msg.data[abs:abs + 32]));
+    }
+
+    /// @notice Validate an AMOUNT block for any local ERC-20 token and return it.
+    /// Reverts if the block is not AMOUNT or the asset is not a local ERC-20.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the AMOUNT block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Amount from the block.
+    function expectErc20Amount(Cur memory cur, uint i) internal view returns (address token, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Amount, 96, 96);
+        token = erc20AddrAt(abs);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a BALANCE block for any local ERC-20 token and return it.
+    /// Reverts if the block is not BALANCE or the asset is not a local ERC-20.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the BALANCE block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Balance amount from the block.
+    function expectErc20Balance(Cur memory cur, uint i) internal view returns (address token, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Balance, 96, 96);
+        token = erc20AddrAt(abs);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a MINIMUM block for any local ERC-20 token and return it.
+    /// Reverts if the block is not MINIMUM or the asset is not a local ERC-20.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the MINIMUM block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Minimum amount from the block.
+    function expectErc20Minimum(Cur memory cur, uint i) internal view returns (address token, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Minimum, 96, 96);
+        token = erc20AddrAt(abs);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Consume a MINIMUM block for any local ERC-20 token and return it.
+    /// Reverts if the current block is not MINIMUM or the asset is not a local ERC-20.
+    /// @param cur Cursor; advanced past the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Minimum amount from the block.
+    function requireErc20Minimum(Cur memory cur) internal view returns (address token, uint amount) {
+        (token, amount) = expectErc20Minimum(cur, cur.i);
+        cur.i += 104;
+    }
+
+    /// @notice Validate a MAXIMUM block for any local ERC-20 token and return it.
+    /// Reverts if the block is not MAXIMUM or the asset is not a local ERC-20.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the MAXIMUM block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Maximum amount from the block.
+    function expectErc20Maximum(Cur memory cur, uint i) internal view returns (address token, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Maximum, 96, 96);
+        token = erc20AddrAt(abs);
+        amount = uint(bytes32(msg.data[abs + 64:abs + 96]));
+    }
+
+    /// @notice Validate a CUSTODY block for any local ERC-20 token and return it.
+    /// Reverts if the block is not CUSTODY or the asset is not a local ERC-20.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the CUSTODY block.
+    /// @param host Expected host node ID from the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Custodied amount from the block.
+    function expectErc20Custody(Cur memory cur, uint i, uint host) internal view returns (address token, uint amount) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Custody, 128, 128);
+        if (uint(bytes32(msg.data[abs:abs + 32])) != host) revert Cursors.UnexpectedValue();
+        token = erc20AddrAt(abs + 32);
+        amount = uint(bytes32(msg.data[abs + 96:abs + 128]));
+    }
+
+    /// @notice Consume an AMOUNT block for any local ERC-20 token and return it.
+    /// Reverts if the current block is not AMOUNT or the asset is not a local ERC-20.
+    /// @param cur Cursor; advanced past the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Amount from the block.
+    function requireErc20Amount(Cur memory cur) internal view returns (address token, uint amount) {
+        (token, amount) = expectErc20Amount(cur, cur.i);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a BALANCE block for any local ERC-20 token and return it.
+    /// Reverts if the current block is not BALANCE or the asset is not a local ERC-20.
+    /// @param cur Cursor; advanced past the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Balance amount from the block.
+    function requireErc20Balance(Cur memory cur) internal view returns (address token, uint amount) {
+        (token, amount) = expectErc20Balance(cur, cur.i);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a MAXIMUM block for any local ERC-20 token and return it.
+    /// Reverts if the current block is not MAXIMUM or the asset is not a local ERC-20.
+    /// @param cur Cursor; advanced past the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Maximum amount from the block.
+    function requireErc20Maximum(Cur memory cur) internal view returns (address token, uint amount) {
+        (token, amount) = expectErc20Maximum(cur, cur.i);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a CUSTODY block for any local ERC-20 token and return it.
+    /// Reverts if the current block is not CUSTODY or the asset is not a local ERC-20.
+    /// @param cur Cursor; advanced past the block.
+    /// @param host Expected host node ID from the block.
+    /// @return token Local ERC-20 token address extracted from the asset identifier.
+    /// @return amount Custodied amount from the block.
+    function requireErc20Custody(Cur memory cur, uint host) internal view returns (address token, uint amount) {
+        (token, amount) = expectErc20Custody(cur, cur.i, host);
+        cur.i += 136;
+    }
+
+}

package/blocks/cursors/Erc721.sol

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { Cur, Cursors } from "./Core.sol";
+import { Keys } from "../Keys.sol";
+import { Assets } from "../../utils/Assets.sol";
+
+using Assets for bytes32;
+
+/// @title Erc721Cursors
+/// @notice ERC-721-aware cursor helpers layered on top of generic block parsing.
+library Erc721Cursors {
+    /// @notice Validate a BALANCE block for a specific local ERC-721 collection and return its metadata.
+    /// Reverts if the block is not BALANCE, the asset is not a local ERC-721, the collection differs, or the amount is not 1.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the BALANCE block.
+    /// @param collection Expected local ERC-721 collection.
+    /// @return meta Asset metadata slot from the block.
+    function expectErc721Balance(Cur memory cur, uint i, address collection) internal view returns (bytes32 meta) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Balance, 96, 96);
+        bytes32(msg.data[abs:abs + 32]).matchErc721(collection);
+        meta = bytes32(msg.data[abs + 32:abs + 64]);
+        if (uint(bytes32(msg.data[abs + 64:abs + 96])) != 1) revert Cursors.UnexpectedValue();
+    }
+
+    /// @notice Validate a CUSTODY block for a specific local ERC-721 collection and return its metadata.
+    /// Reverts if the block is not CUSTODY, the host differs, the asset is not a local ERC-721, the collection differs, or the amount is not 1.
+    /// @param cur Source cursor.
+    /// @param i Byte offset of the CUSTODY block.
+    /// @param host Expected host node ID from the block.
+    /// @param collection Expected local ERC-721 collection.
+    /// @return meta Asset metadata slot from the block.
+    function expectErc721Custody(
+        Cur memory cur,
+        uint i,
+        uint host,
+        address collection
+    ) internal view returns (bytes32 meta) {
+        (uint abs, ) = Cursors.expect(cur, i, Keys.Custody, 128, 128);
+        if (uint(bytes32(msg.data[abs:abs + 32])) != host) revert Cursors.UnexpectedValue();
+        bytes32(msg.data[abs + 32:abs + 64]).matchErc721(collection);
+        meta = bytes32(msg.data[abs + 64:abs + 96]);
+        if (uint(bytes32(msg.data[abs + 96:abs + 128])) != 1) revert Cursors.UnexpectedValue();
+    }
+
+    /// @notice Consume a BALANCE block for a specific local ERC-721 collection and return its metadata.
+    /// Reverts if the current block is not BALANCE, the asset is not a local ERC-721, the collection differs, or the amount is not 1.
+    /// @param cur Cursor; advanced past the block.
+    /// @param collection Expected local ERC-721 collection.
+    /// @return meta Asset metadata slot from the block.
+    function requireErc721Balance(Cur memory cur, address collection) internal view returns (bytes32 meta) {
+        meta = expectErc721Balance(cur, cur.i, collection);
+        cur.i += 104;
+    }
+
+    /// @notice Consume a CUSTODY block for a specific local ERC-721 collection and return its metadata.
+    /// Reverts if the current block is not CUSTODY, the host differs, the asset is not a local ERC-721, the collection differs, or the amount is not 1.
+    /// @param cur Cursor; advanced past the block.
+    /// @param host Expected host node ID from the block.
+    /// @param collection Expected local ERC-721 collection.
+    /// @return meta Asset metadata slot from the block.
+    function requireErc721Custody(Cur memory cur, uint host, address collection) internal view returns (bytes32 meta) {
+        meta = expectErc721Custody(cur, cur.i, host, collection);
+        cur.i += 136;
+    }
+}

package/commands/Burn.sol

@@ -7,16 +7,7 @@ using Cursors for Cur;
 
 string constant NAME = "burn";
 
-/// @title Burn
-/// @notice Command that irreversibly destroys each BALANCE state block via a virtual hook.
-/// Produces no output state.
-abstract contract Burn is CommandBase {
-    uint internal immutable burnId = commandId(NAME);
-
-    constructor() {
-        emit Command(host, NAME, "", burnId, State.Balances, State.Empty, false);
-    }
-
+abstract contract BurnHook {
     /// @notice Override to burn or consume the provided balance amount.
     /// Called once per BALANCE block in state.
     /// @param account Caller's account identifier.
@@ -25,6 +16,17 @@ abstract contract Burn is CommandBase {
     /// @param amount Amount to burn.
     /// @return Amount actually burned (may differ from `amount` for partial burns).
     function burn(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal virtual returns (uint);
+}
+
+/// @title Burn
+/// @notice Command that irreversibly destroys each BALANCE state block via a virtual hook.
+/// Produces no output state.
+abstract contract Burn is CommandBase, BurnHook {
+    uint internal immutable burnId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, "", burnId, State.Balances, State.Empty, false);
+    }
 
     function burn(CommandContext calldata c) external onlyCommand(burnId, c.target) returns (bytes memory) {
         (Cur memory state, , ) = cursor(c.state, 1);