@rootzero/contracts 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.22.0
+
+### Breaking Changes
+
+- Declared child blocks are now structurally present whenever their parent is
+  non-empty. A child without a value uses its zero-payload block form instead
+  of being omitted. The `maybe` modifier now hints that onchain code accepts
+  that empty form; it no longer describes an absent item. Lists likewise keep
+  their header and represent no items with an empty payload.
+- Removed `Schemas.Unit`. Use the empty form of the block key that carries the
+  relevant semantic meaning instead of a generic unit marker.
+- Renamed `Decoders.take(cur, key)` to `takeBlock(cur, key)`. The `take` name is
+  now used by raw cursor navigation and returns the absolute start of a
+  bounds-checked byte range while advancing the cursor.
+- Normalized standard schema bodies by removing their presentation-only outer
+  braces, and renamed the standard node field from `id` to `node`. Published
+  schema annotation bytes therefore change even though their wire layouts do
+  not.
+
+### Added
+
+- Added empty-block inspection, conditional consumption, encoding, writing,
+  and execution-output helpers across `Blocks`, `Decoders`, `Readers`,
+  `Writers`, and `Executions`.
+- Added `absolute`, `advance`, and raw `take` cursor helpers, plus `enter`
+  overloads that advance over a validated fixed payload prefix in one cursor
+  update.
+- Added unnamed `schema` overloads for context-local specifications and an
+  unnamed `Blocks.schema` factory overload.
+- Added the offchain-only `at N` schema projection hint. Explicit positions are
+  reserved first, then unannotated siblings fill the remaining positions in
+  declaration order; wire encoding and onchain decoding remain unchanged.
+
+### Changed
+
+- Clarified that one optional pair of outer braces is presentation-only for all
+  non-empty schema bodies, including custom top-level `many` schemas.
+- Updated custom input examples to group fixed-width fields for direct calldata
+  reads, demonstrate empty child blocks, and separate top-level and nested swap
+  decoding.
+- Excluded repository documentation and examples from the prepared npm package;
+  the package continues to contain Solidity sources, the README, changelog, and
+  license.
+
+### Upgrade Compatibility
+
+- Emit every declared child header in schema order. When a `maybe` child has no
+  value, emit that child's key with a zero payload length and call
+  `tryConsumeEmpty` before its strict semantic unpacker.
+- Replace `Schemas.Unit` markers with an empty block carrying the key expected
+  by the receiving schema.
+- Replace `cur.take(key)` with `cur.takeBlock(key)`. Use `cur.take(amount)` only
+  for raw fixed-width ranges.
+- Indexers should accept braced and unbraced schema bodies, treat `maybe` as an
+  empty-value hint, and apply `at N` only after decoding declaration-order wire
+  data.
+
 ## 1.21.0
 
 ### Breaking Changes

package/README.md

@@ -114,16 +114,20 @@ identifiers inside, never how the bytes are laid out.
 
 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
