@rootzero/contracts 1.21.0 → 1.23.0

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 createEmpty(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.
@@ -1749,28 +1801,28 @@ library Blocks {
     // Dynamic leaf factories
 
     /// @notice Encode a LIST block.
-    function list(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createList(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeList(blockdata, 0, value);
     }
 
     /// @notice Encode a LIST block by copying its payload from calldata.
-    function listCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createListCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyList(blockdata, 0, value);
     }
 
     /// @notice Encode an EVM block.
-    function evm(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createEvm(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeEvm(blockdata, 0, value);
     }
 
     /// @notice Encode an EVM block by copying its payload from calldata.
-    function evmCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createEvmCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyEvm(blockdata, 0, value);
@@ -1779,14 +1831,14 @@ library Blocks {
     /// @notice Encode a BYTES block with a raw payload.
     /// @param value Raw payload bytes.
     /// @return blockdata Encoded BYTES block bytes.
-    function data(bytes memory value) internal pure returns (bytes memory blockdata) {
+    function createBytes(bytes memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         writeBytes(blockdata, 0, value);
     }
 
     /// @notice Encode a BYTES block by copying its payload from calldata.
-    function dataCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
+    function createBytesCopy(bytes calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(value.length);
         blockdata = allocate(Sizes.Header + len);
         copyBytes(blockdata, 0, value);
@@ -1795,14 +1847,14 @@ library Blocks {
     /// @notice Encode a STRING block with a UTF-8 payload.
     /// @param value String payload.
     /// @return blockdata Encoded STRING block bytes.
-    function text(string memory value) internal pure returns (bytes memory blockdata) {
+    function createString(string memory value) internal pure returns (bytes memory blockdata) {
         uint len = max32(bytes(value).length);
         blockdata = allocate(Sizes.Header + len);
         writeString(blockdata, 0, value);
     }
 
     /// @notice Encode a STRING block by copying its payload from calldata.
-    function textCopy(string calldata value) internal pure returns (bytes memory blockdata) {
+    function createStringCopy(string calldata value) internal pure returns (bytes memory blockdata) {
         uint len = max32(bytes(value).length);
         blockdata = allocate(Sizes.Header + len);
         copyString(blockdata, 0, value);
@@ -1814,7 +1866,7 @@ library Blocks {
     /// @param namespace Label namespace.
     /// @param name Label text.
     /// @return value Encoded LABEL block bytes.
-    function label(bytes32 namespace, string memory name) internal pure returns (bytes memory value) {
+    function createLabel(bytes32 namespace, string memory name) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B32 + bytes(name).length);
         value = allocate(Sizes.Header + len);
         writeLabel(value, 0, namespace, name);
@@ -1823,7 +1875,7 @@ library Blocks {
     /// @notice Encode an ACTION annotation block.
     /// @param actionid Canonical semantic action identifier.
     /// @return value Encoded ACTION block bytes.
-    function action(uint actionid) internal pure returns (bytes memory value) {
+    function createAction(uint actionid) internal pure returns (bytes memory value) {
         value = allocate(Sizes.B32);
         write32(value, 0, Keys.Action, bytes32(actionid));
     }
@@ -1831,9 +1883,17 @@ library Blocks {
     /// @notice Encode a SCHEMA block.
     /// @param spec Block specification.
     /// @param body Schema body.
+    /// @return value Encoded SCHEMA block bytes.
+    function createSchema(uint spec, string memory body) internal pure returns (bytes memory value) {
+        return createSchema(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) {
+    function createSchema(uint spec, string memory body, bytes32 name) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + bytes(body).length);
         value = allocate(Sizes.Header + len);
         writeSchema(value, 0, spec, body, name);
@@ -1841,11 +1901,20 @@ library Blocks {
 
     // Fixed-width factories
 
+    /// @notice Encode an AMOUNT block.
+    /// @param asset Asset identifier.
+    /// @param amount Token amount.
+    /// @return value Encoded AMOUNT block bytes.
+    function createAmount(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+        value = allocate(Sizes.Amount);
+        writeAmount(value, 0, asset, amount);
+    }
+
     /// @notice Encode a BALANCE block.
     /// @param asset Asset identifier.
     /// @param amount Token amount.
     /// @return value Encoded BALANCE block bytes.
-    function balance(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+    function createBalance(bytes32 asset, uint amount) internal pure returns (bytes memory value) {
         value = allocate(Sizes.Balance);
         writeBalance(value, 0, asset, amount);
     }
@@ -1855,7 +1924,7 @@ library Blocks {
     /// @param asset Asset identifier.
     /// @param amount Token amount.
     /// @return value Encoded CUSTODY block bytes.
-    function custody(uint host, bytes32 asset, uint amount) internal pure returns (bytes memory value) {
+    function createCustody(uint host, bytes32 asset, uint amount) internal pure returns (bytes memory value) {
         value = allocate(Sizes.B96);
         writeCustody(value, 0, host, asset, amount);
     }
@@ -1866,7 +1935,7 @@ library Blocks {
     /// @param liability Identifier for the liability side.
     /// @param debt Quantity owed on the liability side.
     /// @return value Encoded POSITION block bytes.
-    function position(
+    function createPosition(
         bytes32 asset,
         uint amount,
         bytes32 liability,
@@ -1882,7 +1951,7 @@ library Blocks {
     /// @param asset Asset identifier.
     /// @param amount Transfer amount.
     /// @return value Encoded TRANSACTION block bytes.
-    function transaction(
+    function createTransaction(
         bytes32 from,
         bytes32 to,
         bytes32 asset,
@@ -1899,14 +1968,14 @@ library Blocks {
     /// @param resources Packed resources assigned to the step.
     /// @param input Raw nested input payload.
     /// @return value Encoded STEP block bytes.
-    function step(uint cmd, uint resources, bytes memory input) internal pure returns (bytes memory value) {
+    function createStep(uint cmd, uint resources, bytes memory input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         writeStep(value, 0, cmd, resources, input);
     }
 
     /// @notice Encode a STEP block by copying its nested input from calldata.
-    function stepCopy(uint cmd, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
+    function createStepCopy(uint cmd, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         copyStep(value, 0, cmd, resources, input);
@@ -1917,50 +1986,52 @@ library Blocks {
     /// @param resources Packed resources assigned to the call.
     /// @param payload Raw calldata payload for the target.
     /// @return value Encoded CALL block bytes.
-    function call(uint target, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
+    function createCall(uint target, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         writeCall(value, 0, target, resources, payload);
     }
 
     /// @notice Encode a CALL block by copying its nested payload from calldata.
-    function callCopy(uint target, uint resources, bytes calldata payload) internal pure returns (bytes memory value) {
+    function createCallCopy(uint target, uint resources, bytes calldata payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         copyCall(value, 0, target, resources, payload);
     }
 
     /// @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.
-    function relay(uint portal, uint resources, bytes memory input) internal pure returns (bytes memory value) {
+    function createRelay(uint portal, uint resources, bytes memory input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         writeRelay(value, 0, portal, resources, input);
     }
 
     /// @notice Encode a RELAY block by copying its nested input from calldata.
-    function relayCopy(uint portal, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
+    function createRelayCopy(uint portal, uint resources, bytes calldata input) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + input.length);
         value = allocate(len);
         copyRelay(value, 0, portal, resources, input);
     }
 
     /// @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.
-    function dispatch(uint portal, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
+    function createDispatch(uint portal, uint resources, bytes memory payload) internal pure returns (bytes memory value) {
         uint len = max32(Sizes.B64 + Sizes.Header + payload.length);
         value = allocate(len);
         writeDispatch(value, 0, portal, resources, payload);
     }
 
     /// @notice Encode a DISPATCH block by copying its nested payload from calldata.
-    function dispatchCopy(
+    function createDispatchCopy(
         uint portal,
         uint resources,
         bytes calldata payload
@@ -1971,7 +2042,7 @@ library Blocks {
     }
 
     /// @notice Encode a CONTEXT block.
-    function context(
+    function createContext(
         bytes32 account,
         bytes memory state,
         bytes memory input
@@ -1982,7 +2053,7 @@ library Blocks {
     }
 
     /// @notice Encode a CONTEXT block by copying its nested streams from calldata.
-    function contextCopy(
+    function createContextCopy(
         bytes32 account,
         bytes calldata state,
         bytes calldata input
@@ -1993,7 +2064,7 @@ library Blocks {
     }
 
     /// @notice Encode a RECOVER block.
-    function recover(
+    function createRecover(
         uint handler,
         uint resources,
         bytes32 recoverykey,
@@ -2005,7 +2076,7 @@ library Blocks {
     }
 
     /// @notice Encode a RECOVER block by copying its nested witness from calldata.
-    function recoverCopy(
+    function createRecoverCopy(
         uint handler,
         uint resources,
         bytes32 recoverykey,

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.