@rootzero/contracts 1.20.0 → 1.22.0

package/CHANGELOG.md

@@ -3,6 +3,97 @@
 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
+
+- Repacked endpoint descriptors as `[state key:4][stride:1]`,
+  `[input key:4][stride:1]`,
+  `[output key:4][min:4][max:4][hint:3][stride:1]`, four reserved bytes,
+  one transaction-count byte, and one flags byte. The input child-key field was
+  removed; indexers and request builders must decode the new layout.
+- Removed container metadata and the `many` and `keys` helpers from `Specs`.
+  Top-level lists are now emitted custom schemas whose context-local key is the
+  endpoint input key; nested lists continue to use the generic `#list` key.
+- Replaced the `funded` and `admin` boolean parameters on command helpers and
+  the `funded` boolean parameter on port helpers with a packed `uint8 flags`
+  argument. Endpoint flags now live in the dedicated `Flags` library.
+- Renamed the portal lifecycle events from `Undelivered` and `Recovered` to
+  `Unresolved` and `Resolved`, and renamed `Portal.retry` to `Portal.resolve`.
+  `Portal` now composes the node-access, runtime, and lifecycle-event
+  capabilities; concrete implementations remain responsible for explicitly
+  emitting lifecycle events.
+
+### Added
+
+- Added custom-spec overloads for `Decoders.list(cur, spec)` and
+  `Executions.list(exec, spec, lane)` so custom-keyed top-level lists can use
+  the same cursor model as generic nested lists.
+- Added `Specs.lane` for canonical descriptor lane packing and exported
+  `Flags` from the codec, command, and endpoint package entry points.
+
+### Changed
+
+- Updated schema and indexing documentation and the list example for the
+  custom-keyed top-level list convention.
+
 ## 1.20.0
 
 ### Breaking Changes

package/Codec.sol

@@ -7,7 +7,7 @@ pragma solidity ^0.8.33;
 import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
-import { Descriptors } from "./codec/Descriptors.sol";
+import { Descriptors, Flags } from "./codec/Descriptors.sol";
 import { Schemas } from "./codec/Schema.sol";
 import { Decoders } from "./codec/Decoders.sol";
 import { Cursors, Cur } from "./utils/Cursors.sol";

package/Commands.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file for both standard Execution-based commands and custom decoders.
 
 import {CommandBase} from "./commands/Base.sol";
+import {Flags} from "./codec/Descriptors.sol";
 import {Execution, Executions} from "./execution/Execution.sol";
 import {Lanes} from "./utils/Lanes.sol";
 import {Blocks} from "./codec/Blocks.sol";

package/Endpoints.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
 // Shared endpoint hooks
+import {Flags} from "./codec/Descriptors.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands

package/Events.sol

@@ -12,7 +12,7 @@ import { CommanderEvent } from "./events/Commander.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
 import { ReceivedEvent } from "./events/Received.sol";
-import { RecoveredEvent } from "./events/Recovered.sol";
+import { ResolvedEvent } from "./events/Resolved.sol";
 import { RelayEvent } from "./events/Relay.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
@@ -22,7 +22,7 @@ import { NodeEvent } from "./events/Node.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { RouteEvent } from "./events/Route.sol";
 import { SpentEvent } from "./events/Spent.sol";
-import { UndeliveredEvent } from "./events/Undelivered.sol";
+import { UnresolvedEvent } from "./events/Unresolved.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";
 
 

package/README.md

@@ -114,24 +114,29 @@ 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 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
 
 A input is not a single struct; it is a run of blocks. One `#amount` block
 asks for one deposit, five blocks ask for five, and the code path is identical
 — every endpoint parses with a cursor and loops until the stream is exhausted.
 The descriptor lane key is the prime item: it is the block type that may repeat
