@rootzero/contracts 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.11.0
+
+### Breaking Changes
+
+- Replaced the separate command, port, query, guard, and admin discovery events
+  with the shared `Endpoint` event and a packed endpoint descriptor. Admin
+  commands are now identified by the descriptor admin flag. Default lane groups
+  remain encoded as zero and are interpreted as group size one when read; the
+  final four descriptor bytes are reserved.
+- Renamed the block discovery event to `Schema` and added a `name` field for
+  alias-style schema references.
+- Removed the generic `DATA` block type. Custom input blocks should define
+  their own local keys and publish schemas explicitly when they need discovery.
+- Removed the built-in admin `init` and `destroy` commands.
+- Removed the built-in `Positions` query; custom position output should be
+  modeled as a custom query.
+- Changed `Cursors.list` to consume the LIST block and return a cursor scoped
+  to its payload instead of returning the list's end offset.
+- Renamed the `CommandContext.request` field to `input`. The tuple layout and
+  command selectors are unchanged.
+
+## 1.10.0
+
+### Breaking Changes
+
+- Moved `RecoverHook` from `Portal.sol` to `commands/Recover.sol`.
+- Moved `RoutePayableHook` from `Portal.sol` to `commands/Relay.sol`.
+- Renamed Portal helpers to `forward` / `retry`; hosts now explicitly bridge
+  the `RecoverPayable` hook to Portal retry behavior.
+- Renamed the generic `Resolved` event to `Recovered`.
+- Portal no longer emits `Recovered` when retrying an undelivered witness.
+- Renamed `Cursors.exit` to `ensureAt` and renamed its position argument to
+  `pos`.
+- Removed the redundant `next` return value from both `Cursors.init` overloads;
+  callers should use the returned cursor's `len` as the run boundary.
+- Changed `Cursors.list` to require the expected current cursor position as
+  `pos` before entering the LIST block.
+
 ## 1.9.0
 
 ### Breaking Changes
@@ -18,10 +56,10 @@ breaking API changes. Breaking changes are called out explicitly.
   so routes can be removed by emitting zero status.
 - Added `Undelivered(uint indexed host, bytes32 key, bytes32 digest)` for portal
   messages that could not be delivered to their handler port.
-- Added `Resolved(uint indexed host, bytes32 key)` as the
+- Added `Recovered(uint indexed host, bytes32 key)` as the
   matching event for resolved undelivered digests.
 - Removed the generic `Commitments` core mixin and `Commitment` event in favor
-  of domain-specific events such as `Undelivered` and `Resolved`.
+  of domain-specific events such as `Undelivered` and `Recovered`.
 
 ## 1.8.0
 

package/Core.sol

@@ -10,9 +10,11 @@ import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Host, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls } from "./core/Calls.sol";
+import { EndpointBase, Lane } from "./core/Endpoint.sol";
 import { Payable } from "./core/Payable.sol";
 import { Pipeline } from "./core/Pipeline.sol";
-import { Portal, RecoverHook, RoutePayableHook } from "./core/Portal.sol";
+import { Portal } from "./core/Portal.sol";
+import { RecoverHook } from "./commands/Recover.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 

package/Endpoints.sol

@@ -7,6 +7,7 @@ pragma solidity ^0.8.33;
 // Shared helpers
 import { Keys } from "./blocks/Keys.sol";
 import { CommandBase, CommandContext } from "./commands/Base.sol";
+import { EndpointBase, Lane } from "./core/Endpoint.sol";
 import { Payable } from "./core/Payable.sol";
 
 // Commands
