@rootzero/contracts 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.12.0
+
+### Breaking Changes
+
+- Removed the generic `EndpointBase.schema(...)` helper. Use
+  `localSchema(...)` for context-local endpoint schemas or emit `Schema`
+  directly for custom/named keys.
+- Replaced `isDebitAccount`, `isCreditAccount`, `isAuthorize`, and
+  `isUnauthorize` helper predicates with internal command ID fields:
+  `debitAccountId`, `creditAccountId`, `authorizeId`, and `unauthorizeId`.
+
+### Added
+
+- Added `Keys.Local` as the default context-local block key and added
+  `EndpointBase.localSchema(...)` helpers for publishing local endpoint
+  schemas.
+- Added the standard `#schema` block, `unpackSchema`, and an opt-in
+  `publishSchema` admin command for emitting schema claims from `#schema`
+  blocks.
+
+### Changed
+
+- Updated the schema DSL documentation to allow any number of child blocks in
+  declaration order, including fixed fields before, after, or between child
+  blocks.
+
 ## 1.11.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -31,6 +31,7 @@ import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
 import { Dismiss } from "./commands/admin/Dismiss.sol";
 import { ExecutePayable } from "./commands/admin/Execute.sol";
 import { Label } from "./commands/admin/Label.sol";
+import { PublishSchema } from "./commands/admin/Schemas.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints

package/README.md

@@ -89,8 +89,8 @@ request built for an EVM host is byte-for-byte the request a CosmWasm or Solana
 port would parse; what differs per chain is how a host *resolves* the
 identifiers inside, never how the bytes are laid out.
 
-Schemas can express more than flat fields: a block may end in nested child
-blocks (`#bytes as payload` names a run of raw dynamic bytes), items can be
+Schemas can express more than flat fields: a block may contain any number of
+nested child blocks (`#bytes as payload` names raw dynamic bytes), items can be
 marked `maybe` (optional) or `many` (a list), and aliases and dotted field
 paths give off-chain tooling presentation names without changing a single byte
 on the wire. The full schema language is specified in
@@ -332,7 +332,7 @@ bytes and produce the same output bytes for every endpoint.
 
 Admin commands use the regular command shape but are gated to the host's admin
 account: trust management (`authorize`, `unauthorize`), guardian management
