@rootzero/contracts 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -3,6 +3,131 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.23.0
+
+### Breaking Changes
+
+- Changed every command entrypoint from
+  `(bytes32 account, bytes state, bytes input)` to one `bytes context` argument
+  containing exactly one encoded `CONTEXT` block. Canonical command selectors
+  now use `(bytes)`, so every command node ID changes. Existing command callers,
+  cached IDs, and deployed host graphs are not compatible with this release.
+- Added the acting account to `Execution`. `CommandBase.openCommand` and
+  `AdminBase.openAdminCommand` now accept the encoded context and return only
+  the initialized execution, and command implementations close with
+  `closeCommand(exec)` instead of `close(exec, account)`.
+- Removed the separate state argument from `RelayPayableHook.relay`. Relay
+  implementations can obtain the complete validated state with
+  `exec.rawState()` while the explicit account and nested relay input arguments
+  remain unchanged.
+- Consolidated `AllowAssetsPort` and `DenyAssetsPort` into
+  `ports/Assets.sol`; update direct source imports to the new path.
+- Renamed the peer `AllowancePort` and `portAllowance` selector to
+  `RequestAllowancePort` and `portRequestAllowance`. The peer port now uses a
+  distinct `RequestAllowanceHook.requestAllowance` hook; the admin `Allowance`
+  command and its authoritative `AllowanceHook.allowance` hook are unchanged.
+- Removed the `Commander` event declaration. Commander addresses and chain
+  context are off-chain configuration; host, native-asset, and admin IDs are
+  deterministic from that information.
+- Prefixed every typed `Blocks` factory with `create`, including calldata-copy
+  variants; for example, use `createBalance`, `createStepCopy`, `createBytes`,
+  and `createString` instead of `balance`, `stepCopy`, `data`, and `text`.
+- Changed the `max8`, `max16`, `max24`, `max32`, `max40`, `max64`, `max96`,
+  `max128`, and `max160` bounds helpers to return their corresponding narrowed
+  integer types instead of `uint`.
+
+### Added
+
+- Added `PositionedEvent`, which publishes asset and liability sides together
+  with the semantic action that produced the observed position.
+- Added `RequestAssetPort`, which passes trusted peers' batched asset and amount
+  requests to a host hook for validation and fulfillment.
+- Added `Executions.takeBlock`, which validates and consumes a block from a
+  selected decoder lane and returns its complete calldata encoding.
+- Added `Executions.rawState` and `Executions.rawInput` for retrieving complete
+  validated calldata lanes independently of current cursor progress.
+- Added `Blocks.createAmount` for constructing canonical `AMOUNT` blocks.
+
+### Changed
+
+- Command pipeline hops now construct `command(bytes)` calldata and the nested
+  `CONTEXT` block directly in one allocation, copying memory state and calldata
+  input into the final call buffer.
+- Added memory `callPort`/`tryCallPort` helpers and calldata-copy
+  `callPortCopy`/`tryCallPortCopy` counterparts, matching the block factory
+  naming convention. Portal forwarding and recovery use the copy variants.
+
+### Upgrade Compatibility
+
+- Rebuild command IDs from the new `(bytes)` selectors, redeploy command hosts,
+  and update pipeline builders and other callers to pass one encoded `CONTEXT`
+  block. Do not mix 1.22 command IDs or callers with 1.23 deployments.
+- Update custom commands to read the acting account from `exec.account`, use
+  `openCommand(context, descriptor, batches)`, and return
+  `closeCommand(exec)`.
+- Update relay hook implementations to remove the state parameter and use
+  `exec.rawState()` when the forwarded state is required.
+- Update direct port imports, renamed request-allowance endpoints and hooks,
+  typed `Blocks` factory calls, and any assignments that relied on `max*`
+  returning `uint`.
+
+## 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/Endpoints.sol

@@ -37,12 +37,11 @@ import {Unauthorize} from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints
 import {PortBase} from "./ports/Base.sol";