@@ -16,9 +17,8 @@ import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
-import { RecoverPayable } from "./commands/Recover.sol";
-import { RelayPayable } from "./commands/Relay.sol";
-import { RecoverHook, RoutePayableHook } from "./core/Portal.sol";
+import { RecoverHook, RecoverPayable } from "./commands/Recover.sol";
+import { RelayPayable, RoutePayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -27,11 +27,9 @@ import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
 import { Allowance, AllowanceHook } from "./commands/admin/Allowance.sol";
 import { Appoint } from "./commands/admin/Appoint.sol";
 import { Authorize } from "./commands/admin/Authorize.sol";
-import { Destroy, DestroyHook } from "./commands/admin/Destroy.sol";
 import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
 import { Dismiss } from "./commands/admin/Dismiss.sol";
 import { ExecutePayable } from "./commands/admin/Execute.sol";
-import { Init, InitHook } from "./commands/admin/Init.sol";
 import { Label } from "./commands/admin/Label.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 
@@ -55,4 +53,3 @@ import { Revoke } from "./guards/Revoke.sol";
 import { QueryBase } from "./queries/Base.sol";
 import { AssetStatus, AssetStatusHook } from "./queries/Assets.sol";
 import { GetBalances, GetBalancesHook } from "./queries/Balances.sol";
-import { GetPosition, GetPositionHook } from "./queries/Positions.sol";

package/Events.sol

@@ -4,27 +4,24 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports all event contracts.
 // Import this file to get access to every event emitter in one import.
 
-import { AdminEvent } from "./events/Admin.sol";
 import { AssetEvent, AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
 import { CommanderEvent } from "./events/Commander.sol";
-import { CommandEvent } from "./events/Command.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
+import { EndpointEvent } from "./events/Endpoint.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
-import { ResolvedEvent } from "./events/Resolved.sol";
+import { RecoveredEvent } from "./events/Recovered.sol";
 import { EventEmitter } from "./events/Emitter.sol";
-import { GuardEvent } from "./events/Guard.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";
 import { LabeledEvent } from "./events/Labeled.sol";
 import { LockedEvent } from "./events/Locked.sol";
 import { NodeEvent } from "./events/Node.sol";
-import { PortEvent } from "./events/Port.sol";
-import { QueryEvent } from "./events/Query.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { RouteEvent } from "./events/Route.sol";
+import { SchemaEvent } from "./events/Schema.sol";
 import { SpentEvent } from "./events/Spent.sol";
 import { UndeliveredEvent } from "./events/Undelivered.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";

package/README.md

@@ -58,7 +58,7 @@ const host = await ethers.deployContract("ExampleHost", [deployer.address]);
 
 const account = encodeUserAccount(user.address); // receiving account
 const request = encodeAmountBlock(asset, 100n); // what to deposit
-await host.deposit({ account, state: "0x", request }); // emits Balance
+await host.deposit({ account, state: "0x", input: request }); // emits Balance
 ```
 
 The rest of this guide explains the ideas this example leans on — blocks, IDs,
@@ -74,11 +74,12 @@ payload:
 [bytes4 key][uint32 payloadLen][payload]
 ```
 
-The key is `bytes4(keccak256("#name"))`, and the payload layout is described by
-a schema string. For example, the block that requests a deposit:
+The key is usually `bytes4(keccak256("#name"))`, and the payload layout is
+described by a schema body published under an alias. For example, the standard
+`amount` block that requests a deposit:
 
 ```txt
-#amount { bytes32 asset, uint amount }
+amount { bytes32 asset, uint amount }
 ```
 
 is 72 bytes on the wire: an 8-byte header followed by two big-endian 32-byte
@@ -102,8 +103,12 @@ on the wire. The full schema language is specified in
 A request is not a single struct; it is a run of blocks. One `#amount` block
 asks for one deposit, five blocks ask for five, and the code path is identical
 — every endpoint parses with a cursor and loops until the stream is exhausted.
-The first item of a schema (the *prime item*) is the one that may repeat;
-later top-level items, if any, apply to the whole batch.
+The descriptor lane key is the prime item: it is the block type that may repeat
+for batching. Plain lanes are encoded as `[key][0]`; readers interpret the zero
+group byte as group size 1 when the lane is non-empty. Generic list lanes such
+as `many #asset` are encoded as
+`[Keys.List][Keys.Asset]`, so indexers can see both the top-level LIST container
+and the item type inside it.
 
 Off-chain, building a batch is concatenation. Using the reference encoders from
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts):
@@ -207,49 +212,46 @@ Commands are the write endpoints. Every command receives the same context:
 struct CommandContext {
     bytes32 account; // acting account
     bytes state;     // block stream produced by the previous command
-    bytes request;   // block stream for this invocation
+    bytes input;     // block stream for this invocation
 }
 ```
 
-The request carries instructions; the state carries live value. While a
+The input carries instructions; the state carries live value. While a
 sequence of commands executes, `#balance` and `#custody` blocks in the state
 are the funds being moved — produced by one command, consumed by the next.
 
-The standard `Deposit` mixin shows the canonical shape — init a cursor, loop
-the batch, call the hook, write the output run:
+The standard `Deposit` mixin shows the canonical shape — open the input,
+loop the batch, call the hook, write the output run:
 
 ```solidity
 function deposit(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-    (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
-    Writer memory writer = Writers.allocBalances(groups);
+    (Cur memory input, uint outputs) = openInput(c.input, descriptor);
+    Writer memory output = Writers.allocBalances(outputs);
 
-    while (request.i < request.len) {
-        (bytes32 asset, uint amount) = request.unpackAmount();
+    while (input.i < input.len) {
+        (bytes32 asset, uint amount) = input.unpackAmount();
         deposit(c.account, asset, amount); // host policy hook
-        writer.appendBalance(asset, amount);
+        output.appendBalance(asset, amount);
     }
 
-    request.complete();
-    return writer.finish();
+    return output.finish();
 }
 ```
 
 A command announces itself when the host is deployed. Its constructor emits a
-discovery event carrying the request schema, the expected and produced state
-block keys, and a shape string (`"1:0:1"` = one request block per operation, no
-input state, one output block per operation), plus a human-readable label:
+discovery event carrying a packed descriptor with the input, state, and output
+lanes, derived group sizes, and flags, plus a human-readable label:
 
 ```solidity
 abstract contract MyCommand is CommandBase {
-    uint internal immutable myCommandId = commandId(this.myCommand.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Command(host, myCommandId, "1:0:1", Schemas.Amount, Keys.Empty, Keys.Balance, false);
-        emit Labeled(myCommandId, bytes32(0), "myCommand");
+        (, descriptor) = command("myCommand", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
     }
 
     function myCommand(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        // parse c.request, loop, return the output state run
+        // parse c.input, loop, return the output state run
     }
 }
 ```
@@ -266,7 +268,7 @@ A single command is rarely the whole story. A pipeline is a run of `#step`
 blocks executed in order within one transaction:
 
 ```txt
-#step { uint target, uint resources, #bytes as request }
+step { uint target, uint resources, #bytes as request }
 ```
 
 Each step names a target command, the resources it may spend, and its request.
@@ -297,22 +299,22 @@ standard `getBalances` query takes a run of positions and answers each one in
 order:
 
 ```txt
-request:  #accountAsset { bytes32 account, bytes32 asset }
-response: #accountAmount { bytes32 account, bytes32 asset, uint amount }
+request:  accountAsset { bytes32 account, bytes32 asset }
+response: accountAmount { bytes32 account, bytes32 asset, uint amount }
 ```
 
-Like commands, every query announces its request and response schemas at
-deployment, so tooling knows how to call it without artifacts.
+Like commands, every query announces a descriptor at deployment; tooling resolves
+the descriptor's lanes through the published block schemas.
 
 ## Ports
 
 Ports are the host-to-host surfaces, callable only by trusted peer hosts. The two
 central ones are batches all the way down:
 
-- `portSettle` consumes `#transaction { bytes32 from, bytes32 to, bytes32 asset,
+- `portSettle` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
   block — how two hosts record settlement between their ledgers.
-- `portPipePayable` consumes `#context` blocks, each carrying an account, an
+- `portPipePayable` consumes `context` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
   host, executed locally against the port call's shared value budget.
 
@@ -339,8 +341,8 @@ drop a trusted node immediately.
 ## Events and Discovery
 
 Hosts are self-describing. At deployment a host emits the ABI of every event it
-uses (`EventAbi`), a discovery event per endpoint with its full schemas, and
-labels for human-readable names. State changes then follow evented
+uses (`EventAbi`), block schema events, endpoint descriptors, and labels for
+human-readable names. State changes then follow evented
 conventions: `Balance` for every ledger change and flow events (`Received`,
 `Spent`, `Locked`, `Unlocked`) for value movement, each tagged with the endpoint that
 caused it. An indexer can reconstruct the entire repository — endpoints,

package/Utils.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Nodes, Layout, Utils, Value).
+// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Nodes, Selectors, Layout, Utils, Value).
 // Import this file to access the full utility surface without managing individual paths.
 
 import { Keys } from "./blocks/Keys.sol";
