@rootzero/contracts 1.10.0 → 1.11.0

package/docs/Schema.md

@@ -1,8 +1,10 @@
 # Schema
 
 Rootzero request and response data is encoded as a stream of typed blocks. A
-schema string describes payload layout for discovery events and tooling; the
-runtime block key is derived only from the block name.
+schema string describes the payload body for discovery events and tooling; the
+runtime block key is the compact type tag that identifies that payload layout in
+the active schema context. The block alias is published separately from the
+payload schema.
 
 ## Wire Format
 
@@ -15,39 +17,50 @@ Every block uses the same header:
 `payloadLen` is big-endian and counts only payload bytes. Child blocks and list
 items use the same header format.
 
-The block key is:
+Standard built-in block keys use:
 
 ```txt
 bytes4(keccak256("#name"))
 ```
 
-For example, `#amount { bytes32 asset, uint amount }` uses the key
-derived from `#amount`. Blocks must not be overloaded: one block name should have
-one protocol meaning.
+For example, the standard `amount` alias uses the key derived from `#amount`
+and the schema body `{ bytes32 asset, uint amount }`. Custom block keys do not
+have to be keccak-derived. They
+are opaque `bytes4` tags and only need to be unique in the context where they are
+used. A host can publish the meaning of a custom key with:
+
+```solidity
+event Schema(uint indexed host, bytes4 key, string schema, bytes32 name);
+```
+
+For example, a host-specific payment block can use `Keys.local(1)`, the command
+selector, or any other chosen `bytes4` value as long as that key is not
+overloaded in the relevant host/schema context.
 
 ## Block Syntax
 
-A block starts with `#`. Fixed fields are written in braces:
+A block definition has an event alias and a schema body. Fixed fields are
+written in braces:
 
 ```txt
-#amount { bytes32 asset, uint amount }
-#account { bytes32 account }
+alias:  amount
+schema: { bytes32 asset, uint amount }
 ```
 
-A block without braces has no payload:
+A block body can reference another block alias as a child item with `#`:
 
 ```txt
-#unit
-#bytes
+{ bytes32 account, #bytes as state, #bytes as request }
 ```
 
-Empty braces are invalid. A zero-payload block must omit braces.
+The empty schema string `""` means the block has no structured payload. This is
+used for zero-payload blocks such as `#unit` and raw dynamic blocks such as
+`#bytes`.
 
-A schema is a comma-separated list of items. Order is significant.
+A schema body is a comma-separated list of items. Order is significant.
 
 ```txt
-#amount { bytes32 asset, uint amount },
-maybe #account { bytes32 account }
+{ #amount, maybe #account as recipient }
 ```
 
 ## Payload Layout
@@ -56,8 +69,8 @@ A block payload has fixed fields first, followed by an optional child-block tail
 Once a child block appears, no more fixed fields may follow.
 
 ```txt
-#call { uint target, uint resources, #bytes as payload }
-#context { bytes32 account, #bytes as state, #bytes as request }
+{ uint target, uint resources, #bytes as payload }
+{ bytes32 account, #bytes as state, #bytes as request }
 ```
 
 The tail is embedded directly as child block bytes. There is no wrapper around a
@@ -75,59 +88,87 @@ alias to give those bytes a presentation name:
 Cardinality is expressed with prefix keywords:
 
 ```txt
-#balance { bytes32 asset, uint amount }
-maybe #balance { bytes32 asset, uint amount }
-many #balance { bytes32 asset, uint amount }
-maybe many #balance { bytes32 asset, uint amount }
+#balance
+maybe #balance
+many #balance
+maybe many #balance
 ```
 
 - no prefix: one required item
 - `maybe`: optional item
-- `many`: one `#list` block whose payload contains repeated items
+- `many`: one generic `#list` block whose payload contains repeated items
 - `maybe many`: optional `#list` block
 
 `maybe` emits no placeholder when absent. `many` wraps repeated items in one
 generic list block; it does not repeat the item in place.
 
