@rootzero/contracts 1.13.0 → 1.14.0

package/docs/Schema.md

@@ -1,6 +1,6 @@
 # Schema
 
-Rootzero request and response data is encoded as a stream of typed blocks. A
+Rootzero input and response data is encoded as a stream of typed blocks. A
 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
@@ -30,7 +30,7 @@ are opaque `bytes4` tags and only need to be unique in the context where they ar
 used. A host can publish the meaning of a custom key with:
 
 ```solidity
-event Schema(uint indexed host, bytes4 key, string schema, bytes32 name);
+event Schema(uint indexed host, uint spec, string body, bytes32 name);
 ```
 
 For example, a host-specific payment block can use a small literal, the command
@@ -50,7 +50,7 @@ schema: { bytes32 asset, uint amount }
 A block body can reference another block alias as a child item with `#`:
 
 ```txt
-{ bytes32 account, #bytes as state, #bytes as request }
+{ bytes32 account, #bytes as state, #bytes as input }
 ```
 
 The empty schema string `""` means the block has no structured payload. This is
@@ -72,8 +72,8 @@ 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 }
+{ bytes32 account, #bytes as state, #bytes as input }
+{ uint spec, #string as body, bytes32 name }
 { #bytes as left, uint op, #bytes as right }
 ```
 
@@ -108,24 +108,30 @@ generic list block; it does not repeat the item in place.
 ## 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.
+Solidity, endpoint definition helpers accept block specs such as `Specs.Amount`.
+A zero group is interpreted as group size 1, while `Specs.Empty` means the
+endpoint has no blocks in that lane. Use `group(spec, size)` when a lane needs
+an explicit group size other than 1.
 
-The packed descriptor stores each lane key as an 8-byte value:
+The packed descriptor uses these lane layouts:
 
 ```txt
-[key bytes4][item bytes4]
+state   [key:4][group:1]
+input   [key:4][item:4][group:1]
+output  [key:4][min:4][max:4][hint:4][group:1]
 ```
 
-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`.
+Containers are exclusive to input. A plain input spec is compressed into
+`[spec.key][0]`. A spec with a nonzero container is compressed into
+`[spec.container][spec.key]`: the container is the top-level wire key and the
+item is its contained block key. The built-in `many(spec)` helper annotates the
+spec with `Specs.List` as its container, matching the DSL form `many #item`.
+Output lanes retain their size bounds and allocation hint so execution can
+reconstruct the output spec and initialize its writer directly. The Solidity
+output decoder returns this as a left-aligned, writer-ready spec that retains
+its encoded group. Its container and reserved fields are cleared. `Specs.group`
+returns the effective group, interpreting an encoded zero as one for a
+non-empty spec.
 
 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
@@ -299,33 +305,33 @@ invalid in any path segment.
 - `#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. Endpoint contracts can use `schema(...)` for
-that publication:
+Custom input shapes should define their own context-local block spec and publish
+it with a `Schema` event. Endpoint contracts can use `schema(...)` to construct
+and publish that spec:
 
 ```solidity
-bytes4 input = schema(1, "{ bytes32 asset, uint amount }");
+uint input = schema(1, 64, 64, 64, "{ bytes32 asset, uint amount }", bytes32(0));
 ```
 
 Use different numeric keys when a host needs more than one local block key. The
 key can also be 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.
+context where it is used. The numeric arguments after the key are the minimum,
+maximum, and allocation hint payload sizes. The alias names the block; the
+schema string describes only the payload body.
 
 ## Standard Blocks
 
-Common protocol schemas live in `contracts/blocks/Schema.sol`:
+Common protocol schemas live in `contracts/codec/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 }
+step     { uint cmd, uint resources, #bytes as input }
+context  { bytes32 account, #bytes as state, #bytes as input }
 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 }
+schema   { uint spec, #string as body, bytes32 name }
 ```
 
 `Keys.sol` contains the corresponding standard runtime keys.

package/events/Endpoint.sol

@@ -6,12 +6,12 @@ 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)";
+    string private constant ABI = "event Endpoint(uint indexed host, uint id, uint 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);
+    event Endpoint(uint indexed host, uint id, uint descriptor);
 
     constructor() {
         emit EventAbi(ABI);

package/events/Schema.sol

@@ -4,18 +4,18 @@ 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.
+/// @notice Emitted during host deployment to publish a block spec 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)";
+    string private constant ABI = "event Schema(uint indexed host, uint spec, string body, 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 spec Block specification being defined by `host`.
+    /// @param body 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);
+    event Schema(uint indexed host, uint spec, string body, bytes32 name);
 
     constructor() {
         emit EventAbi(ABI);

package/execution/Budget.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @notice Mutable native-value budget shared across internal calls.
+struct Budget {
+    /// @dev Remaining unspent native value in wei.
+    uint remaining;
+}
+
+/// @title Budgets
+/// @notice Opening and mutation helpers for standalone native-value budgets.
+library Budgets {
+    /// @dev Thrown when an operation attempts to spend more value than remains.
+    error InsufficientValue();
+
+    /// @notice Open a standalone budget containing the current call value.
+    /// @return budget Budget initialized with `msg.value`.
+    function open() internal view returns (Budget memory budget) {
+        budget.remaining = msg.value;
+    }
+
+    /// @notice Deduct the EVM value lane of `resources` from `budget`.
+    /// @dev EVM resources use the low 128 bits as native value/endowment.
+    /// @param budget Mutable budget to debit.
+    /// @param resources Packed resources whose low 128 bits contain native value.
+    /// @return value Native value to forward in wei.
+    function use(Budget memory budget, uint resources) internal pure returns (uint128 value) {
+        value = uint128(resources);
+        if (value > budget.remaining) revert InsufficientValue();
+        budget.remaining -= value;
+    }
+
+    /// @notice Remove and return all remaining value from `budget`.
+    /// @param budget Mutable budget to drain.
+    /// @return value Native value removed from the budget.
+    function drain(Budget memory budget) internal pure returns (uint value) {
+        value = budget.remaining;
+        budget.remaining = 0;
+    }
+}