@rootzero/contracts 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -3,7 +3,26 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
-## Unreleased
+## 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
 

package/Core.sol

@@ -10,6 +10,7 @@ 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 } from "./core/Portal.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
@@ -26,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";
 
@@ -54,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 { 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,35 +72,22 @@ 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`).
-    function init(
-        bytes calldata source,
-        uint group
-    ) internal pure returns (Cur memory cur, uint groups) {
+    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);
     }
 
-    /// @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`.
-    function init(
-        bytes calldata source,
-        uint group,
-        uint expectedGroups
-    ) internal pure returns (Cur memory cur) {
-        uint groups;
-        (cur, groups) = init(source, group);
-        if (groups != expectedGroups) revert BadRatio();
-    }
-
     /// @notice Move the cursor to an absolute position within the source region.
     /// @param cur Cursor to update.
     /// @param i New read position (byte offset relative to source start).
@@ -330,17 +317,15 @@ library Cursors {
         return find(cur, cur.i, key);
     }
 
-    /// @notice Enter a LIST block at the expected current position and return its next offset.
-    /// Reverts with `IncompleteCursor` if `cur.i` is not exactly `pos`.
-    /// 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 expected to be positioned at a list block; advanced past the 8-byte header.
-    /// @param pos Expected current cursor position, relative to the cursor region.
-    /// @return next Byte offset immediately after the list payload.
-    function list(Cur memory cur, uint pos) internal pure returns (uint next) {
-        cur.ensureAt(pos);
-        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,15 +363,6 @@ 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 Ensure the cursor is at an exact position.
     /// Reverts with `IncompleteCursor` if `pos` exceeds the cursor region length
     /// or `cur.i != pos`.
@@ -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);
     }
 
@@ -1145,9 +1110,7 @@ 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();
@@ -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.

package/blocks/Schema.sol

@@ -7,31 +7,36 @@ pragma solidity ^0.8.33;
 // - payload layout is block-specific
 //
 // Schema:
-// - blocks are written as `#name { fields }`
-// - a block without braces has no payload, e.g. `#unit`
+// - block aliases are published separately from payload schemas
+// - payload schemas are written as `{ fields }`
+// - an empty schema string means the block has no structured payload
 // - commas separate siblings at every level
-// - braces define parent-child boundaries
+// - braces define the current block payload body
 // - command requests are a single run when the request schema is non-empty
 // - command state is a single active state run without trailing globals
 // - run items may repeat at top level for batching
-// - `maybe #x { ... }` marks an optional block item
-// - `many #x { ... }` emits one generic list block containing repeated `#x` items
+// - `maybe #x` marks an optional block item
+// - `many #x` emits one generic list block containing repeated `#x` items
+// - endpoint descriptor lanes are `[key bytes4][item bytes4]`; normal keys widen to `[key][0]`
+// - descriptor lanes for `many #x` use `[Keys.List][keyOfX]`; bare `[Keys.List][0]`
+//   is incomplete discovery metadata and should be rejected by tooling
 // - `portal` fields are routing identifiers, often destination host IDs
 // - `resources` fields are chain-specific resource words. A portal adapter
 //   interprets them for the destination runtime. EVM resources use the low
 //   128 bits as native value.
 // - dotted field names and aliases, e.g. `dst.portal` or `#bytes as dst.payload`,
 //   are offchain projection metadata only and do not change runtime encoding
-// - a child block without an inline body, e.g. `#context as witness`, may resolve
-//   to a known schema in the active schema context; unresolved aliases are invalid
+// - child blocks resolve by alias in the active schema context; unresolved aliases are invalid
+// - schema strings describe the payload body only; the `Block` event carries the alias
 // - fixed fields are packed in declaration order
 // - blocks have fixed fields followed by a dynamic child-block tail
 // - child block tails are embedded directly, without an extra stream wrapper
 // - `#bytes` is a reserved child block that stores raw bytes and has no body
 // - `#string` is a reserved child block that stores UTF-8 string bytes and has no body
-// - generic `#data` uses the stable key derived from `#data`
 // - generic lists use the stable key derived from `#list`
-// - keys are derived from block names, e.g. bytes4(keccak256("#amount"))
+// - standard keys are derived from block aliases, e.g. bytes4(keccak256("#amount"))
+// - custom keys are opaque bytes4 tags and only need to be unique in their
+//   active context; use `Schema(host, key, schema, name)` to publish their meaning
 // - see `docs/Schema.md` for the full working spec
 //
 // Pipeline state:
@@ -57,48 +62,48 @@ pragma solidity ^0.8.33;
 /// @title Schemas
 /// @notice Human-readable schema string constants for each block type.
 /// These strings describe payload layout for discovery events and docs; block