-for batching. Plain lanes are encoded as `[key][0]`; readers interpret the zero
-group byte as group size 1 when the lane is non-empty. Generic list lanes such
-as `many #asset` are encoded as
-`[Keys.List][Keys.Asset]`, so indexers can see both the top-level LIST container
-and the item type inside it.
+for batching. Readers interpret a zero group byte as group size 1 when the lane
+is non-empty.
 
 Off-chain, building a batch is concatenation. Using the reference encoders from
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts):
@@ -308,7 +313,7 @@ abstract contract MyCommand is CommandBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
+        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, 0);
     }
 
     function myCommand(
@@ -327,6 +332,10 @@ abstract contract MyCommand is CommandBase {
 }
 ```
 
+The final argument is a packed flags byte. Pass `0` for an ordinary endpoint,
+or compose values such as `Flags.Funded`, `Flags.Admin`, and
+`Flags.AdminFunded` from the command or endpoint package entry point.
+
 The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `settlePayable` (funded settlement),
 `withdraw` and `burn` (funds out),
@@ -466,12 +475,13 @@ Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
   `Settlement`, `Pipeline`, `Portal`, validator
-- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, codec
-  helpers, and shared value types for authoring custom commands
+- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, `Flags`,
+  codec helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
-  mixins and their hooks
+  mixins, their hooks, and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
-  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`, and `Specs`
+  `Reader`/`Readers`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
+  `Specs`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts
@@ -486,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.
@@ -194,7 +250,15 @@ library Decoders {
     /// @param cur Cursor advanced past the list.
     /// @return items Cursor spanning the list payload.
     function list(Cur memory cur) internal pure returns (Cur memory items) {
-        (uint abs, uint end) = consume(cur, Specs.List);
+        return list(cur, Specs.List);
+    }
+
+    /// @notice Consume a list block described by `spec` and return a cursor over its items.
+    /// @param cur Cursor advanced past the list.
+    /// @param spec Custom list block specification.
+    /// @return items Cursor spanning the list payload.
+    function list(Cur memory cur, uint spec) internal pure returns (Cur memory items) {
+        (uint abs, uint end) = consume(cur, spec);
         items.state = Cursors.create(abs, end - abs, 0, 0, 0);
     }
 
@@ -202,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);
@@ -248,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/Descriptors.sol

@@ -4,25 +4,32 @@ pragma solidity ^0.8.33;
 import {Specs} from "./Specs.sol";
 import {Lanes} from "../utils/Lanes.sol";
 
+/// @title Flags
+/// @notice Packed endpoint behavior flags.
+library Flags {
+    /// @dev Endpoint accepts nonzero native value.
+    uint8 internal constant Funded = 1 << 0;
+    /// @dev Endpoint is restricted to the admin account.
+    uint8 internal constant Admin = 1 << 1;
+    /// @dev Endpoint accepts nonzero native value and is restricted to the admin account.
+    uint8 internal constant AdminFunded = Admin | Funded;
+}
+
 /// @title Descriptors
 /// @notice Packing and lane metadata helpers for endpoint descriptors.
 library Descriptors {
     /// @dev The requested lane is not part of an endpoint descriptor.
     error InvalidLane();
 
-    /// @dev Endpoint accepts nonzero native value.
-    uint8 internal constant Funded = 1 << 0;
-    /// @dev Endpoint is restricted to the admin account.
-    uint8 internal constant Admin = 1 << 1;
-
     /// @notice Create a descriptor from endpoint lane specifications and flags.
     /// @dev Layout: `[state key:4][stride:1]`
-    /// `[input key:4][item:4][stride:1]`
+    /// `[input key:4][stride:1]`
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
+    /// `[reserved:4]`
     /// `[transactions:1]`
     /// `[flags:1]`. Flag bits: funded = 0, admin = 1.
     /// @param state State lane specification.
-    /// @param input Input lane specification, optionally wrapped in a container.
+    /// @param input Direct input lane specification.
     /// @param output Output writer specification.
     /// @param transactions Transactions produced per batch.
     /// @param flags Endpoint behavior flags.
@@ -34,15 +41,13 @@ library Descriptors {
         uint8 transactions,
         uint8 flags
     ) internal pure returns (uint descriptor) {
-        state = Specs.normalize(state, true);
-        input = Specs.normalize(input, false);
-        output = Specs.normalize(output, true);
+        output = Specs.normalize(output);
         descriptor = pack(state, input, output, transactions, flags);
     }
 
-    /// @dev Pack normalized endpoint specs and flags into a descriptor.
-    /// @param state Normalized direct state specification.
-    /// @param input Normalized input specification.
+    /// @dev Pack endpoint specs and flags into a descriptor.
+    /// @param state State specification.
+    /// @param input Input specification.
     /// @param output Normalized direct output specification.
     /// @param transactions Transactions produced per batch.
     /// @param flags Endpoint behavior flags.
@@ -54,14 +59,9 @@ library Descriptors {
         uint8 transactions,
         uint8 flags
     ) private pure returns (uint descriptor) {
-        (bytes4 outer, bytes4 child) = Specs.keys(input);
-
-        descriptor |= uint(uint32(Specs.key(state))) << 224;
-        descriptor |= uint(Specs.stride(state)) << 216;
-        descriptor |= uint(uint32(outer)) << 184;
-        descriptor |= uint(uint32(child)) << 152;
-        descriptor |= uint(Specs.stride(input)) << 144;
-        descriptor |= (output >> 128) << 16;
+        descriptor |= uint(Specs.lane(state)) << 216;
+        descriptor |= uint(Specs.lane(input)) << 176;
+        descriptor |= (output >> 128) << 48;
         descriptor |= uint(transactions) << 8;
         descriptor |= flags;
     }
@@ -82,22 +82,22 @@ library Descriptors {
     /// @return Effective blocks per batch for the lane.
     function stride(uint descriptor, uint8 lane) internal pure returns (uint8) {
         if (lane == Lanes.State) return uint8(descriptor >> 216);
-        if (lane == Lanes.Input) return uint8(descriptor >> 144);
-        if (lane == Lanes.Output) return uint8(descriptor >> 16);
+        if (lane == Lanes.Input) return uint8(descriptor >> 176);
+        if (lane == Lanes.Output) return uint8(descriptor >> 48);
         if (lane == Lanes.Transactions) return uint8(descriptor >> 8);
         revert InvalidLane();
     }
 
     /// @notice Return the effective block key for `lane`.
-    /// @dev Input returns its outer key. Transaction blocks have a fixed
-    /// protocol key that is not stored in the descriptor.
+    /// @dev Transaction blocks have a fixed protocol key that is not stored in
+    /// the descriptor.
     /// @param descriptor Packed endpoint descriptor.
     /// @param lane Lane identifier from `Lanes`.
-    /// @return Effective outer block key for the lane.
+    /// @return Effective block key for the lane.
     function key(uint descriptor, uint8 lane) internal pure returns (bytes4) {
         if (lane == Lanes.State) return bytes4(uint32(descriptor >> 224));
         if (lane == Lanes.Input) return bytes4(uint32(descriptor >> 184));
-        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 112));
+        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 144));
         if (lane == Lanes.Transactions) return Specs.key(Specs.Transaction);
         revert InvalidLane();
     }
@@ -110,7 +110,7 @@ library Descriptors {
     /// @return growable Whether the writer may grow beyond that capacity.
     function allocation(uint descriptor, uint8 lane, uint groups) internal pure returns (uint capacity, bool growable) {
         if (lane == Lanes.Output) {
-            uint spec = uint(uint128(descriptor >> 16)) << 128;
+            uint spec = uint(uint128(descriptor >> 48)) << 128;
             return Specs.allocation(spec, groups);
         }
         if (lane == Lanes.Transactions) {