@@ -11,6 +11,7 @@ import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
+import { Selectors } from "./utils/Selectors.sol";
 import { Layout } from "./utils/Layout.sol";
 import { Schemas } from "./blocks/Schema.sol";
 import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";

package/blocks/Cursors.sol

@@ -72,36 +72,20 @@ library Cursors {
 
     /// @notice Create a cursor over `source` and restrict it to its first grouped run.
     /// Equivalent to `open(source)`, reading the current key, then `run(key, group)`.
+    /// When `group` is zero, `source` must be empty and the function returns an empty cursor.
     /// @param source Calldata slice that forms the block stream.
-    /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
+    /// @param group Expected block group size (e.g. 1 for single, 2 for paired); 0 means empty.
     /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
     /// @return groups Number of block groups in the run (`block count / group`).
-    /// @return next Byte offset immediately after the run, relative to `source`.
-    function init(
-        bytes calldata source,
-        uint group
-    ) internal pure returns (Cur memory cur, uint groups, uint next) {
+    function init(bytes calldata source, uint group) internal pure returns (Cur memory cur, uint groups) {
         cur = open(source);
-        if (cur.i == cur.len) revert ZeroCursor();
+        if (group == 0) {
+            if (cur.len != 0) revert IncompleteCursor();
+            return (cur, 0);
+        }
+        if (cur.len == 0) revert ZeroCursor();
         (bytes4 key, ) = cur.peek(cur.i);
         groups = cur.run(key, group);
-        next = cur.len;
-    }
-
-    /// @notice Create a cursor over `source`, restrict it to its first grouped run, and require an exact group count.
-    /// @param source Calldata slice that forms the block stream.
-    /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
-    /// @param expectedGroups Required number of groups in the run.
-    /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
-    /// @return next Byte offset immediately after the run, relative to `source`.
-    function init(
-        bytes calldata source,
-        uint group,
-        uint expectedGroups
-    ) internal pure returns (Cur memory cur, uint next) {
-        uint groups;
-        (cur, groups, next) = init(source, group);
-        if (groups != expectedGroups) revert BadRatio();
     }
 
     /// @notice Move the cursor to an absolute position within the source region.
@@ -333,14 +317,15 @@ library Cursors {
         return find(cur, cur.i, key);
     }
 
-    /// @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 = enter(cur, Keys.List, 0, 0);
+    /// @notice Consume a LIST block and return a cursor over its payload.
+    /// Advances `cur.i` past the full list while the returned cursor is scoped to
+    /// the list members as a fresh zero-based region.
+    /// @param cur Cursor positioned at a list block; advanced past the full list.
+    /// @return items Cursor scoped to the list payload.
+    function list(Cur memory cur) internal pure returns (Cur memory items) {
+        uint next = enter(cur, Keys.List, 0, 0);
+        items = cur.slice(cur.i, next);
+        cur.i = next;
     }
 
     /// @notice Consume a block with the given key at the current position and return a cursor over the full block slice.
@@ -378,22 +363,13 @@ library Cursors {
         return cur.isAt(key) ? take(cur, key) : cur.slice(cur.i, cur.i);
     }
 
-    /// @notice Consume an optional DATA block at the current position and return a cursor over the full block slice.
-    /// If the current block is not DATA, returns an empty cursor and leaves `cur.i` unchanged.
-    /// Otherwise behaves like `take(cur, Keys.Data)`.
-    /// @param cur Cursor positioned at an optional DATA block.
-    /// @return out Cursor scoped to the full DATA block, or empty when no DATA block is present.
-    function maybeData(Cur memory cur) internal pure returns (Cur memory out) {
-        return maybeTake(cur, Keys.Data);
-    }
-
-    /// @notice Exit a nested region at an exact boundary.
-    /// Reverts with `IncompleteCursor` if `end` exceeds the cursor region length
-    /// or `cur.i != end`.
+    /// @notice Ensure the cursor is at an exact position.
+    /// Reverts with `IncompleteCursor` if `pos` exceeds the cursor region length
+    /// or `cur.i != pos`.
     /// @param cur Cursor to check.
-    /// @param end Relative end offset of the nested region.
-    function exit(Cur memory cur, uint end) internal pure {
-        if (end > cur.len || cur.i != end) revert IncompleteCursor();
+    /// @param pos Relative byte offset the cursor must be positioned at.
+    function ensureAt(Cur memory cur, uint pos) internal pure {
+        if (pos > cur.len || cur.i != pos) revert IncompleteCursor();
     }
 
     /// @notice Assert that the cursor has consumed its entire source region.
@@ -747,7 +723,7 @@ library Cursors {
         id = cur.readUint();
         namespace = cur.read32();
         name = cur.unpackString();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a dynamic block with a single bytes32 payload.
@@ -825,10 +801,7 @@ library Cursors {
     /// @param key Expected block key.
     /// @return asset Asset identifier.
     /// @return amount Scalar amount value.
-    function unpackAssetAmount(
-        Cur memory cur,
-        bytes4 key
-    ) internal pure returns (bytes32 asset, uint amount) {
+    function unpackAssetAmount(Cur memory cur, bytes4 key) internal pure returns (bytes32 asset, uint amount) {
         uint abs = consume(cur, 0, key, 64, 64);
         asset = bytes32(msg.data[abs:abs + 32]);
         amount = uint(bytes32(msg.data[abs + 32:abs + 64]));
@@ -992,9 +965,7 @@ library Cursors {
     /// @return host Host node ID.
     /// @return account Account identifier.
     /// @return asset Asset identifier.
-    function unpackHostAccountAsset(
-        Cur memory cur
-    ) internal pure returns (uint host, bytes32 account, bytes32 asset) {
+    function unpackHostAccountAsset(Cur memory cur) internal pure returns (uint host, bytes32 account, bytes32 asset) {
         return unpackHostAccountAsset(cur, Keys.HostAccountAsset);
     }
 
@@ -1010,9 +981,7 @@ library Cursors {
     /// @return account Account identifier.
     /// @return asset Asset identifier.
     /// @return amount Token amount.
-    function unpackAccountAmount(
-        Cur memory cur
-    ) internal pure returns (bytes32 account, bytes32 asset, uint amount) {
+    function unpackAccountAmount(Cur memory cur) internal pure returns (bytes32 account, bytes32 asset, uint amount) {
         return unpackAccountAmount(cur, Keys.AccountAmount);
     }
 
@@ -1028,9 +997,7 @@ library Cursors {
     /// @return host Host node ID.
     /// @return asset Asset identifier.
     /// @return amount Token amount.
-    function unpackAllocation(
-        Cur memory cur
-    ) internal pure returns (uint host, bytes32 asset, uint amount) {
+    function unpackAllocation(Cur memory cur) internal pure returns (uint host, bytes32 asset, uint amount) {
         return unpackHostAmount(cur, Keys.Allocation);
     }
 
@@ -1046,9 +1013,7 @@ library Cursors {
     /// @return host Host node ID.
     /// @return asset Asset identifier.
     /// @return amount Token amount.
-    function unpackAllowance(
-        Cur memory cur
-    ) internal pure returns (uint host, bytes32 asset, uint amount) {
+    function unpackAllowance(Cur memory cur) internal pure returns (uint host, bytes32 asset, uint amount) {
         return unpackHostAmount(cur, Keys.Allowance);
     }
 
@@ -1107,7 +1072,7 @@ library Cursors {
         target = uint(cur.read32());
         resources = uint(cur.read32());
         req = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a CALL block and return its target invocation fields.
@@ -1121,7 +1086,7 @@ library Cursors {
         target = uint(cur.read32());
         resources = uint(cur.read32());
         data = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a CONTEXT block and return its command context fields.
@@ -1137,7 +1102,7 @@ library Cursors {
         account = cur.read32();
         state = cur.unpackBytes();
         request = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a RELAY block and return its destination portal, resources, and request stream.
@@ -1145,14 +1110,12 @@ library Cursors {
     /// @return portal Destination portal identifier, often the destination host ID.
     /// @return resources Chain-specific resources for the destination context.
     /// @return request Embedded request block stream.
-    function unpackRelay(
-        Cur memory cur
-    ) internal pure returns (uint portal, uint resources, bytes calldata request) {
+    function unpackRelay(Cur memory cur) internal pure returns (uint portal, uint resources, bytes calldata request) {
         uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
         portal = cur.readUint();
         resources = cur.readUint();
         request = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a DISPATCH block and return its destination portal, resources, and payload.
@@ -1167,7 +1130,7 @@ library Cursors {
         portal = cur.readUint();
         resources = cur.readUint();
         payload = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a RECOVER block and return its handler, resources, key, and witness bytes.
@@ -1184,7 +1147,7 @@ library Cursors {
         resources = cur.readUint();
         key = cur.read32();
         witness = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     // Type-specific validators
@@ -1214,11 +1177,7 @@ library Cursors {
     /// @param key Expected block type key.
     /// @param asset Expected asset identifier.
     /// @return amount Amount from the block.
-    function requireAssetAmount(
-        Cur memory cur,
-        bytes4 key,
-        bytes32 asset
-    ) internal pure returns (uint amount) {
+    function requireAssetAmount(Cur memory cur, bytes4 key, bytes32 asset) internal pure returns (uint amount) {
         uint abs = consume(cur, 0, key, 64, 64);
         if (bytes32(msg.data[abs:abs + 32]) != asset) revert UnexpectedValue();
         amount = uint(bytes32(msg.data[abs + 32:abs + 64]));
@@ -1274,12 +1233,7 @@ library Cursors {
     /// @param key Expected block type key.
     /// @param host Expected host node ID.
     /// @param asset Expected asset identifier.
-    function requireUnitHostAmount(
-        Cur memory cur,
-        bytes4 key,
-        uint host,
-        bytes32 asset
-    ) internal pure {
+    function requireUnitHostAmount(Cur memory cur, bytes4 key, uint host, bytes32 asset) internal pure {
         uint abs = consume(cur, 0, key, 96, 96);
         if (uint(bytes32(msg.data[abs:abs + 32])) != host) revert UnexpectedValue();
         if (bytes32(msg.data[abs + 32:abs + 64]) != asset) revert UnexpectedValue();
@@ -1326,10 +1280,7 @@ library Cursors {
     /// @param host Expected host node ID.
     /// @return account Account identifier from the block.
     /// @return asset Asset identifier from the block.
-    function requireHostAccountAsset(
-        Cur memory cur,
-        uint host
-    ) internal pure returns (bytes32 account, bytes32 asset) {
+    function requireHostAccountAsset(Cur memory cur, uint host) internal pure returns (bytes32 account, bytes32 asset) {
         return requireHostAccountAsset(cur, Keys.HostAccountAsset, host);
     }
 

package/blocks/Keys.sol

@@ -2,9 +2,21 @@
 pragma solidity ^0.8.33;
 
 /// @title Keys
-/// @notice Block type selectors for the rootzero block stream protocol.
-/// Each key is the first 4 bytes of the keccak256 hash of its block name.
+/// @notice Standard block type selectors for the rootzero block stream protocol.
+/// Standard keys use the first 4 bytes of `keccak256("#name")` by convention.
+/// Custom block keys only need to be unique in the context where they are used;
+/// hosts may publish custom key meanings with the `Schema` event.
 library Keys {
+    /// @notice Create a context-local block key.
+    /// @dev Local keys are opaque tags for host- or endpoint-specific schemas.
+    /// The caller is responsible for choosing values that are unique in the
+    /// context where they are used and publishing their meaning with `Schema`.
+    /// @param value Opaque local key value.
+    /// @return Context-local block key.
+    function local(uint32 value) internal pure returns (bytes4) {
+        return bytes4(value);
+    }
+
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
     /// @dev Wildcard key used in discovery when any block stream is accepted.
@@ -27,8 +39,6 @@ library Keys {
     bytes4 constant Fee = bytes4(keccak256("#fee"));
     /// @dev List wrapper; payload is an embedded repeated block stream
     bytes4 constant List = bytes4(keccak256("#list"));
-    /// @dev Extensible data field; layout is schema-defined
-    bytes4 constant Data = bytes4(keccak256("#data"));
     /// @dev EVM-encoded payload field; layout follows standard ABI tuple encoding
     bytes4 constant Evm = bytes4(keccak256("#evm"));
     /// @dev Reserved raw bytes child block.