-## Prime Items
+## Endpoint Lanes
+
+Endpoint descriptors identify each lane with a block key and group size. In
+Solidity, endpoint definition helpers accept `bytes9` lane values, with plain
+`bytes4` keys and the `bytes8` values returned by `many(item)` widening
+implicitly. A plain key or `many(item)` stores a zero group byte that readers
+interpret as group size 1, while `bytes9(0)` or `Keys.Empty` means the endpoint
+has no blocks in that lane. Use
+`group(lane, size)` when a lane needs an explicit group size other than 1.
+
+The packed descriptor stores each lane key as an 8-byte value:
+
+```txt
+[key bytes4][item bytes4]
+```
+
+A plain block key is widened into `[key][0]`, so normal endpoint declarations can
+pass standard `bytes4` keys directly. A lane with a nonzero `item` describes a
+generic container block: `key` is the top-level wire key and `item` is the
+contained item key. The built-in `many(item)` helper creates `[Keys.List][item]`
+with the default group size 1, matching the DSL form `many #item`.
 
-The empty string `""` means no schema. Whitespace-only schemas are invalid.
+Any non-empty lane resolves its key to a block alias and schema body through the
+active schema context. If the item slot is nonzero, tooling also resolves that
+item key in the same context. A bare list lane, `[Keys.List][0]`, is incomplete
+discovery metadata because it does not say what the list contains; indexers
+should reject it for self-describing endpoints.
 
-For a non-empty schema, the first top-level item is the prime item. Prime items
-may repeat at the top level for batching. Later top-level items are globals for
-the whole batch and are not counted as per-operation prime blocks.
+The lane key is the prime item. Prime items may repeat at the top level for
+batching. When the lane is `many #item`, the repeated prime item is the generic
+LIST block and each LIST payload contains repeated `item` blocks. Later
+top-level items are globals for the whole batch and are not counted as
+per-operation prime blocks.
 
-The prime item cannot be optional. If a command needs a per-operation marker with
-no payload, use a zero-payload block such as `#unit`.
+The prime item cannot be optional. If an endpoint needs a per-operation marker
+with no payload, use a zero-payload block such as `#unit`.
 
-Command request and state streams currently use a narrower convention than the
-full block grammar: each is a single run of blocks, without additional global
-items. Future protocol surfaces may use the more flexible top-level structure,
-but command discovery metadata should describe only that one-run shape.
+Endpoint descriptors currently use a narrower convention than the full block
+grammar: each state, input, or output lane is a single run of blocks, without
+additional global items. Future protocol surfaces may use the more flexible
+top-level structure.
 
-## Aliases
+## Field Aliases
 
-Aliases are presentation metadata for tooling. They do not change payload layout
-or runtime keys.
+Block aliases are published in `Schema` events. Field aliases are presentation
+metadata for tooling. They do not change payload layout or runtime keys.
 
 ```txt
-maybe #account { bytes32 account } as recipient
-#call { uint target, uint resources, #bytes as payload }
+maybe #account as recipient
+{ uint target, uint resources, #bytes as payload }
 ```
 
-Aliases may be used on any block item, including child blocks and prime items.
+Field aliases may be used on any block item, including child blocks and prime
+items.
 
-A child block without an inline body may also be used as a schema reference:
+Child blocks are schema references:
 
 ```txt
-#recover { uint handler, uint resources, bytes32 key, #bytes as witness }
+{ uint handler, uint resources, bytes32 key, #bytes as witness }
 ```
 
-Alias resolution is context-dependent. A consumer may resolve `#context` from the
-standard `Schemas` table, from app-specific schemas, or from another active
-schema context. Consumers should reject schemas with unresolved aliases. The
-runtime encoding is still an embedded child block with the referenced key and
-layout.
+Alias resolution is context-dependent. A consumer may resolve `#context` from
+standard block events, from app-specific block events, or from another active
+schema context. Custom parents should define nested custom blocks from the
+bottom up and reference them by alias. Consumers should reject schemas with
+unresolved aliases. The runtime encoding is still an embedded child block with
+the referenced key and layout.
 
 ## Field Paths
 
