@rootzero/contracts 0.9.2 → 0.9.4

package/blocks/Keys.sol

@@ -1,88 +1,69 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Forms} from "./Schema.sol";
-
 /// @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 schema string,
-/// matching the ABI-selector convention used in `Schemas`.
+/// Each key is the first 4 bytes of the keccak256 hash of its block name.
 library Keys {
     /// @dev Empty / unset key.
     bytes4 constant Empty = bytes4(0);
     /// @dev Input amount - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Amount = bytes4(keccak256("amount(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Amount = bytes4(keccak256("#amount"));
     /// @dev Ledger balance - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Balance = bytes4(keccak256("balance(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Balance = bytes4(keccak256("#balance"));
     /// @dev Host-scoped request amount - (uint host, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Allocation = bytes4(keccak256("allocation(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Allocation = bytes4(keccak256("#allocation"));
     /// @dev Host-scoped allowance cap - (uint host, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Allowance = bytes4(keccak256("allowance(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Allowance = bytes4(keccak256("#allowance"));
     /// @dev Cross-host custody state - (uint host, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Custody = bytes4(keccak256("custody(uint host, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Custody = bytes4(keccak256("#custody"));
     /// @dev Minimum acceptable output - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Minimum = bytes4(keccak256("minimum(bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Minimum = bytes4(keccak256("#minimum"));
     /// @dev Maximum allowable spend - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Maximum = bytes4(keccak256("maximum(bytes32 asset, bytes32 meta, uint amount)"));
-    /// @dev Signed min/max bounds - (int min, int max)
-    bytes4 constant Bounds = bytes4(keccak256("bounds(int min, int max)"));
+    bytes4 constant Maximum = bytes4(keccak256("#maximum"));
     /// @dev Fee amount - (uint amount)
-    bytes4 constant Fee = bytes4(keccak256("fee(uint amount)"));
-    /// @dev Hard stop / iteration sentinel - ()
-    bytes4 constant Break = bytes4(keccak256("break()"));
-    /// @dev Bundle wrapper - (bytes data); payload is an embedded block stream
-    bytes4 constant Bundle = bytes4(keccak256("bundle(bytes data)"));
-    /// @dev List wrapper - (bytes data); payload is an embedded repeated block stream
-    bytes4 constant List = bytes4(keccak256("list(bytes data)"));
-    /// @dev Frame wrapper - (bytes data); payload is schema-defined concatenated member payloads
-    bytes4 constant Frame = bytes4(keccak256("frame(bytes data)"));
-    /// @dev Extensible routing field - (bytes data); layout is command-defined
-    bytes4 constant Route = bytes4(keccak256("route(bytes data)"));
-    /// @dev Extensible list item field - (bytes data); layout is implementation-defined
-    bytes4 constant Item = bytes4(keccak256("item(bytes data)"));
-    /// @dev EVM-encoded payload field - (bytes data); layout follows standard ABI tuple encoding
-    bytes4 constant Evm = bytes4(keccak256("evm(bytes data)"));
-    /// @dev Extensible query field - (bytes data); layout is query-defined, key is always `Keys.Query`
-    bytes4 constant Query = bytes4(keccak256("query(bytes data)"));
-    /// @dev Extensible response field - (bytes data); layout is response-defined, key is always `Keys.Response`
-    bytes4 constant Response = bytes4(keccak256("response(bytes data)"));
-    /// @dev Plain scalar amount - (uint amount)
-    bytes4 constant Quantity = bytes4(keccak256("quantity(uint amount)"));
-    /// @dev Ratio or rate value - (uint value)
-    bytes4 constant Rate = bytes4(keccak256("rate(uint value)"));
+    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.
+    bytes4 constant Bytes = bytes4(keccak256("#bytes"));
     /// @dev Account identifier - (bytes32 account)
-    bytes4 constant Account = bytes4(keccak256("account(bytes32 account)"));
+    bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer payout request - (bytes32 account, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Payout = bytes4(keccak256("payout(bytes32 account, bytes32 asset, bytes32 meta, uint amount)"));
+    bytes4 constant Payout = bytes4(keccak256("#payout"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant Transaction = bytes4(
-        keccak256("transaction(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)")
-    );
-    /// @dev Sub-command invocation - (uint target, uint value, bytes request)
-    bytes4 constant Step = bytes4(keccak256("step(uint target, uint value, bytes request)"));
-    /// @dev Raw external call - (uint target, uint value, bytes data)
-    bytes4 constant Call = bytes4(keccak256("call(uint target, uint value, bytes data)"));
-    /// @dev Authentication proof - (uint cid, uint deadline, bytes proof); must appear last in its segment
-    bytes4 constant Auth = bytes4(keccak256("auth(uint cid, uint deadline, bytes proof)"));
+    bytes4 constant Transaction = bytes4(keccak256("#transaction"));
+    /// @dev Sub-command invocation - (uint target, uint value, #bytes as request)
+    bytes4 constant Step = bytes4(keccak256("#step"));
+    /// @dev Raw external call - (uint target, uint value, #bytes as payload)
+    bytes4 constant Call = bytes4(keccak256("#call"));
+    /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)
+    bytes4 constant Context = bytes4(keccak256("#context"));
+    /// @dev Authentication proof - (uint cid, uint deadline, #bytes as proof); must appear last in its segment
+    bytes4 constant Auth = bytes4(keccak256("#auth"));
     /// @dev Asset descriptor without amount - (bytes32 asset, bytes32 meta)
-    bytes4 constant Asset = bytes4(keccak256("asset(bytes32 asset, bytes32 meta)"));
+    bytes4 constant Asset = bytes4(keccak256("#asset"));
     /// @dev Node identifier - (uint id)
-    bytes4 constant Node = bytes4(keccak256("node(uint id)"));
+    bytes4 constant Node = bytes4(keccak256("#node"));
     /// @dev Relayer bounty - (uint amount, bytes32 relayer)
-    bytes4 constant Bounty = bytes4(keccak256("bounty(uint amount, bytes32 relayer)"));
+    bytes4 constant Bounty = bytes4(keccak256("#bounty"));
 
     /// @dev Structural status form - (bool ok)
-    bytes4 constant Status = bytes4(keccak256(bytes(Forms.Status)));
+    bytes4 constant Status = bytes4(keccak256("#status"));
     /// @dev Structural asset amount form - (bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant AssetAmount = bytes4(keccak256(bytes(Forms.AssetAmount)));
+    bytes4 constant AssetAmount = bytes4(keccak256("#assetAmount"));
     /// @dev Structural account asset form - (bytes32 account, bytes32 asset, bytes32 meta)
-    bytes4 constant AccountAsset = bytes4(keccak256(bytes(Forms.AccountAsset)));
+    bytes4 constant AccountAsset = bytes4(keccak256("#accountAsset"));
     /// @dev Structural account amount form - (bytes32 account, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant AccountAmount = bytes4(keccak256(bytes(Forms.AccountAmount)));
+    bytes4 constant AccountAmount = bytes4(keccak256("#accountAmount"));
     /// @dev Structural host amount form - (uint host, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant HostAmount = bytes4(keccak256(bytes(Forms.HostAmount)));
+    bytes4 constant HostAmount = bytes4(keccak256("#hostAmount"));
     /// @dev Structural host account asset form - (uint host, bytes32 account, bytes32 asset, bytes32 meta)
-    bytes4 constant HostAccountAsset = bytes4(keccak256(bytes(Forms.HostAccountAsset)));
+    bytes4 constant HostAccountAsset = bytes4(keccak256("#hostAccountAsset"));
     /// @dev Structural host account amount form - (uint host, bytes32 account, bytes32 asset, bytes32 meta, uint amount)
-    bytes4 constant HostAccountAmount = bytes4(keccak256(bytes(Forms.HostAccountAmount)));
+    bytes4 constant HostAccountAmount = bytes4(keccak256("#hostAccountAmount"));
 }

package/blocks/Schema.sol

@@ -3,81 +3,26 @@ pragma solidity ^0.8.33;
 
 // Block stream:
 // - encoding is [bytes4 key][bytes4 payloadLen][payload]
-// - `payloadLen` covers only the block payload
+// - `payloadLen` is big-endian and covers only the block payload
 // - payload layout is block-specific
 //
-// Extensible payloads:
-// - self payload may be [head][dynamic tail]
-// - head layout is implied by the block key
-// - one dynamic field may consume the rest of self payload without its own length prefix
-// - reserved extensible forms keep one fixed key while their declared field list remains descriptive schema metadata
-// - chain-specific payload blocks are encoded using the local chain/runtime's native conventions
-// - on EVM-family chains, `evm(<fields...>)` payloads use standard ABI tuple encoding via `abi.encode(...)`
-//   and can be decoded with `abi.decode`
-// - chain-specific payload blocks are request-only escape hatches and should never be used for pipeline state
-// - prefer ordinary protocol blocks whenever possible; chain-specific payload blocks should be a last resort
-//
-// Schema DSL:
-// - `;` separates top-level sibling blocks
-// - `&` bundles adjacent blocks into one bundle block
-// - `+` frames adjacent fixed-layout block payloads into one frame block
-// - `&` and `+` follow the same grouping and normalization rules, except they emit different wrapper blocks
-// - `name = a & b` introduces a named bundle item with a local key derived from the raw input string
-// - `name = a + b` introduces a named frame item with a local key derived from the raw input string
-// - `bundle = a & b` introduces an anonymous child bundle item
-// - `frame = a + b` introduces an anonymous child frame item, like `bundle = ...` and `list = ...`
-// - postfix `[]` marks a repeated list in the simple suffix form, e.g. `asset(...)[]`
-// - `name[] = a & b` introduces a named list with a local key derived from the raw input string
-// - `list = a & b` introduces an anonymous list whose repeated item is the bundled shape `a & b`
-// - empty entries are ignored, but structural markers are preserved after normalization
-// - grouping parentheses are not part of the DSL; parentheses are only used in block field lists
-// - `+` binds tighter than `&`, so `a & b + c` normalizes as `a & (b + c)`
-// - if `&` appears, the result remains a bundle even when only one non-empty child remains
-// - if `+` appears, the result remains a frame even when only one non-empty child remains
-// - after ignoring empty entries, repeated adjacent separators collapse while preserving bundle/frame/list shape
-// - bundled blocks preserve member order, so `a & b` differs from `b & a`
-// - a bundle block's self payload is an embedded normal block stream of its bundled members
-// - bundled members keep their ordinary block encoding, so dynamic blocks are allowed inside bundles
-// - a list block's self payload is an embedded normal block stream representing the repeated items
-// - a frame block's self payload is the concatenated payload fields of its framed members
-// - framed members do not keep their ordinary block headers; the emitted schema defines the frame layout
-// - framed members must be fixed-layout block forms because frame payloads contain no child lengths or block keys
-// - frames may be bundled like ordinary block items, but bundles/lists cannot be framed
-// - top-level blocks of the same type should be grouped together
-// - primary / driving blocks should appear before auxiliary blocks
-// - `route(<fields...>)`, `item(<fields...>)`, `evm(<fields...>)`, `query(<fields...>)`,
-//   and `response(<fields...>)` are reserved extensible schema forms whose keys are always
-//   `Keys.Route`, `Keys.Item`, `Keys.Evm`, `Keys.Query`, and `Keys.Response` respectively
-// - these extensible forms work like dynamic `bytes` blocks: they may carry arbitrary
-//   payload bytes while keeping one fixed key per semantic block type
-// - `evm(<fields...>)` differs from bundle/list payloads: its bytes are not an embedded block stream
-// - `evm(uint foo, uint bar)` is a schema declaration only; on-chain the block key is still `Keys.Evm`
-//   and the payload can be decoded from `bytes data` using the local runtime's native decoder
-// - on EVM, `evm(bool flag)` occupies one full 32-byte ABI word, exactly like `abi.encode(flag)`
-// - anonymous `&` compiles to a `Keys.Bundle` block whose self payload is the bundled member block stream
-// - anonymous `[]` compiles to a `Keys.List` block whose self payload is the repeated item block stream
-// - anonymous `+` compiles to a `Keys.Frame` block whose self payload is the framed member payload fields
-// - named lists, bundles, and frames use bytes4(keccak256(bytes(rawSchemaInput))) as their block key
-// - named structural keys are custom/local identifiers, not global protocol keys; formatting is part of identity
-// - `asset(...)[]` means a list whose repeated item is the block `asset(...)`
-// - `steps[] = asset(...) & account(...)` means a named list whose repeated item is the bundle
-//   `asset(...) & account(...)`
-// - `payment = amount(...) + fee(...)` means a named frame whose payload is
-//   `asset | meta | amount | fee` and whose on-chain key is derived from that raw schema string
-// - `amount(...) & fee(...) + account(...)` means `amount(...) & (fee(...) + account(...))`;
-//   it compiles to a bundle containing one amount block followed by one frame block
-// - `bundle = account(...) & evm(bytes routeData)` means an anonymous child bundle with those bundled members
-// - `frame = amount(...) + fee(...)` means an anonymous child frame with those framed payload fields
-// - `list = asset(...) & account(...)` means an anonymous child list whose repeated item is the
-//   bundle `asset(...) & account(...)`
-// - `"amount(...) &"` and `"& amount(...)"` both normalize to a bundle containing one `amount(...)` child
-// - `"amount(...) +"` and `"+ amount(...)"` both normalize to a frame containing one `amount(...)` payload
-// - canonical blocks are `amount(...)` for request amounts, `balance(...)` for state balances,
-//   `allocation(...)` for host-scoped provision requests, `allowance(...)` for host-scoped caps,
-//   `custody(...)` for host-scoped state,
-//   `minimum(...)` for result floors, `maximum(...)` for spend ceilings, and `quantity(...)`
-//   for plain scalar amounts
-// - `auth(uint cid, uint deadline, bytes proof)` is a proof-separator block and must be emitted last
+// Schema:
+// - blocks are written as `#name { fields }`
+// - a block without braces has no payload, e.g. `#unit`
+// - commas separate siblings at every level
+// - braces define parent-child boundaries
+// - top-level item 0 is the prime item; later top-level items are globals
+// - prime 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
+// - 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
+// - 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"))
+// - see `docs/Schema.md` for the full working spec
 //
 // Pipeline state:
 // - `balance(...)` and `custody(...)` are live, linear state in the active command pipeline
@@ -91,56 +36,52 @@ pragma solidity ^0.8.33;
 //
 // Signed blocks:
 // - an authenticated input segment ends with one trailing AUTH block
-// - auth is typically grouped with the signed payload in one bundle, with AUTH as the final member
 // - only the final AUTH is treated specially; earlier AUTH blocks remain ordinary signed bytes
 // - the signed slice runs from the segment start through the AUTH head, excluding only AUTH proof bytes
 // - `cid` binds the signature to one command; `deadline` acts as expiry and nonce
 // - current helpers assume proof layout `[bytes20 signer][bytes65 sig]`
 
 /// @title Schemas
-/// @notice Human-readable ABI-signature string constants for each block type.
-/// These strings are the canonical source from which `Keys` constants are derived
-/// and are used when emitting schema descriptors in command events.
+/// @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.
 library Schemas {
-    string constant Node = "node(uint id)";
-    string constant Account = "account(bytes32 account)";
-    string constant Asset = "asset(bytes32 asset, bytes32 meta)";
-    string constant Balance = "balance(bytes32 asset, bytes32 meta, uint amount)";
-    string constant Amount = "amount(bytes32 asset, bytes32 meta, uint amount)";
-    string constant Minimum = "minimum(bytes32 asset, bytes32 meta, uint amount)";
-    string constant Maximum = "maximum(bytes32 asset, bytes32 meta, uint amount)";
-    string constant Custody = "custody(uint host, bytes32 asset, bytes32 meta, uint amount)";
-    string constant Payout = "payout(bytes32 account, bytes32 asset, bytes32 meta, uint amount)";
-    string constant Allocation = "allocation(uint host, bytes32 asset, bytes32 meta, uint amount)";
-    string constant Allowance = "allowance(uint host, bytes32 asset, bytes32 meta, uint amount)";
-    string constant Transaction = "transaction(bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount)";
-    string constant Call = "call(uint target, uint value, bytes data)";
-    string constant Step = "step(uint target, uint value, bytes request)";
-    string constant Bounty = "bounty(uint amount, bytes32 relayer)";
-    string constant Quantity = "quantity(uint amount)";
-    string constant Fee = "fee(uint amount)";
-    string constant Rate = "rate(uint value)";
-    string constant Bounds = "bounds(int min, int max)";
-    string constant Auth = "auth(uint cid, uint deadline, bytes proof)";
-    string constant Route = "route(bytes data)";
-    string constant Item = "item(bytes data)";
-    string constant Evm = "evm(bytes data)";
-    string constant Query = "query(bytes data)";
-    string constant Response = "response(bytes data)";
-    string constant Break = "break()";
+    string constant Unit = "#unit";
+    string constant Node = "#node { uint id }";
+    string constant Account = "#account { bytes32 account }";
+    string constant Asset = "#asset { bytes32 asset, bytes32 meta }";
+    string constant Balance = "#balance { bytes32 asset, bytes32 meta, uint amount }";
+    string constant Amount = "#amount { bytes32 asset, bytes32 meta, uint amount }";
+    string constant Minimum = "#minimum { bytes32 asset, bytes32 meta, uint amount }";
+    string constant Maximum = "#maximum { bytes32 asset, bytes32 meta, uint amount }";
+    string constant Custody = "#custody { uint host, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Payout = "#payout { bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Allocation = "#allocation { uint host, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Allowance = "#allowance { uint host, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, bytes32 meta, uint amount }";
+    string constant Call = "#call { uint target, uint value, #bytes as payload }";
+    string constant Step = "#step { uint target, uint value, #bytes as request }";
+    string constant Context = "#context { bytes32 account, uint value, #bytes as state, #bytes as request }";
+    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 Bytes = "#bytes";
+    string constant Data = "#data";
+    string constant List = "#list";
+    string constant Evm = "#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(bool ok)";
-    string constant AssetAmount = "assetAmount(bytes32 asset, bytes32 meta, uint amount)";
-    string constant AccountAsset = "accountAsset(bytes32 account, bytes32 asset, bytes32 meta)";
-    string constant AccountAmount = "accountAmount(bytes32 account, bytes32 asset, bytes32 meta, uint amount)";
-    string constant HostAmount = "hostAmount(uint host, bytes32 asset, bytes32 meta, uint amount)";
-    string constant HostAccountAsset = "hostAccountAsset(uint host, bytes32 account, bytes32 asset, bytes32 meta)";
-    string constant HostAccountAmount = "hostAccountAmount(uint host, bytes32 account, bytes32 asset, bytes32 meta, uint amount)";
+    string constant Status = "#status { bool ok }";
+    string constant AssetAmount = "#assetAmount { bytes32 asset, bytes32 meta, uint amount }";
+    string constant AccountAsset = "#accountAsset { bytes32 account, bytes32 asset, bytes32 meta }";
+    string constant AccountAmount = "#accountAmount { bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
+    string constant HostAmount = "#hostAmount { uint host, bytes32 asset, bytes32 meta, uint amount }";
+    string constant HostAccountAsset = "#hostAccountAsset { uint host, bytes32 account, bytes32 asset, bytes32 meta }";
+    string constant HostAccountAmount = "#hostAccountAmount { uint host, bytes32 account, bytes32 asset, bytes32 meta, uint amount }";
 }
 
 /// @title Sizes
@@ -162,14 +103,14 @@ library Sizes {
     uint constant B160 = Header + 5 * Word;
     /// @dev AUTH proof segment only: 20-byte signer + 65-byte signature = 85 bytes
     uint constant Proof = 85;
-    /// @dev AUTH block: 8 header + 32 cid + 32 deadline + 85 proof = 157 bytes
-    uint constant Auth = B64 + Proof;
+    /// @dev AUTH block: 8 header + 32 cid + 32 deadline + nested BYTES block with 85-byte proof = 165 bytes
+    uint constant Auth = B64 + Header + Proof;
+    /// @dev STATUS block: 8 header + 1 bool byte = 9 bytes
+    uint constant Status = Header + 1;
     /// @dev AMOUNT block: 8 header + 32 asset + 32 meta + 32 amount = 104 bytes
     uint constant Amount = B96;
     /// @dev BALANCE block: 8 header + 32 asset + 32 meta + 32 amount = 104 bytes
     uint constant Balance = B96;
-    /// @dev BOUNDS block: 8 header + 32 min + 32 max = 72 bytes
-    uint constant Bounds = B64;
     /// @dev FEE block: 8 header + 32 amount = 40 bytes
     uint constant Fee = B32;
     /// @dev BOUNTY block: 8 header + 32 amount + 32 relayer = 72 bytes