-import {AllowAssetsPort} from "./ports/AllowAssets.sol";
-import {AllowancePort} from "./ports/Allowance.sol";
+import {AllowAssetsPort, DenyAssetsPort, RequestAssetPort, RequestAssetHook} from "./ports/Assets.sol";
+import {RequestAllowancePort, RequestAllowanceHook} from "./ports/Allowance.sol";
 import {RedeemBalancePort, RedeemBalanceHook} from "./ports/Redeem.sol";
 import {CreditAccountPort} from "./ports/Credit.sol";
 import {DebitAccountPort} from "./ports/Debit.sol";
-import {DenyAssetsPort} from "./ports/DenyAssets.sol";
 import {PipePayablePort} from "./ports/Pipe.sol";
 import {DispatchPayablePort, DispatchPayableHook} from "./ports/Dispatch.sol";
 import {PostPort} from "./ports/Post.sol";

package/Events.sol

@@ -8,7 +8,6 @@ import { AnnotationEvent } from "./events/Annotation.sol";
 import { AssetEvent, AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
-import { CommanderEvent } from "./events/Commander.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
 import { ReceivedEvent } from "./events/Received.sol";
@@ -19,6 +18,7 @@ import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";
 import { LockedEvent } from "./events/Locked.sol";
 import { NodeEvent } from "./events/Node.sol";
+import { PositionedEvent } from "./events/Positioned.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { RouteEvent } from "./events/Route.sol";
 import { SpentEvent } from "./events/Spent.sol";

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
 
@@ -284,19 +288,17 @@ command lanes, loop the batch, call the hook, and write the output run:
 
 ```solidity
 function deposit(
-    bytes32 account,
-    bytes calldata state,
-    bytes calldata input
+    bytes calldata context
 ) external onlyCommand returns (bytes memory, bytes memory) {
-    Execution memory exec = openCommand(state, input, descriptor, 0);
+    Execution memory exec = openCommand(context, descriptor, 0);
 
     while (exec.more()) {
         (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-        deposit(account, asset, amount); // host policy hook
+        deposit(exec.account, asset, amount); // host policy hook
         exec.outputBalance(asset, amount);
     }
 
-    return close(exec, account);
+    return closeCommand(exec);
 }
 ```
 
@@ -313,17 +315,15 @@ abstract contract MyCommand is CommandBase {
     }
 
     function myCommand(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
             // Apply command-specific behavior for this group.
             exec.outputBalance(asset, amount);
         }
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 ```
@@ -431,6 +431,12 @@ central ones are batches all the way down:
 - `portPost` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
   block — how two hosts post transactions between their ledgers.
+- `portRequestAsset` consumes `amount { bytes32 asset, uint amount }` blocks and
+  passes the authenticated peer, asset, and amount to a host hook. The hook
+  validates asset support and applies the host's request and transfer policy.
+- `portRequestAllowance` consumes the same amount blocks and lets the
+  authenticated peer request an asset allowance. The hook decides what
+  allowance, if any, to grant.
 - `portPipePayable` consumes `context` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
   host, executed locally against the port call's shared value budget.
@@ -492,7 +498,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/Action.sol

@@ -12,6 +12,6 @@ abstract contract Action is AnnotationEvent {
     /// @param entity Entity receiving the action annotation.
     /// @param value Canonical action identifier, such as a value from `Actions`.
     function action(uint entity, uint value) internal virtual {
-        emit Annotation(entity, Blocks.action(value));
+        emit Annotation(entity, Blocks.createAction(value));
     }
 }

package/annotations/Label.sol

@@ -14,6 +14,6 @@ abstract contract Label is AnnotationEvent {
     /// @param namespace Label namespace.
     /// @param name Human-readable name within the namespace.
     function label(uint entity, bytes32 namespace, string memory name) internal virtual {
-        emit Annotation(entity, Blocks.label(namespace, name));
+        emit Annotation(entity, Blocks.createLabel(namespace, name));
     }
 }

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,13 +66,21 @@ 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.
     /// @param name Schema alias name, or zero for unnamed schemas.
     /// @return The published block specification.
     function schema(uint spec, string memory body, bytes32 name) internal returns (uint) {
-        emit Annotation(host, Blocks.schema(spec, body, name));
+        emit Annotation(host, Blocks.createSchema(spec, body, name));
         return spec;
     }
 }