-/// keys are derived only from block names.
+/// aliases map to standard keys by convention. Custom blocks may use any unique
+/// bytes4 key in their active context.
 library Schemas {
-    string constant Unit = "#unit";
-    string constant Node = "#node { uint id }";
-    string constant Account = "#account { bytes32 account }";
-    string constant Asset = "#asset { bytes32 asset }";
-    string constant Amount = "#amount { bytes32 asset, uint amount }";
-    string constant Balance = "#balance { bytes32 asset, uint amount }";
-    string constant BalanceLimit = "#balanceLimit { bytes32 asset, uint min, uint max }";
-    string constant Custody = "#custody { uint host, bytes32 asset, uint amount }";
-    string constant CustodyLimit = "#custodyLimit { uint host, bytes32 asset, uint min, uint max }";
-    string constant Allocation = "#allocation { uint host, bytes32 asset, uint amount }";
-    string constant Allowance = "#allowance { uint host, bytes32 asset, uint amount }";
-    string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, uint amount }";
-    string constant Context = "#context { bytes32 account, #bytes as state, #bytes as request }";
-    string constant Recover = "#recover { uint handler, uint resources, bytes32 key, #bytes as witness }";
-    string constant Call = "#call { uint target, uint resources, #bytes as payload }";
-    string constant Step = "#step { uint target, uint resources, #bytes as request }";
-    string constant Relay = "#relay { uint portal, uint resources, #bytes as request }";
-    string constant Dispatch = "#dispatch { uint portal, uint resources, #bytes as payload }";
-    string constant Bounty = "#bounty { uint amount, bytes32 relayer }";
-    string constant Fee = "#fee { uint amount }";
-    string constant Auth = "#auth { uint cid, uint deadline, #bytes as proof }";
-    string constant Label = "#label { uint id, bytes32 namespace, #string as name }";
-    string constant Bytes = "#bytes";
-    string constant String = "#string";
-    string constant Data = "#data";
-    string constant List = "#list";
-    string constant Evm = "#evm";
+    string constant Unit = "";
+    string constant Node = "{ uint id }";
+    string constant Account = "{ bytes32 account }";
+    string constant Asset = "{ bytes32 asset }";
+    string constant Amount = "{ bytes32 asset, uint amount }";
+    string constant Balance = "{ bytes32 asset, uint amount }";
+    string constant BalanceLimit = "{ bytes32 asset, uint min, uint max }";
+    string constant Custody = "{ uint host, bytes32 asset, uint amount }";
+    string constant CustodyLimit = "{ uint host, bytes32 asset, uint min, uint max }";
+    string constant Allocation = "{ uint host, bytes32 asset, uint amount }";
+    string constant Allowance = "{ uint host, bytes32 asset, uint amount }";
+    string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
+    string constant Context = "{ bytes32 account, #bytes as state, #bytes as request }";
+    string constant Recover = "{ uint handler, uint resources, bytes32 key, #bytes as witness }";
+    string constant Call = "{ uint target, uint resources, #bytes as payload }";
+    string constant Step = "{ uint target, uint resources, #bytes as request }";
+    string constant Relay = "{ uint portal, uint resources, #bytes as request }";
+    string constant Dispatch = "{ uint portal, uint resources, #bytes as payload }";
+    string constant Bounty = "{ uint amount, bytes32 relayer }";
+    string constant Fee = "{ uint amount }";
+    string constant Auth = "{ uint cid, uint deadline, #bytes as proof }";
+    string constant Label = "{ uint id, bytes32 namespace, #string as name }";
+    string constant Bytes = "";
+    string constant String = "";
+    string constant List = "";
+    string constant Evm = "";
 }
 
 /// @title Forms
 /// @notice Reusable structural block schemas for core tuple shapes.
 /// These describe payload form without assigning command or query semantics.
 library Forms {
-    string constant Status = "#status { uint code }";
-    string constant AssetAmount = "#assetAmount { bytes32 asset, uint amount }";
-    string constant AccountAsset = "#accountAsset { bytes32 account, bytes32 asset }";
-    string constant AccountAmount = "#accountAmount { bytes32 account, bytes32 asset, uint amount }";
-    string constant HostAmount = "#hostAmount { uint host, bytes32 asset, uint amount }";
-    string constant HostAccountAsset = "#hostAccountAsset { uint host, bytes32 account, bytes32 asset }";
-    string constant HostAccountAmount = "#hostAccountAmount { uint host, bytes32 account, bytes32 asset, uint amount }";
+    string constant Status = "{ uint code }";
+    string constant AssetAmount = "{ bytes32 asset, uint amount }";
+    string constant AccountAsset = "{ bytes32 account, bytes32 asset }";
+    string constant AccountAmount = "{ bytes32 account, bytes32 asset, uint amount }";
+    string constant HostAmount = "{ uint host, bytes32 asset, uint amount }";
+    string constant HostAccountAsset = "{ uint host, bytes32 account, bytes32 asset }";
+    string constant HostAccountAmount = "{ uint host, bytes32 account, bytes32 asset, uint amount }";
 }
 
 /// @title Sizes