-[`docs/Schema.md`](docs/Schema.md). The standard block schemas live in
+marked `maybe` when their empty form is accepted or `many` when they form a
+list, and aliases and dotted field paths give off-chain tooling presentation
+names without changing a single byte on the wire. Declared child headers are
+always present; a zero payload length represents an empty block. An `at N` hint
+can reposition one field in off-chain presentation without changing its wire
+position. The full schema language is specified in
+[`docs/Schema.md`](https://github.com/lastqubit/rootzero-evm/blob/main/docs/Schema.md). The standard block schemas live in
 `Schemas` and their runtime keys in `Keys` (both via
 `@rootzero/contracts/Codec.sol`).
 
-A rare top-level list is published as a custom schema such as `many #asset`.
-Its context-local schema key becomes the outer block key accepted by the
-endpoint; nested lists continue to use the generic `#list` key.
+A rare top-level list is published as a custom schema consisting of one item,
+such as `many #asset` or `{ many #asset }`. Its context-local schema key becomes
+the outer block key accepted by the endpoint; a list alongside sibling items
+continues to use the generic `#list` key.
 
 ## Batches
 
@@ -492,7 +496,7 @@ Repo layout:
 - `contracts/blocks` — block schema, cursor parsing, writers
 - `contracts/utils` — ids, nodes, assets, accounts, layout, ECDSA
 - `contracts/events` — event contracts and emitters
-- `docs` — [`Schema.md`](docs/Schema.md) (wire format and schema DSL)
+- `docs` — [`Schema.md`](https://github.com/lastqubit/rootzero-evm/blob/main/docs/Schema.md) (wire format and schema DSL)
 
 Use this library to create a new rootzero host, implement a command, or reuse
 the protocol's block format in tooling. It is the shared protocol foundation,

package/annotations/Schema.sol

@@ -11,6 +11,23 @@ import {Runtime} from "../core/Runtime.sol";
 /// @dev Schema annotations accumulate for distinct block keys. For a trusted
 /// emitter, the latest schema for the same block key replaces the earlier claim.
 abstract contract Schema is Runtime, AnnotationEvent {
+    /// @notice Construct and publish an unnamed context-local block specification.
+    /// @param key Context-local key value.
+    /// @param min Minimum accepted payload length.
+    /// @param max Maximum accepted payload length; zero means unbounded.
+    /// @param hint Initial per-block payload capacity.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @return spec The context-local block specification.
+    function schema(
+        uint32 key,
+        uint32 min,
+        uint32 max,
+        uint32 hint,
+        string memory body
+    ) internal returns (uint spec) {
+        return schema(key, min, max, hint, body, bytes32(0));
+    }
+
     /// @notice Construct and publish a context-local block specification.
     /// @param key Context-local key value.
     /// @param min Minimum accepted payload length.
@@ -27,8 +44,16 @@ abstract contract Schema is Runtime, AnnotationEvent {
         string memory body,
         bytes32 name
     ) internal returns (uint spec) {
-        spec = Specs.create(key, min, max, hint);
-        return schema(spec, body, name);
+        return schema(Specs.create(key, min, max, hint), body, name);
+    }
+
+    /// @notice Construct and publish an unnamed exact-size context-local block specification.
+    /// @param key Context-local key value.
+    /// @param size Exact payload length and initial per-block payload capacity.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @return spec The context-local block specification.
+    function schema(uint32 key, uint32 size, string memory body) internal returns (uint spec) {
+        return schema(key, size, body, bytes32(0));
     }
 
     /// @notice Construct and publish an exact-size context-local block specification.
@@ -41,6 +66,14 @@ abstract contract Schema is Runtime, AnnotationEvent {
         return schema(Specs.create(key, size), body, name);
     }
 
+    /// @notice Publish an unnamed, already constructed block specification for the current host.
+    /// @param spec Packed block specification.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @return The published block specification.
+    function schema(uint spec, string memory body) internal returns (uint) {
+        return schema(spec, body, bytes32(0));
+    }
+
     /// @notice Publish an already constructed block specification for the current host.
     /// @param spec Packed block specification.
     /// @param body Schema DSL string describing the block payload body.

package/codec/Blocks.sol

@@ -73,6 +73,17 @@ library Blocks {
         len = uint32(head >> 192);
     }
 
+    /// @notice Decode a complete block header within an absolute calldata region.
+    /// @param abs Absolute position of the header.
+    /// @param end Absolute region boundary.
+    /// @return key Decoded block key.
+    /// @return len Decoded payload length.
+    function peek(uint abs, uint end) internal pure returns (bytes4 key, uint len) {
+        if (abs > end || Sizes.Header > end - abs) revert MalformedBlocks();
+        (key, len) = header(abs);
+        if (len > end - abs - Sizes.Header) revert MalformedBlocks();
+    }
+
     /// @notice Validate a block header at an absolute calldata position.
     /// @dev DANGER: This performs an unchecked calldata read and does not ensure `end`
     /// lies within the caller's logical calldata region. Only the key, minimum,
@@ -101,6 +112,17 @@ library Blocks {
         end = body + size;
     }
 
+    /// @notice Validate an empty block at an absolute calldata position.
+    /// @dev DANGER: This performs an unchecked calldata read. The caller must
+    /// validate the returned end against its logical calldata region.
+    /// @param abs Absolute position of the block header.
+    /// @param key Expected block key.
+    /// @return end Absolute position immediately after the empty block header.
+    function expectEmpty(uint abs, bytes4 key) internal pure returns (uint end) {
+        if (header(abs, key) != 0) revert InvalidBlock();
+        return abs + Sizes.Header;
+    }
+
     /// @notice Return whether `abs` identifies a header with `key` before an absolute end.
     /// @param abs Absolute calldata position to inspect.
     /// @param end Absolute region boundary.
@@ -111,6 +133,16 @@ library Blocks {
         return bytes4(read32(abs)) == key;
     }
 
+    /// @notice Return whether `abs` identifies a complete empty block header.
+    /// @param abs Absolute position to inspect.
+    /// @param end Absolute region boundary.
+    /// @param key Expected block key.
+    /// @return Whether the expected key occurs with a zero-length payload.
+    function isEmpty(uint abs, uint end, bytes4 key) internal pure returns (bool) {
+        if (!hasAt(abs, end, key)) return false;
+        return uint32(uint(read32(abs)) >> 192) == 0;
+    }
+
     /// @notice Find the first block with `key` at or after absolute position `abs`.
     /// @param abs Absolute search position.
     /// @param end Absolute region boundary.
@@ -160,6 +192,18 @@ library Blocks {
 
     // Generic block writes
 
+    /// @notice Write an empty block header at `i`.
+    /// @dev DANGER: Unchecked memory write. Reserve `Sizes.Header` bytes first.
+    /// @param dst Destination buffer.
+    /// @param i Relative write position.
+    /// @param key Block key.
+    function writeEmpty(bytes memory dst, uint i, bytes4 key) internal pure {
+        uint head = uint(uint32(key)) << 224;
+        assembly ("memory-safe") {
+            mstore(add(add(dst, 0x20), i), head)
+        }
+    }
+
     /// @notice Write a custom block with one payload word at `i`.
     /// @dev DANGER: Unchecked memory write. Reserve `Sizes.B32` bytes first.
     /// @param dst Destination buffer.
@@ -1729,6 +1773,14 @@ library Blocks {
 
     // Generic factories
 
+    /// @notice Encode an empty block.
+    /// @param key Block type key.
+    /// @return value Encoded empty block header.
+    function empty(bytes4 key) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Header);
+        writeEmpty(value, 0, key);
+    }
+
     /// @notice Encode a block with a raw payload.
     /// @param key Block type key.
     /// @param payload Raw payload bytes.
@@ -1831,6 +1883,14 @@ library Blocks {
     /// @notice Encode a SCHEMA block.
     /// @param spec Block specification.
     /// @param body Schema body.
+    /// @return value Encoded SCHEMA block bytes.
+    function schema(uint spec, string memory body) internal pure returns (bytes memory value) {
+        return schema(spec, body, bytes32(0));
+    }
+
+    /// @notice Encode a named SCHEMA block.
+    /// @param spec Block specification.
+    /// @param body Schema body.
     /// @param name Schema name.
     /// @return value Encoded SCHEMA block bytes.
     function schema(uint spec, string memory body, bytes32 name) internal pure returns (bytes memory value) {
@@ -1931,7 +1991,8 @@ library Blocks {
     }
 
     /// @notice Encode a RELAY block.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID, passed through
+    /// without semantic validation.
     /// @param resources Chain-specific resources for the destination context.
     /// @param input Nested input block stream.
     /// @return value Encoded RELAY block bytes.
@@ -1949,7 +2010,8 @@ library Blocks {
     }
 
     /// @notice Encode a DISPATCH block.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID, passed through
+    /// without semantic validation.
     /// @param resources Chain-specific resources for the destination dispatch.
     /// @param payload Encoded payload.
     /// @return value Encoded DISPATCH block bytes.

package/codec/Decoders.sol

@@ -52,6 +52,13 @@ library Decoders {
         return cur.state.more();
     }
 
+    /// @notice Return the cursor's current absolute calldata position.
+    /// @param cur Cursor to inspect.
+    /// @return Current absolute calldata position.
+    function absolute(Cur memory cur) internal pure returns (uint) {
+        return cur.state.absolute();
+    }
+
     /// @notice Validate and consume the next block from a cursor.
     /// @param cur Cursor advanced over the complete block.
     /// @param spec Expected block specification.
@@ -62,6 +69,18 @@ library Decoders {
         cur.state = cur.state.seekAbs(end);
     }
 
+    /// @notice Consume a matching empty block from a cursor when present.
+    /// @param cur Cursor advanced only when the matching block is empty.
+    /// @param key Expected block key.
+    /// @return Whether an empty block was consumed.
+    function tryConsumeEmpty(Cur memory cur, bytes4 key) internal pure returns (bool) {
+        (uint i, uint offset, uint size) = cur.state.decode();
+        (bytes4 current, uint len) = Blocks.peek(offset + i, offset + size);
+        if (current != key || len != 0) return false;
+        cur.state = cur.state.seek(i + Sizes.Header);
+        return true;
+    }
+
     /// @notice Validate and enter the payload of the next block in a cursor.
     /// @dev The cursor remains in its existing frame so callers can decode child
     /// blocks in place. Callers should prove complete payload consumption with
@@ -71,8 +90,38 @@ library Decoders {
     /// @return abs Absolute position of the first payload byte.
     /// @return end Absolute position immediately after the payload.
     function enter(Cur memory cur, uint spec) internal pure returns (uint abs, uint end) {
+        return enter(cur, spec, 0);
+    }
+
+    /// @notice Validate a parent block and advance over a fixed payload prefix.
+    /// @dev `amount` is relative to the payload start and cannot exceed the
+    /// current parent payload. The returned `abs` remains the payload start.
+    /// @param cur Cursor advanced over the block header and fixed prefix.
+    /// @param spec Expected parent block specification.
+    /// @param amount Number of initial payload bytes to advance over.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function enter(Cur memory cur, uint spec, uint amount) internal pure returns (uint abs, uint end) {
         (abs, end) = Blocks.expect(cur.state.absolute(), spec);
-        cur.state = cur.state.seekAbs(abs);
+        if (amount > end - abs) revert Blocks.InvalidBlock();
+        cur.state = cur.state.seekAbs(abs + amount);
+    }
+
+    /// @notice Advance a cursor by a raw byte count.
+    /// @dev No block header or schema is validated.
+    /// @param cur Cursor advanced by `amount` bytes.
+    /// @param amount Number of bytes to advance.
+    function advance(Cur memory cur, uint amount) internal pure {
+        cur.state = cur.state.advance(amount);
+    }
+
+    /// @notice Take a raw byte range from the cursor.
+    /// @dev No block header or schema is validated.
+    /// @param cur Cursor advanced by `amount` bytes.
+    /// @param amount Number of bytes to take.
+    /// @return abs Absolute position of the first taken byte.
+    function take(Cur memory cur, uint amount) internal pure returns (uint abs) {
+        (cur.state, abs) = cur.state.consume(amount);
     }
 
     /// @notice Require a decoder cursor to be at absolute position `abs`.
@@ -128,9 +177,7 @@ library Decoders {
     /// @return len Payload length.
     function peek(Cur memory cur, uint i) internal pure returns (bytes4 key, uint len) {
         (, uint offset, uint size) = cur.state.decode();
-        if (i > size || Sizes.Header > size - i) revert Blocks.MalformedBlocks();
-        (key, len) = Blocks.header(offset + i);
-        if (len > size - i - Sizes.Header) revert Blocks.MalformedBlocks();
+        return Blocks.peek(offset + i, offset + size);
     }
 
     /// @notice Return the relative position immediately after the current block.
@@ -161,6 +208,15 @@ library Decoders {
         return Blocks.hasAt(offset + i, offset + len, key);
     }
 
+    /// @notice Return whether the current block has `key` and an empty payload.
+    /// @param cur Cursor positioned at a block.
+    /// @param key Expected block key.
+    /// @return Whether a complete matching empty block header occurs at the current position.
+    function isEmpty(Cur memory cur, bytes4 key) internal pure returns (bool) {
+        (uint i, uint offset, uint len) = cur.state.decode();
+        return Blocks.isEmpty(offset + i, offset + len, key);
+    }
+
     /// @notice Find `key` at or after relative position `i`.
     /// @param cur Cursor to search.
     /// @param i Relative search position.
@@ -210,7 +266,7 @@ library Decoders {
     /// @param cur Cursor advanced past the block.
     /// @param key Expected block key.
     /// @return out Cursor spanning the complete encoded block.
-    function take(Cur memory cur, bytes4 key) internal pure returns (Cur memory out) {
+    function takeBlock(Cur memory cur, bytes4 key) internal pure returns (Cur memory out) {
         uint abs = cur.state.absolute();
         (, uint end) = consume(cur, Specs.create(key, 0, 0, 0));
         out.state = Cursors.create(abs, end - abs, 0, 0, 0);
@@ -256,9 +312,7 @@ library Decoders {
 
     /// @dev Return the next raw calldata word and advance by `size` bytes.
     function next(Cur memory cur, uint size) private pure returns (bytes32 value) {
-        uint abs;
-        (cur.state, abs) = cur.state.consume(size);
-        value = Blocks.read32(abs);
+        value = Blocks.read32(take(cur, size));
     }
 
     /// @notice Return the next raw byte and advance the cursor by one byte.

package/codec/Readers.sol

@@ -45,6 +45,45 @@ library Readers {
         return cur.i != cur.source.length;
     }
 
+    /// @notice Return whether the current block has `key` and an empty payload.
+    /// @param cur Reader inspected without advancing.
+    /// @param key Expected block key.
+    /// @return Whether a complete matching empty block header occurs at the current position.
+    function isEmpty(Reader memory cur, bytes4 key) internal pure returns (bool) {
+        bytes memory source = cur.source;
+        uint i = cur.i;
+        if (i > source.length || source.length - i < Sizes.Header) return false;
+
+        uint header;
+        assembly ("memory-safe") {
+            header := mload(add(add(source, 0x20), i))
+        }
+        return bytes4(uint32(header >> 224)) == key && uint32(header >> 192) == 0;
+    }
+
+    /// @notice Consume a matching empty block from the reader when present.
+    /// @param cur Reader advanced only when the matching block is empty.
+    /// @param key Expected block key.
+    /// @return Whether an empty block was consumed.
+    function tryConsumeEmpty(Reader memory cur, bytes4 key) internal pure returns (bool) {
+        bytes memory source = cur.source;
+        uint i = cur.i;
+        if (i > source.length || source.length - i < Sizes.Header) revert InvalidBlock();
+
+        bytes4 current;
+        uint len;
+        assembly ("memory-safe") {
+            let header := mload(add(add(source, 0x20), i))
+            current := header
+            len := and(shr(192, header), 0xffffffff)
+        }
+
+        if (len > source.length - i - Sizes.Header) revert InvalidBlock();
+        if (current != key || len != 0) return false;
+        cur.i += Sizes.Header;
+        return true;
+    }
+
     /// @notice Validate and consume the current block, advancing `cur.i` past it.
     /// @param cur Reader to advance.
     /// @param key Expected block key.

package/codec/Schema.sol

@@ -8,24 +8,34 @@ pragma solidity ^0.8.33;
 //
 // Schema:
 // - block aliases are published separately from payload schemas
-// - payload schemas are `""`, `{ fields }`, or a top-level `many #x`
+// - payload schemas are `""` or a comma-separated item sequence; one optional
+//   pair of outer braces may wrap a non-empty sequence without changing meaning
 // - an empty schema string means the block has no structured payload
 // - commas separate siblings at every level
-// - braces define the current block payload body
+// - braces are presentation-only and do not change payload layout
 // - command inputs are a single run when the input 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
-// - nested `many #x` emits one generic list block containing repeated `#x` items
-// - a custom schema consisting of top-level `many #x` uses its custom key for
-//   the outer list block and contains repeated `#x` items directly
+// - every declared child block header is present when its parent is non-empty
+// - any block may use a zero-length payload as its empty form
+// - `maybe #x` hints that the onchain consumer accepts the empty form of `#x`
+//   when emptiness is not already intrinsic to the referenced block type
+// - `many #x` alongside other items emits one generic list block containing
+//   zero or more repeated `#x` items; the list header is always present
+// - a custom schema consisting of exactly one `many #x` item uses its custom
+//   key for the outer list block and contains repeated `#x` items directly,
+//   whether or not the item is wrapped in braces
 // - endpoint descriptor lanes identify their top-level block key directly
-// - `portal` fields are routing identifiers, often destination host IDs
+// - `portal` fields identify destination portal hosts. By convention the value
+//   is the portal implementation's host ID; core passes it through unchanged
+//   and hooks may validate or resolve it for their transport
 // - `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
+// - `at N` assigns an offchain presentation position to one sibling; explicit
+//   positions are reserved first and unannotated siblings retain relative order
 // - 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
 // - items are encoded in declaration order
@@ -63,7 +73,6 @@ pragma solidity ^0.8.33;
 library Schemas {
     // Empty and reserved payloads
 
-    string constant Unit = "";
     string constant Bytes = "";
     string constant String = "";
     string constant List = "";
@@ -71,47 +80,47 @@ library Schemas {
 
     // One-word payloads
 
-    string constant Node = "{ uint id }";
-    string constant Account = "{ bytes32 account }";
-    string constant Asset = "{ bytes32 asset }";
-    string constant Status = "{ uint code }";
+    string constant Node = "uint node";
+    string constant Account = "bytes32 account";
+    string constant Asset = "bytes32 asset";
+    string constant Status = "uint code";
 
     // Two-word payloads
 
-    string constant Amount = "{ bytes32 asset, uint amount }";
-    string constant Balance = "{ bytes32 asset, uint amount }";
-    string constant AccountAsset = "{ bytes32 account, bytes32 asset }";
-    string constant HostAsset = "{ uint host, bytes32 asset }";
+    string constant Amount = "bytes32 asset, uint amount";
+    string constant Balance = "bytes32 asset, uint amount";
+    string constant AccountAsset = "bytes32 account, bytes32 asset";
+    string constant HostAsset = "uint host, bytes32 asset";
 
     // Three-word payloads
 
-    string constant Allocation = "{ uint host, bytes32 asset, uint amount }";
-    string constant Allowance = "{ uint host, bytes32 asset, uint amount }";
-    string constant Custody = "{ uint host, bytes32 asset, uint amount }";
-    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 Allocation = "uint host, bytes32 asset, uint amount";
+    string constant Allowance = "uint host, bytes32 asset, uint amount";
+    string constant Custody = "uint host, bytes32 asset, uint amount";
+    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";
 
     // Four-word payloads
 
-    string constant Position = "{ bytes32 asset, uint amount, bytes32 liability, uint debt }";
-    string constant Transaction = "{ bytes32 from, bytes32 to, bytes32 asset, uint amount }";
-    string constant HostAccountAmount = "{ uint host, bytes32 account, bytes32 asset, uint amount }";
+    string constant Position = "bytes32 asset, uint amount, bytes32 liability, uint debt";
+    string constant Transaction = "bytes32 from, bytes32 to, bytes32 asset, uint amount";
+    string constant HostAccountAmount = "uint host, bytes32 account, bytes32 asset, uint amount";
 
     // Composite payloads
 
-    string constant Call = "{ uint target, uint resources, #bytes as payload }";
-    string constant Step = "{ uint cmd, uint resources, #bytes as input }";
-    string constant Relay = "{ uint portal, uint resources, #bytes as input }";
-    string constant Dispatch = "{ uint portal, uint resources, #bytes as payload }";
-    string constant Context = "{ bytes32 account, #bytes as state, #bytes as input }";
-    string constant Recover = "{ uint handler, uint resources, bytes32 key, #bytes as witness }";
-    string constant Annotation = "{ uint entity, #bytes as data }";
+    string constant Call = "uint target, uint resources, #bytes as payload";
+    string constant Step = "uint cmd, uint resources, #bytes as input";
+    string constant Relay = "uint portal, uint resources, #bytes as input";
+    string constant Dispatch = "uint portal, uint resources, #bytes as payload";
+    string constant Context = "bytes32 account, #bytes as state, #bytes as input";
+    string constant Recover = "uint handler, uint resources, bytes32 key, #bytes as witness";
+    string constant Annotation = "uint entity, #bytes as data";
 
     // Annotation payloads
 
-    string constant Action = "{ uint action }";
-    string constant Label = "{ bytes32 namespace, #string as name }";
-    string constant Schema = "{ uint spec, #string as body, bytes32 name }";
+    string constant Action = "uint action";
+    string constant Label = "bytes32 namespace, #string as name";
+    string constant Schema = "uint spec, #string as body, bytes32 name";
 }
 

package/codec/Writers.sol

@@ -73,6 +73,14 @@ library Writers {
     // Append helpers
     // -------------------------------------------------------------------------
 
+    /// @notice Append an empty block.
+    /// @param writer Destination writer.
+    /// @param key Block key.
+    function appendEmpty(Writer memory writer, bytes4 key) internal pure {
+        uint i = reserve(writer, Sizes.Header);
+        Blocks.writeEmpty(writer.dst, i, key);
+    }
+
     /// @notice Append arbitrary bytes to the writer.
     /// @param writer Destination writer; `i` is advanced by `data.length`.
     /// @param data Bytes to append.

package/commands/Relay.sol

@@ -8,7 +8,8 @@ using Executions for Execution;
 /// @notice Hook implemented by hosts that relay command contexts.
 abstract contract RelayPayableHook {
     /// @notice Override to relay a command context to `portal`.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID. Implementations
+    /// may validate or resolve it for their transport.
     /// @param resources Chain-specific destination resources. EVM adapters
     /// may interpret this as packed execution gas and destination value.
     /// @param account Destination command account.

package/core/Host.sol

@@ -61,16 +61,19 @@ abstract contract CommandHost is CommanderAccess, CallerAccess, HostIntroduction
     function enforceCaller(address caller) internal view virtual override returns (address) {
         return enforceCommander(caller);
     }
-
 }
 
 /// @title Admins
 /// @notice Optional bundle of the default host administration commands.
-abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {}
+abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {
+
+}
 
 /// @title Guardians
 /// @notice Optional bundle for guardian management and the default revoke guard.
-abstract contract Guardians is Appoint, Dismiss, Revoke {}
+abstract contract Guardians is Appoint, Dismiss, Revoke {
+
+}
 
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
@@ -78,13 +81,7 @@ abstract contract Guardians is Appoint, Dismiss, Revoke {}
 /// 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.
-abstract contract Host is
-    Admins,
-    Guardians,
-    HostIntroduction,
-    IntroductionEvent,
-    IHostIntroduction
-{
+abstract contract Host is Admins, Guardians, HostIntroduction, IntroductionEvent, IHostIntroduction {
     /// @param cmdr Commander address; used by the composed access capabilities.
     ///        If `cmdr` is a deployed contract, the host calls `introduce`
     ///        on it during construction.

package/events/Dispatch.sol

@@ -8,7 +8,7 @@ abstract contract DispatchEvent is EventEmitter {
     string private constant ABI = "event Dispatch(uint indexed host, uint portal, uint resources, bytes32 key, bytes32 digest)";
 
     /// @param host Host node ID that owns the dispatch.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID.
     /// @param resources Chain-specific resources assigned to the dispatch.
     /// @param key Dispatch correlation or recovery lookup key.
     /// @param digest Digest of the dispatched payload or canonical envelope.

package/events/Relay.sol

@@ -8,7 +8,7 @@ abstract contract RelayEvent is EventEmitter {
     string private constant ABI = "event Relay(bytes32 indexed account, uint portal, uint resources, bytes32 key, bytes32 digest)";
 
     /// @param account Account that owns the relayed context.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID.
     /// @param resources Chain-specific resources assigned to the relay.
     /// @param key Relay correlation or recovery lookup key.
     /// @param digest Digest of the relayed payload or canonical envelope.

package/events/Route.sol

@@ -8,7 +8,7 @@ abstract contract RouteEvent is EventEmitter {
     string private constant ABI = "event Route(uint indexed host, uint portal, uint status)";
 
     /// @param host Host node ID that owns the route.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID.
     /// @param status Route status. Zero means inactive; nonzero means active.
     event Route(uint indexed host, uint portal, uint status);
 

package/execution/Execution.sol

@@ -187,6 +187,25 @@ library Executions {
         return exec.decoders.any();
     }
 
+    /// @notice Return a decoder lane's current absolute calldata position.
+    /// @param exec Execution whose decoder is inspected.
+    /// @param lane Decoder lane to select.
+    /// @return Current absolute calldata position of the selected lane.
+    function absolute(Execution memory exec, uint8 lane) internal pure returns (uint) {
+        return exec.decoders.select(lane).absolute();
+    }
+
+    /// @notice Return whether the next block on `lane` has `key` and an empty payload.
+    /// @param exec Execution whose decoder is inspected without advancing.
+    /// @param lane Decoder lane to inspect.
+    /// @param key Expected block key.
+    /// @return Whether a complete matching empty block header occurs next.
+    function isEmpty(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (bool) {
+        uint cur = exec.decoders.select(lane);
+        (uint i, uint offset, uint len) = cur.decode();
+        return Blocks.isEmpty(offset + i, offset + len, key);
+    }
+
     /// @notice Validate and consume the next block from an execution decoder lane.
     /// @param exec Execution whose selected decoder cursor is advanced over the complete block.
     /// @param lane Execution decoder lane to select.
@@ -199,6 +218,20 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Consume a matching empty block from an execution decoder lane when present.
+    /// @param exec Execution whose selected decoder advances only for a matching empty block.
+    /// @param lane Decoder lane to consume.
+    /// @param key Expected block key.
+    /// @return Whether an empty block was consumed.
+    function tryConsumeEmpty(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (bool) {
+        uint cur = exec.decoders.select(lane);
+        (uint i, uint offset, uint size) = cur.decode();
+        (bytes4 current, uint len) = Blocks.peek(offset + i, offset + size);
+        if (current != key || len != 0) return false;
+        exec.decoders = cur.seek(i + Sizes.Header);
+        return true;
+    }
+
     /// @notice Validate and enter the payload of the next block in an execution decoder lane.
     /// @dev The selected lane remains in its existing frame so callers can decode
     /// child blocks in place. Callers should prove complete payload consumption
@@ -209,9 +242,48 @@ library Executions {
     /// @return abs Absolute position of the first payload byte.
     /// @return end Absolute position immediately after the payload.
     function enter(Execution memory exec, uint8 lane, uint spec) internal pure returns (uint abs, uint end) {
+        return enter(exec, lane, spec, 0);
+    }
+
+    /// @notice Validate a parent block and advance over a fixed payload prefix.
+    /// @dev `amount` is relative to the payload start and cannot exceed the
+    /// current parent payload. The returned `abs` remains the payload start.
+    /// @param exec Execution whose selected decoder advances over the header and fixed prefix.
+    /// @param lane Execution decoder lane to select.
+    /// @param spec Expected parent block specification.
+    /// @param amount Number of initial payload bytes to advance over.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function enter(
+        Execution memory exec,
+        uint8 lane,
+        uint spec,
+        uint amount
+    ) internal pure returns (uint abs, uint end) {
         uint cur = exec.decoders.select(lane);
         (abs, end) = Blocks.expect(cur.absolute(), spec);
-        exec.decoders = cur.seekAbs(abs);
+        if (amount > end - abs) revert Blocks.InvalidBlock();
+        exec.decoders = cur.seekAbs(abs + amount);
+    }
+
+    /// @notice Advance an execution decoder lane by a raw byte count.
+    /// @dev No block header or schema is validated.
+    /// @param exec Execution whose selected decoder cursor is advanced.
+    /// @param lane Decoder lane to select.
+    /// @param amount Number of bytes to advance.
+    function advance(Execution memory exec, uint8 lane, uint amount) internal pure {
+        uint cur = exec.decoders.select(lane);
+        exec.decoders = cur.advance(amount);
+    }
+
+    /// @notice Take a raw byte range from an execution decoder lane.
+    /// @dev No block header or schema is validated.
+    /// @param exec Execution whose selected decoder cursor is advanced.
+    /// @param lane Decoder lane to select.
+    /// @param amount Number of bytes to take.
+    /// @return abs Absolute position of the first taken byte.
+    function take(Execution memory exec, uint8 lane, uint amount) internal pure returns (uint abs) {
+        (exec.decoders, abs) = exec.decoders.consume(lane, amount);
     }
 
     /// @notice Require the active execution decoder to be at absolute position `abs`.
@@ -246,9 +318,7 @@ library Executions {
 
     /// @dev Return the next raw calldata word from `lane` and advance by `size` bytes.
     function next(Execution memory exec, uint8 lane, uint size) private pure returns (bytes32 value) {
-        uint abs;
-        (exec.decoders, abs) = exec.decoders.consume(lane, size);
-        value = Blocks.read32(abs);
+        value = Blocks.read32(take(exec, lane, size));
     }
 
     /// @notice Return the next raw byte from a decoder lane and advance it by one byte.
@@ -806,6 +876,14 @@ library Executions {
         return reserve(exec, size, size);
     }
 
+    /// @notice Append an empty block to execution output.
+    /// @param exec Execution receiving the block.
+    /// @param key Block key.
+    function outputEmpty(Execution memory exec, bytes4 key) internal pure {
+        uint i = reserve(exec, Sizes.Header);
+        Blocks.writeEmpty(exec.output, i, key);
+    }
+
     /// @notice Append an ACCOUNT block to execution output.
     /// @param exec Execution receiving the block.
     /// @param account Account identifier to encode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",
@@ -9,8 +9,7 @@
     "**/*.sol",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE",
-    "docs/Schema.md"
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"

package/ports/Dispatch.sol

@@ -11,7 +11,8 @@ using Executions for Execution;
 /// @notice Hook implemented by hosts that forward funded dispatch payloads.
 abstract contract DispatchPayableHook {
     /// @notice Override to dispatch an encoded payload to `portal`.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID. Implementations
+    /// may validate or resolve it for their transport.
     /// @param resources Chain-specific destination resources. EVM adapters
     /// may interpret this as packed execution gas and destination value.
     /// @param payload Encoded payload ready for the transport layer.

package/docs/Schema.md

@@ -1,427 +0,0 @@
-# Schema
-
-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
-payload schema.
-
-## Wire Format
-
-Every block uses the same header:
-
-```txt
-[bytes4 key][uint32 payloadLen][payload]
-```
-
-`payloadLen` is big-endian and counts only payload bytes. Child blocks and list
-items use the same header format.
-
-Standard built-in block keys use:
-
-```txt
-bytes4(keccak256("#name"))
-```
-
-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 as an annotation:
-
-```solidity
-event Annotation(uint indexed entity, bytes data);
-#schema { uint spec, #string as body, bytes32 name }
-```
-
-Annotation merge behavior is defined by the annotation block type rather than
-by the `Annotation` event. A `#schema` annotation is identified by its entity
-and the block key encoded in `spec`: distinct keys accumulate, while the latest
-trusted claim for the same key replaces the earlier one. Other annotation types
-may define additive, historical, or explicitly revocable behavior instead.
-
-The standard `#action { uint action }` annotation assigns one primary semantic
-action to an entity. The latest trusted value replaces the previous value, and
-`Actions.None` clears the classification.
-
-For example, a host-specific payment block can use a small literal, 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 definition has an event alias and a schema body. A schema body is one
-of three forms:
-
-```txt
-""                 empty or raw payload
-{ fields }         structured payload
-many #item         top-level custom list payload
-```
-
-Fixed fields are written in braces:
-
-```txt
-alias:  amount
-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 input }
-```
-
-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 root `many #item` body is reserved for an emitted custom schema
-whose own key identifies the outer list block.
-
-A structured schema body is a comma-separated list of items. Order is
-significant.
-
-```txt
-{ #amount, maybe #account as recipient }
-```
-
-## Payload Layout
-
-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 input }
-{ uint spec, #string as body, bytes32 name }
-{ #bytes as left, uint op, #bytes as right }
-```
-
-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:
-
-```txt
-#bytes as payload
-```
-
-## Modifiers
-
-Cardinality is expressed with prefix keywords:
-
-```txt
-#balance
-maybe #balance
-many #balance
-maybe many #balance
-```
-
-- no prefix: one required item
-- `maybe`: optional item
-- `many`: a list whose payload contains repeated items
-- `maybe many`: optional `#list` block
-
-`maybe` emits no placeholder when absent. Inside a structured schema body,
-`many` wraps repeated items in one generic `#list` block; it does not repeat the
-item in place:
-
-```txt
-{ uint id, many #asset as assets }
-```
-
-When an emitted custom schema consists entirely of a top-level `many` item, the
-custom schema key identifies the outer list block instead. Its payload contains
-the repeated items directly:
-
-```txt
-schema key: 0x00000001
-schema body: many #asset
-wire value: [0x00000001][length][ASSET][ASSET]...
-```
-
-This convention gives a top-level list a discoverable, context-local type while
-retaining the generic `#list` key for lists whose type is supplied by an
-enclosing schema.
-
-## Endpoint Lanes
-
-Endpoint descriptors identify each lane with a block key and group size. In
-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 uses these lane layouts:
-
-```txt
-state   [key:4][group:1]
-input   [key:4][group:1]
-output  [key:4][min:4][max:4][hint:3][group:1]
-reserve [reserved:4]
-tx      [transactions:1]
-flags   [flags:1]
-```
-
-Each lane directly identifies its top-level block key. Output lanes retain their
-size bounds and allocation hint so execution can reconstruct the output spec and
-initialize its writer directly. Four descriptor-level bytes are reserved after
-the lane metadata. The Solidity output decoder returns a left-aligned,
-writer-ready spec that retains its encoded group and clears its reserved fields.
-`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. A top-level list lane uses the key of its emitted custom
-`many` schema; the descriptor treats it like every other direct lane spec.
-
-The lane key 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 prime item cannot be optional. If an endpoint needs a per-operation marker
-with no payload, use a zero-payload block such as `#unit`.
-
-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. Endpoint decoder opening requires that run to consume
-the complete supplied lane; a trailing block with another key is invalid.
-Lower-level cursor scanning may still intentionally open only a prefix run.
-Those lower layers retain only the raw block count; descriptor strides are
-applied and lane groups reconciled once when an endpoint execution opens.
-Future protocol surfaces may use the more flexible top-level structure.
-
-For commands, complete-lane validation is also a state-safety rule. State is a
-linear value owned by the current pipeline step, not optional context that a
-command may disregard. Every command must account for the complete supplied
-state by consuming it, transforming and returning it, forwarding it intact, or
-reverting. A command whose descriptor declares an empty state lane must reject
-non-empty state. A command that accepts state must validate the complete stream
-against its declared schema; accepting only a prefix and silently dropping the
-remainder is invalid.
-
-## Live Pipeline State
-
-`#balance`, `#custody`, and `#position` are live state carried between command
-steps for the active account. A position atomically pairs an asset side with a
-liability side:
-
-```txt
-position { bytes32 asset, uint amount, bytes32 liability, uint debt }
-```
-
-The pair is deliberately general. The asset side represents value acquired or
-controlled, and the liability side represents value owed or required. Commands
-may preserve or replace either side and return a new position. The terminal
-`settle` command consumes the pair. Position state is transient protocol state;
-rewriting it does not by itself create, discharge, or replace an obligation
-persisted by a host or external protocol. The responsible command hook must
-perform or verify those effects. A command must not ignore a supplied position:
-it must explicitly consume, transform, forward, or reject it, so neither its
-asset nor its debt can disappear accidentally.
-
-This representation supports ordinary forward transformations as well as
-backward composition. For example, an exact-output route can carry its desired
-asset while successive hops replace the upstream liability:
-
-```txt
-position(C, 100, C, 100)
-→ position(C, 100, B, 50)
-→ position(C, 100, A, 25)
-→ settle
-```
-
-“Backward” describes how requirements are composed from the desired result
-toward the source. Pipeline execution is not reversed: STEP blocks always run
-forward in their encoded order. Exact-output routing is only an example;
-borrowing, refinancing, collateral transformation, callback obligations,
-cross-host claims, fees, and netting can use the same position state.
-
-## Field Aliases
-
-Block aliases are published in `#schema` annotations. Field aliases are presentation
-metadata for tooling. They do not change payload layout or runtime keys.
-
-```txt
-maybe #account as recipient
-{ uint target, uint resources, #bytes as payload }
-```
-
-Field aliases may be used on any block item, including child blocks and prime
-items.
-
-Child blocks are schema references:
-
-```txt
-{ uint handler, uint resources, bytes32 key, #bytes as witness }
-```
-
-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
-
-Field names and aliases may use dotted paths for offchain projection. A dotted
-path does not change the block key, payload bytes, payload length, cursor
-behavior, or any onchain validation. It is metadata only.
-
-```txt
-{ uint dst.portal, uint dst.resources, #bytes as dst.payload }
-```
-
-This has the same runtime layout as:
-
-```txt
-{ uint portal, uint resources, #bytes as payload }
-```
-
-Offchain tooling may decode the dotted form into a nested object:
-
-```ts
-{
-  dst: {
-    portal,
-    resources,
-    payload
-  }
-}
-```
-
-Encoding and decoding must still follow schema declaration order, not object
-property order. Fields with the same path prefix do not need to be contiguous,
-although contiguous fields are easier to read when they represent one logical
-object.
-
-Tooling should reject duplicate full paths and prefix/value collisions:
-
-```txt
-uint dst.portal, uint dst.portal    // duplicate path
-uint dst, uint dst.portal           // prefix/value collision
-```
-
-The same rule applies to field aliases:
-
-```txt
-{ uint target, uint resources, #bytes as calldata.payload }
-maybe #account as recipient.account
-```
-
-## Field Types
-
-Supported field types are chain-neutral:
-
-```txt
-uint, uint8, uint16, uint32, uint64, uint128, uint256
-int, int8, int16, int32, int64, int128, int256
-bool
-bytes1 through bytes32
-```
-
-`uint` means `uint256`; `int` means `int256`. Other integer widths, unsized
-`bytes`, `string`, and array syntax are not part of the core schema DSL.
-
-Restricting fixed bytes to the power-of-two widths `bytes1`, `bytes2`,
-`bytes4`, `bytes8`, `bytes16`, and `bytes32` is under consideration, but has
-not been decided. Until that decision is made, the schema DSL continues to
-allow every `bytesN` width from 1 through 32.
-
-Integers are encoded big-endian. Signed integers use two's-complement encoding
-for their declared width. `bool` is one byte: `0x00` for false and `0x01` for
-true. `bytesN` values are encoded as exactly `N` bytes with no padding.
-
-## Chain Resources
-
-Fields named `portal` are routing identifiers; they are often the destination
-host ID, but a transport adapter may define a different stable handle.
-
-Fields named `resources` are chain-specific resource words. A portal adapter
-interprets them for the destination runtime. Different runtimes may pack these
-words differently, but a given runtime must use one stable format everywhere.
-For EVM chains, the low 128 bits are native value / endowment in wei; higher
-bits are reserved for execution resources such as gas.
-
-## Protocol IDs
-
-Account, asset, and node ID fields use one 32-byte convention:
-
-- first byte `0x00`: opaque ID, encoded as `0x00 || bytes31(hash)`. The full
-  preimage must come from a lookup table or witness data when native metadata is
-  needed.
-- first byte nonzero: structured ID. The value may be deconstructed according
-  to its chain/runtime layout.
-
-Opaque preimages must start with a one-byte format/hash tag; `0x01` means
-keccak256. The remaining bytes are host/domain-specific until the protocol
-standardizes a fuller preimage payload format.
-
-The field name supplies the protocol role for opaque IDs. For example, a
-`bytes32 asset` whose first byte is zero is still an asset in that block; it
-just cannot be decoded without external context. Runtime helpers that inspect
-the layout of an ID only apply to structured IDs.
-
-## Identifiers
-
-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]*
-[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*
-```
-
-Invalid examples:
-
-```txt
-Amount
-asset_meta
-asset-meta
-0account
-asset.
-.asset
-```
-
-Reserved words include `maybe`, `many`, `as`, all field type names, and the
-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
-- `#string`: UTF-8 string bytes, written without a body
-- `#list`: generic list wrapper emitted by nested `many`
-
-Custom input shapes should define their own context-local block spec and publish
-it with a `#schema` annotation. Endpoint contracts can use `schema(...)` to
-construct and publish that spec:
-
-```solidity
-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 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/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 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 }
-schema   { uint spec, #string as body, bytes32 name }
-```
-
-`Keys.sol` contains the corresponding standard runtime keys.