-(`appoint`, `dismiss`), naming (`label`), asset gating (`allowAssets`,
+(`appoint`, `dismiss`), metadata (`label`, `publishSchema`), asset gating (`allowAssets`,
 `denyAssets`, `allowance`), lifecycle (`init`, `destroy`), and raw calls
 (`executePayable`). Guards go the other way: direct actions guardians can take
 without any command context — the default is `revoke`, which lets a guardian

package/blocks/Cursors.sol

@@ -726,6 +726,19 @@ library Cursors {
         cur.ensureAt(end);
     }
 
+    /// @notice Consume a SCHEMA block and return its fields.
+    /// @param cur Cursor; advanced past the SCHEMA block.
+    /// @return key Block key being defined.
+    /// @return body Schema DSL string describing the block payload body.
+    /// @return name Optional block alias.
+    function unpackSchema(Cur memory cur) internal pure returns (bytes4 key, string memory body, bytes32 name) {
+        uint end = cur.enter(Keys.Schema, 36 + Sizes.Header, 0);
+        key = cur.read4();
+        body = cur.unpackString();
+        name = cur.read32();
+        cur.ensureAt(end);
+    }
+
     /// @notice Consume a dynamic block with a single bytes32 payload.
     /// @param cur Cursor; advanced past the block.
     /// @param key Expected dynamic block key.

package/blocks/Keys.sol

@@ -21,6 +21,8 @@ library Keys {
     bytes4 constant Empty = bytes4(0);
     /// @dev Wildcard key used in discovery when any block stream is accepted.
     bytes4 constant Any = 0xffffffff;
+    /// @dev Default context-local block key for hosts/endpoints that need one custom schema.
+    bytes4 constant Local = bytes4(uint32(1));
     /// @dev Input amount - (bytes32 asset, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
@@ -71,6 +73,8 @@ library Keys {
     bytes4 constant Bounty = bytes4(keccak256("#bounty"));
     /// @dev Mutable node label - (uint id, bytes32 namespace, #string as name)
     bytes4 constant Label = bytes4(keccak256("#label"));
+    /// @dev Block schema publication - (bytes4 key, #string as body, bytes32 name)
+    bytes4 constant Schema = bytes4(keccak256("#schema"));
 
     /// @dev Structural status form - (uint code)
     bytes4 constant Status = bytes4(keccak256("#status"));

package/blocks/Schema.sol

@@ -28,9 +28,9 @@ pragma solidity ^0.8.33;
 //   are offchain projection metadata only and do not change runtime encoding
 // - 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
+// - items are encoded in declaration order
+// - fixed fields are packed inline and any number of child blocks are embedded directly
+// - child blocks may appear between fixed fields because each block carries its own length
 // - `#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 lists use the stable key derived from `#list`
@@ -87,6 +87,7 @@ library Schemas {
     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 Schema = "{ bytes4 key, #string as body, bytes32 name }";
     string constant Bytes = "";
     string constant String = "";
     string constant List = "";

package/commands/Credit.sol

@@ -20,15 +20,10 @@ abstract contract CreditAccountHook {
 /// Use for internally recording credits that have already been settled externally.
 abstract contract CreditAccount is CommandBase, CreditAccountHook {
     bytes32 private immutable descriptor;
-    uint private immutable id;
+    uint internal immutable creditAccountId;
 
     constructor() {
-        (id, descriptor) = command("creditAccount", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
-    }
-
-    /// @notice Return true if `candidate` is this command's credit account ID.
-    function isCreditAccount(uint candidate) internal view returns (bool) {
-        return candidate == id;
+        (creditAccountId, descriptor) = command("creditAccount", Keys.Balance, Keys.Empty, Keys.Empty, 0, false, false);
     }
 
     /// @notice Credit each BALANCE block from the command state to the command account.

package/commands/Debit.sol

@@ -22,15 +22,10 @@ abstract contract DebitAccountHook {
 /// AMOUNT block; the default batch implementation handles the full request loop.
 abstract contract DebitAccount is CommandBase, DebitAccountHook {
     bytes32 private immutable descriptor;
-    uint private immutable id;
+    uint internal immutable debitAccountId;
 
     constructor() {
-        (id, descriptor) = command("debitAccount", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
-    }
-
-    /// @notice Return true if `candidate` is this command's debit account ID.
-    function isDebitAccount(uint candidate) internal view returns (bool) {
-        return candidate == id;
+        (debitAccountId, descriptor) = command("debitAccount", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
     }
 
     /// @notice Override to customize request parsing or batching for debits.

package/commands/admin/Authorize.sol

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur } from "../../Cursors.sol";
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Authorize
@@ -11,17 +11,16 @@ using Cursors for Cur;
 /// Only callable by the admin account.
 abstract contract Authorize is AdminBase {
     bytes32 private immutable descriptor;
+    uint internal immutable authorizeId;
 
     constructor() {
-        (, descriptor) = command("authorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
+        (authorizeId, descriptor) = command("authorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
     }
 
     /// @notice Authorize each NODE block in the admin request.
     /// @param c Admin command context; `c.input` must contain NODE blocks.
     /// @return Empty output state.
-    function authorize(
-        CommandContext calldata c
-    ) external onlyAdmin(c.account) returns (bytes memory) {
+    function authorize(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
         (Cur memory input, ) = openInput(c.input, descriptor);
 
         while (input.i < input.len) {
@@ -31,8 +30,3 @@ abstract contract Authorize is AdminBase {
         return "";
     }
 }
-
-
-
-
-

package/commands/admin/Schemas.sol

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
+using Cursors for Cur;
+
+/// @title PublishSchema
+/// @notice Admin command that publishes block schemas for keys.
+/// Each SCHEMA block in the request emits one `Schema` event. Only callable by
+/// the admin account.
+abstract contract PublishSchema is AdminBase {
+    bytes32 private immutable descriptor;
+
+    constructor() {
+        (, descriptor) = command("publishSchema", Keys.Empty, Keys.Schema, Keys.Empty, 0, false, true);
+    }
+
+    /// @notice Publish each SCHEMA block in the admin request.
+    /// @param c Admin command context; `c.input` must contain SCHEMA blocks.
+    /// @return Empty output state.
+    function publishSchema(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
+        (Cur memory input, ) = openInput(c.input, descriptor);
+
+        while (input.i < input.len) {
+            (bytes4 key, string memory body, bytes32 name) = input.unpackSchema();
+            emit Schema(host, key, body, name);
+        }
+        return "";
+    }
+}

package/commands/admin/Unauthorize.sol

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, CommandContext, Keys } from "./Base.sol";
-import { Cursors, Cur } from "../../Cursors.sol";
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
+import {Cursors, Cur} from "../../Cursors.sol";
 using Cursors for Cur;
 
 /// @title Unauthorize
@@ -11,17 +11,16 @@ using Cursors for Cur;
 /// Only callable by the admin account.
 abstract contract Unauthorize is AdminBase {
     bytes32 private immutable descriptor;
+    uint internal immutable unauthorizeId;
 
     constructor() {
-        (, descriptor) = command("unauthorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
+        (unauthorizeId, descriptor) = command("unauthorize", Keys.Empty, Keys.Node, Keys.Empty, 0, false, true);
     }
 
     /// @notice Unauthorize each NODE block in the admin request.
     /// @param c Admin command context; `c.input` must contain NODE blocks.
     /// @return Empty output state.
-    function unauthorize(
-        CommandContext calldata c
-    ) external onlyAdmin(c.account) returns (bytes memory) {
+    function unauthorize(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
         (Cur memory input, ) = openInput(c.input, descriptor);
 
         while (input.i < input.len) {
@@ -31,8 +30,3 @@ abstract contract Unauthorize is AdminBase {
         return "";
     }
 }
-
-
-
-
-

package/core/Endpoint.sol

@@ -118,14 +118,21 @@ abstract contract EndpointBase is Runtime, EndpointEvent, LabeledEvent, SchemaEv
         (input, , outputs) = openLane(source, descriptor, Lane.Input, 0);
     }
 
-    /// @notice Publish a block schema and return its key for descriptor construction.
-    /// @param key Block key being defined.
+    /// @notice Publish the default local block schema and return `Keys.Local`.
     /// @param body Schema DSL string describing the block payload body.
-    /// @param name Optional block alias used by descriptor tooling and nested schemas.
-    /// @return The same block key, for inline descriptor construction.
-    function schema(bytes4 key, string memory body, bytes32 name) internal returns (bytes4) {
-        emit Schema(host, key, body, name);
-        return key;
+    /// @return The default context-local block key.
+    function localSchema(string memory body) internal returns (bytes4) {
+        return localSchema(1, body);
+    }
+
+    /// @notice Publish a context-local block schema and return its key.
+    /// @param key Context-local key value.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @return The context-local block key.
+    function localSchema(uint32 key, string memory body) internal returns (bytes4) {
+        bytes4 k = Keys.local(key);
+        emit Schema(host, k, body, bytes32(0));
+        return k;
     }
 
     /// @notice Create and publish endpoint metadata with a default label.

package/core/Host.sol

@@ -23,7 +23,7 @@ interface IHostIntroduction {
 
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
-/// Inherits admin command support (authorize, unauthorize, executePayable),
+/// Inherits admin command support (authorize, unauthorize, label, executePayable),
 /// guardian management, the default guardian revoke action, and
 /// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.

package/docs/Schema.md

@@ -33,7 +33,7 @@ used. A host can publish the meaning of a custom key with:
 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
+For example, a host-specific payment block can use `Keys.Local`, the command
 selector, or any other chosen `bytes4` value as long as that key is not
 overloaded in the relevant host/schema context.
 
@@ -65,16 +65,19 @@ A schema body is a comma-separated list of items. Order is significant.
 
 ## Payload Layout
 
-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.
+A block payload encodes schema items in declaration order. Fixed fields are
+packed inline, and zero or more child blocks are embedded directly at their
+declared positions. Because every child block carries its own header and payload
+length, fixed fields may appear before, after, or between child blocks.
 
 ```txt
 { uint target, uint resources, #bytes as payload }
 { bytes32 account, #bytes as state, #bytes as request }
+{ bytes4 key, #string as body, bytes32 name }
+{ #bytes as left, uint op, #bytes as right }
 ```
 
-The tail is embedded directly as child block bytes. There is no wrapper around a
-child-block tail.
+There is no wrapper around embedded child blocks.
 
 Raw dynamic bytes are represented with the reserved `#bytes` child block. Use an
 alias to give those bytes a presentation name:
@@ -293,19 +296,21 @@ invalid in any path segment.
 ## Reserved Blocks
 
 - `#bytes`: raw dynamic bytes, written without a body
+- `#string`: UTF-8 string bytes, written without a body
 - `#list`: generic list wrapper emitted by `many`
 
 Custom input shapes should define their own context-local block key and publish
 that key with a `Schema` event:
 
 ```solidity
-bytes4 constant Input = Keys.local(1);
+bytes4 constant Input = Keys.Local;
 emit Schema(host, Input, "{ bytes32 asset, uint amount }", bytes32("payment"));
 ```
 
-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.
+Use `Keys.local(n)` when a host needs more than one local block key. The key can
+also 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
 
@@ -320,6 +325,7 @@ 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 }
+schema   { bytes4 key, #string as body, bytes32 name }
 ```
 
 `Keys.sol` contains the corresponding standard runtime keys.

package/package.json

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