@@ -136,13 +177,13 @@ path does not change the block key, payload bytes, payload length, cursor
 behavior, or any onchain validation. It is metadata only.
 
 ```txt
-#dispatch { uint dst.portal, uint dst.resources, #bytes as dst.payload }
+{ uint dst.portal, uint dst.resources, #bytes as dst.payload }
 ```
 
 This has the same runtime layout as:
 
 ```txt
-#dispatch { uint portal, uint resources, #bytes as payload }
+{ uint portal, uint resources, #bytes as payload }
 ```
 
 Offchain tooling may decode the dotted form into a nested object:
@@ -169,11 +210,11 @@ uint dst.portal, uint dst.portal    // duplicate path
 uint dst, uint dst.portal           // prefix/value collision
 ```
 
-The same rule applies to block aliases:
+The same rule applies to field aliases:
 
 ```txt
-#call { uint target, uint resources, #bytes as calldata.payload }
-maybe #account { bytes32 account } as recipient.account
+{ uint target, uint resources, #bytes as calldata.payload }
+maybe #account as recipient.account
 ```
 
 ## Field Types
@@ -226,8 +267,8 @@ the layout of an ID only apply to structured IDs.
 
 ## Identifiers
 
-Block names use lower camelCase ASCII identifiers. Field names and aliases use
-one or more lower camelCase path segments separated by dots:
+Block aliases use lower camelCase ASCII identifiers. Field names and aliases
+use one or more lower camelCase path segments separated by dots:
 
 ```txt
 [a-z][a-zA-Z0-9]*
@@ -246,48 +287,39 @@ asset.
 ```
 
 Reserved words include `maybe`, `many`, `as`, all field type names, and the
-reserved block names `bytes`, `data`, and `list`. For dotted paths, reserved
-words are invalid in any path segment.
+reserved block aliases `bytes` and `list`. For dotted paths, reserved words are
+invalid in any path segment.
 
 ## Reserved Blocks
 
 - `#bytes`: raw dynamic bytes, written without a body
-- `#data`: generic/custom payload block
 - `#list`: generic list wrapper emitted by `many`
 
-Use `#data` when a local schema needs a stable generic key:
+Custom input shapes should define their own context-local block key and publish
+that key with a `Schema` event:
 
-```txt
-#data { uint foo, bytes32 tag }
-#data { #bytes as payload }
-```
-
-If a schema string starts with a fixed field type, it is shorthand for one
-top-level `#data` block:
-
-```txt
-uint foo, bytes32 tag
+```solidity
+bytes4 constant Input = Keys.local(1);
+emit Schema(host, Input, "{ bytes32 asset, uint amount }", bytes32("payment"));
 ```
 
-expands to:
-
-```txt
-#data { uint foo, bytes32 tag }
-```
+The key can be a small literal, a selector, or any other `bytes4` value that is
+unique in the context where it is used. The alias names the block; the schema
+string describes only the payload body.
 
 ## Standard Blocks
 
 Common protocol schemas live in `contracts/blocks/Schema.sol`:
 
 ```txt
-#amount { bytes32 asset, uint amount }
-#balance { bytes32 asset, uint amount }
-#custody { uint host, bytes32 asset, uint amount }
-#call { uint target, uint resources, #bytes as payload }
-#step { uint target, uint resources, #bytes as request }
-#context { bytes32 account, #bytes as state, #bytes as request }
-#recover { uint handler, uint resources, bytes32 key, #bytes as witness }
-#auth { uint cid, uint deadline, #bytes as proof }
+amount   { bytes32 asset, uint amount }
+balance  { bytes32 asset, uint amount }
+custody  { uint host, bytes32 asset, uint amount }
+call     { uint target, uint resources, #bytes as payload }
+step     { uint target, uint resources, #bytes as request }
+context  { bytes32 account, #bytes as state, #bytes as request }
+recover  { uint handler, uint resources, bytes32 key, #bytes as witness }
+auth     { uint cid, uint deadline, #bytes as proof }
 ```
 
-`Keys.sol` contains the corresponding runtime keys.
+`Keys.sol` contains the corresponding standard runtime keys.

package/events/Endpoint.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @title EndpointEvent
+/// @notice Emitted during host deployment to publish a callable endpoint descriptor.
+abstract contract EndpointEvent is EventEmitter {
+    string private constant ABI = "event Endpoint(uint indexed host, uint id, bytes32 descriptor)";
+
+    /// @param host Host node ID that exposes the endpoint.
+    /// @param id Endpoint node ID.
+    /// @param descriptor Packed endpoint lane metadata and flags.
+    event Endpoint(uint indexed host, uint id, bytes32 descriptor);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Schema.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @title SchemaEvent
+/// @notice Emitted during host deployment to publish a block key and payload schema.
+/// Block keys are opaque `bytes4` tags. Standard protocol blocks use
+/// keccak-derived keys by convention, but custom block keys only need to be
+/// unique within the publishing host/schema context.
+abstract contract SchemaEvent is EventEmitter {
+    string private constant ABI = "event Schema(uint indexed host, bytes4 key, string schema, bytes32 name)";
+
+    /// @param host Host node ID that publishes this block schema.
+    /// @param key Block type key being defined by `host`.
+    /// @param schema Schema DSL string describing the block payload body.
+    /// @param name Optional block alias used by endpoint descriptors and nested schemas.
+    event Schema(uint indexed host, bytes4 key, string schema, bytes32 name);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/guards/Base.sol

@@ -2,24 +2,33 @@
 pragma solidity ^0.8.33;
 
 import {AccessControl} from "../core/Access.sol";
-import {GuardEvent} from "../events/Guard.sol";
-import {LabeledEvent} from "../events/Labeled.sol";
+import {EndpointBase} from "../core/Endpoint.sol";
 import {Nodes} from "../utils/Nodes.sol";
+import {Selectors} from "../utils/Selectors.sol";
 
 /// @title GuardBase
 /// @notice Abstract base for guardian-only direct host actions.
 /// Guard actions are non-payable direct calls with no command context, state, or response.
-abstract contract GuardBase is AccessControl, GuardEvent, LabeledEvent {
+abstract contract GuardBase is AccessControl, EndpointBase {
     /// @dev Restrict execution to active guardian addresses.
     modifier onlyGuardian() {
         if (!isGuardian(msg.sender)) revert AccessDenied();
         _;
     }
 
-    /// @notice Derive the deterministic node ID for a guard action selector on this contract.
-    /// @param selector Guard action entrypoint selector.
-    /// @return Guard action node ID.
-    function guardId(bytes4 selector) internal view returns (uint) {
-        return Nodes.toGuard(selector, address(this));
+    /// @notice Publish guard metadata and a default label.
+    /// @param name Default human-readable guard label and selector name.
+    /// @param input Packed input lane plus optional group byte.
+    /// @param selector Guard ABI selector, or zero to derive it from `name`.
+    /// @return id Guard action node ID.
+    /// @return descriptor Packed endpoint lane metadata and flags.
+    function guard(
+        string memory name,
+        bytes9 input,
+        bytes4 selector
+    ) internal returns (uint id, bytes32 descriptor) {
+        selector = selector == bytes4(0) ? Selectors.guard(name) : selector;
+        id = Nodes.toGuard(selector, address(this));
+        descriptor = endpoint(id, name, bytes9(0), input, bytes9(0), false, false);
     }
 }

package/guards/Revoke.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {GuardBase} from "./Base.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Cursors, Cur, Keys} from "../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Revoke
@@ -10,21 +10,19 @@ using Cursors for Cur;
 /// Each NODE block in the request is deauthorized on the host.
 /// Only callable by active guardian addresses.
 abstract contract Revoke is GuardBase {
-    uint internal immutable revokeId = guardId(this.revoke.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Guard(host, revokeId, Schemas.Node);
-        emit Labeled(revokeId, bytes32(0), "revoke");
+        (, descriptor) = guard("revoke", Keys.Node, 0);
     }
 
     function revoke(bytes calldata request) external onlyGuardian {
-        (Cur memory input, ) = Cursors.init(request, 1);
+        (Cur memory input, ) = openInput(request, descriptor);
 
         while (input.i < input.len) {
             uint node = input.unpackNode();
             setNode(node, false);
         }
 
-        input.complete();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/ports/AllowAssets.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
 import { AllowAssetsHook } from "../commands/admin/AllowAssets.sol";
-import { Cursors, Cur, Schemas } from "../Cursors.sol";
+import { Cursors, Cur, Keys } from "../Cursors.sol";
 
 using Cursors for Cur;
 
@@ -11,25 +11,22 @@ using Cursors for Cur;
 /// @notice Port that permits a list of assets on behalf of a peer host.
 /// Each ASSET block in the request calls `allowAsset`. Restricted to trusted peers.
 abstract contract PortAllowAssets is PortBase, AllowAssetsHook {
-    uint internal immutable portAllowAssetsId = portId(this.portAllowAssets.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Port(host, portAllowAssetsId, "1:0", Schemas.Asset, "", false);
-        emit Labeled(portAllowAssetsId, bytes32(0), "portAllowAssets");
+        (, descriptor) = port("portAllowAssets", Keys.Asset, Keys.Empty, 0, false);
     }
 
     /// @notice Execute the allow-assets peer call.
     /// @param data ASSET block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portAllowAssets(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory assets, ) = Cursors.init(data, 1);
+        (Cur memory input, ) = openInput(data, descriptor);
 
-        while (assets.i < assets.len) {
-            bytes32 asset = assets.unpackAsset();
+        while (input.i < input.len) {
+            bytes32 asset = input.unpackAsset();
             allowAsset(asset);
         }
-
-        assets.complete();
         return "";
     }
 }

package/ports/Allowance.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
 import {AllowanceHook} from "../commands/admin/Allowance.sol";
-import {Cursors, Cur, Schemas} from "../Cursors.sol";
+import {Cursors, Cur, Keys} from "../Cursors.sol";
 
 using Cursors for Cur;
 
@@ -12,26 +12,23 @@ using Cursors for Cur;
 /// Each AMOUNT block in the request is scoped to the peer host and passed to the
 /// shared allowance hook as a host-scoped allowance. Restricted to trusted peers.
 abstract contract PortAllowance is PortBase, AllowanceHook {
-    uint internal immutable portAllowanceId = portId(this.portAllowance.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Port(host, portAllowanceId, "1:0", Schemas.Amount, "", false);
-        emit Labeled(portAllowanceId, bytes32(0), "portAllowance");
+        (, descriptor) = port("portAllowance", Keys.Amount, Keys.Empty, 0, false);
     }
 
     /// @notice Execute the allowance port call.
     /// @param data AMOUNT block stream requested by the trusted peer.
     /// @return Empty response bytes.
     function portAllowance(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory amounts, ) = Cursors.init(data, 1);
+        (Cur memory input, ) = openInput(data, descriptor);
         uint peer = caller();
 
-        while (amounts.i < amounts.len) {
-            (bytes32 asset, uint amount) = amounts.unpackAmount();
+        while (input.i < input.len) {
+            (bytes32 asset, uint amount) = input.unpackAmount();
             allowance(peer, asset, amount);
         }
-
-        amounts.complete();
         return "";
     }
 }

package/ports/Base.sol

@@ -2,15 +2,15 @@
 pragma solidity ^0.8.33;
 
 import { NodeCalls } from "../core/Calls.sol";
-import { PortEvent } from "../events/Port.sol";
-import { LabeledEvent } from "../events/Labeled.sol";
+import { EndpointBase } from "../core/Endpoint.sol";
 import { Nodes } from "../utils/Nodes.sol";
+import { Selectors } from "../utils/Selectors.sol";
 
 /// @title PortBase
 /// @notice Abstract base for peer-facing rootzero ports.
 /// Ports handle inter-host operations between cooperating hosts.
 /// Access is restricted to trusted peer callers via `onlyPeer`.
-abstract contract PortBase is NodeCalls, PortEvent, LabeledEvent {
+abstract contract PortBase is NodeCalls, EndpointBase {
     /// @dev Thrown when the commander attempts to call a port entrypoint directly.
     error CommanderNotAllowed();
 
@@ -21,10 +21,23 @@ abstract contract PortBase is NodeCalls, PortEvent, LabeledEvent {
         _;
     }
 
-    /// @notice Derive the deterministic node ID for a port selector on this contract.
-    /// @param selector Port entrypoint selector.
-    /// @return Port node ID.
-    function portId(bytes4 selector) internal view returns (uint) {
-        return Nodes.toPort(selector, address(this));
+    /// @notice Publish port metadata and a default label.
+    /// @param name Default human-readable port label and selector name.
+    /// @param input Packed input lane plus optional group byte.
+    /// @param output Packed output lane plus optional group byte.
+    /// @param selector Port ABI selector, or zero to derive it from `name`.
+    /// @param funded Whether the port accepts nonzero native value.
+    /// @return id Port node ID.
+    /// @return descriptor Packed endpoint lane metadata and flags.
+    function port(
+        string memory name,
+        bytes9 input,
+        bytes9 output,
+        bytes4 selector,
+        bool funded
+    ) internal returns (uint id, bytes32 descriptor) {
+        selector = selector == bytes4(0) ? Selectors.port(name) : selector;
+        id = Nodes.toPort(selector, address(this));
+        descriptor = endpoint(id, name, bytes9(0), input, output, funded, false);
     }
 }

package/ports/Credit.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
 import { CreditAccountHook } from "../commands/Credit.sol";
-import { Cursors, Cur, Forms } from "../Cursors.sol";
+import { Cursors, Cur, Keys } from "../Cursors.sol";
 
 using Cursors for Cur;
 
@@ -11,25 +11,22 @@ using Cursors for Cur;
 /// @notice Port that lets a trusted peer credit supplied accounts directly.
 /// Each ACCOUNT_AMOUNT block calls `creditAccount` for its account.
 abstract contract PortCreditAccount is PortBase, CreditAccountHook {
-    uint internal immutable portCreditAccountId = portId(this.portCreditAccount.selector);
+    bytes32 private immutable descriptor;
 
     constructor() {
-        emit Port(host, portCreditAccountId, "1:0", Forms.AccountAmount, "", false);
-        emit Labeled(portCreditAccountId, bytes32(0), "portCreditAccount");
+        (, descriptor) = port("portCreditAccount", Keys.AccountAmount, Keys.Empty, 0, false);
     }
 
     /// @notice Execute the port-credit call.
     /// @param data ACCOUNT_AMOUNT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portCreditAccount(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory amounts, ) = Cursors.init(data, 1);
+        (Cur memory input, ) = openInput(data, descriptor);
 
-        while (amounts.i < amounts.len) {
-            (bytes32 account, bytes32 asset, uint amount) = amounts.unpackAccountAmount();
+        while (input.i < input.len) {
+            (bytes32 account, bytes32 asset, uint amount) = input.unpackAccountAmount();
             creditAccount(account, asset, amount);
         }
-
-        amounts.complete();
         return "";
     }
 }