@rootzero/contracts 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.9.0
+
+### Breaking Changes
+
+- Renamed relay and dispatch routing fields from `chain` to `portal` across
+  schemas, cursor helpers, dispatch hooks, and dispatch/route events.
+- Replaced the context-specific `RecoverContextPayable` / `#contextRecovery`
+  surface with generic `RecoverPayable` / `#recover` using byte witnesses.
+- Renamed the `Dispatch` event correlation field from `ref` to `key`.
+- Replaced `DispatchPayableHook.dispatch` with `RoutePayableHook.route` in the
+  portal core layer.
+- Added `status` to `Route(uint indexed host, uint portal, uint status)`
+  so routes can be removed by emitting zero status.
+- Added `Undelivered(uint indexed host, bytes32 key, bytes32 digest)` for portal
+  messages that could not be delivered to their handler port.
+- Added `Resolved(uint indexed host, bytes32 key)` as the
+  matching event for resolved undelivered digests.
+- Removed the generic `Commitments` core mixin and `Commitment` event in favor
+  of domain-specific events such as `Undelivered` and `Resolved`.
+
 ## 1.8.0
 
 ### Breaking Changes

package/Core.sol

@@ -6,13 +6,13 @@ pragma solidity ^0.8.33;
 
 import { AccessControl } from "./core/Access.sol";
 import { Balances, InsufficientFunds } from "./core/Balances.sol";
-import { Commitments } from "./core/Commitments.sol";
 import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Host, IHostIntroduction } from "./core/Host.sol";
 import { CommandCalls, FailedCall, NodeCalls, PortCalls } from "./core/Calls.sol";
 import { Payable } from "./core/Payable.sol";
 import { Pipeline } from "./core/Pipeline.sol";
+import { Portal, RecoverHook, RoutePayableHook } from "./core/Portal.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 

package/Endpoints.sol

@@ -16,8 +16,9 @@ import { DebitAccount, DebitAccountHook } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
-import { RecoverContextPayable, RecoverContextPayableHook } from "./commands/Recover.sol";
-import { RelayPayable, DispatchPayableHook } from "./commands/Relay.sol";
+import { RecoverPayable } from "./commands/Recover.sol";
+import { RelayPayable } from "./commands/Relay.sol";
+import { RecoverHook, RoutePayableHook } from "./core/Portal.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands

package/Events.sol

@@ -10,10 +10,10 @@ import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
 import { CommanderEvent } from "./events/Commander.sol";
 import { CommandEvent } from "./events/Command.sol";
-import { CommitmentEvent } from "./events/Commitment.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
+import { ResolvedEvent } from "./events/Resolved.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardEvent } from "./events/Guard.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
@@ -26,6 +26,7 @@ import { QueryEvent } from "./events/Query.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 { UnlockedEvent } from "./events/Unlocked.sol";
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 rootzero is a protocol for building **hosts**: contracts that expose a uniform
 set of endpoints over accounts and assets — commands that change state,
-queries that read it, and peer links that connect hosts to each other, on the
+queries that read it, and port links that connect hosts to each other, on the
 same chain or across chains.
 
 This repository is `@rootzero/contracts`, the Solidity library for the EVM port
@@ -160,7 +160,7 @@ structured ID announces what it is (an account, an asset, a node) and which
 chain it lives on, and the payload usually embeds the underlying address. User
 accounts are chain-agnostic; admin and guardian accounts are chain-local.
 Assets are unique IDs in the same single-word form as accounts and nodes.
-Nodes are hosts, commands, peers, queries, and guards.
+Nodes are hosts, commands, ports, queries, and guards.
 
 Opaque asset declarations use `Asset(host, asset, preimage)`. The preimage
 starts with a one-byte format/hash tag, letting offchain indexers or witnesses
@@ -258,7 +258,7 @@ The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
 state to other accounts), `provision` (allocate custody on another host), and
-`relayPayable` (hand a pipeline to another chain).
+`relayPayable` (hand a pipeline to another portal).
 
 ## Pipelines
 
@@ -285,9 +285,9 @@ if (state.length != 0) revert UnexpectedState();
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
 `#amount` request into `#balance` state, and `payout` consumes that state
 toward a recipient. Because a pipeline is just blocks, it is also the unit of
-command batching — and `resources` is a chain-typed word (on EVM, the low 128
-bits are native value in wei, drawn from a shared budget), so the same pipeline
-bytes are meaningful to every port.
+command batching — and `resources` is a chain-specific word interpreted by the
+portal adapter (on EVM, the low 128 bits are native value in wei, drawn from a
+shared budget), so the same pipeline bytes are meaningful to every port.
 
 ## Queries
 
@@ -314,10 +314,11 @@ central ones are batches all the way down:
   block — how two hosts record settlement between their ledgers.
 - `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 peer call's shared value budget.
+  host, executed locally against the port call's shared value budget.
 
-This is also the cross-chain mechanism. `relayPayable` (or `portDispatchPayable`)
-wraps a pipe and addresses it to a chain; a bridge adapter moves the **raw
+This is also the cross-portal mechanism. `relayPayable` (or `portDispatchPayable`)
+wraps a pipe and addresses it to a portal, commonly the destination host ID;
+a bridge adapter moves the **raw
 bytes**; the destination host parses them with the same cursor rules and runs
 the same pipeline loop. Nothing in the payload is EVM-specific — step targets
 are destination-local node IDs, and only the adapter boundary (native
@@ -350,8 +351,8 @@ names, access sets, balances — from logs alone, with no artifact files.
 Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
-  `Pipeline`, validator
-- `@rootzero/contracts/Endpoints.sol` — command, admin, peer, guard, and query
+  `Pipeline`, `Portal`, validator
+- `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
   mixins and their hooks
 - `@rootzero/contracts/Cursors.sol` — `Cur` cursor reader, `Writers`, `Schemas`,
   `Keys`
@@ -363,7 +364,7 @@ Repo layout:
 
 - `contracts/core` — host, access control, balances, pipeline, validation
 - `contracts/commands` — standard commands and admin commands
-- `contracts/ports` — peer surfaces for inter-host and cross-chain flows
+- `contracts/ports` — port surfaces for inter-host and cross-portal flows
 - `contracts/guards` — guardian direct actions
 - `contracts/queries` — read-only query endpoints
 - `contracts/blocks` — block schema, cursor parsing, writers

package/blocks/Cursors.sol

@@ -519,7 +519,7 @@ library Cursors {
 
     /// @notice Encode a STEP block.
     /// @param target Command target identifier.
-    /// @param resources Chain resources assigned to the step.
+    /// @param resources Packed resources assigned to the step.
     /// @param request Raw nested request payload.
     /// @return Encoded STEP block bytes.
     function toStepBlock(uint target, uint resources, bytes memory request) internal pure returns (bytes memory) {
@@ -528,7 +528,7 @@ library Cursors {
 
     /// @notice Encode a CALL block.
     /// @param target Target node identifier.
-    /// @param resources Chain resources assigned to the call.
+    /// @param resources Packed resources assigned to the call.
     /// @param data Raw calldata payload for the target.
     /// @return Encoded CALL block bytes.
     function toCallBlock(uint target, uint resources, bytes memory data) internal pure returns (bytes memory) {
@@ -549,21 +549,21 @@ library Cursors {
     }
 
     /// @notice Encode a RELAY block.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific resources for the destination context.
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param resources Chain-specific resources for the destination context.
     /// @param request Nested request block stream.
     /// @return Encoded RELAY block bytes.
-    function toRelayBlock(uint chain, uint resources, bytes memory request) internal pure returns (bytes memory) {
-        return createBlock(Keys.Relay, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(request)));
+    function toRelayBlock(uint portal, uint resources, bytes memory request) internal pure returns (bytes memory) {
+        return createBlock(Keys.Relay, bytes.concat(bytes32(portal), bytes32(resources), toBytesBlock(request)));
     }
 
     /// @notice Encode a DISPATCH block.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific resources for the destination dispatch.
-    /// @param payload Encoded cross-chain payload.
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param resources Chain-specific resources for the destination dispatch.
+    /// @param payload Encoded payload.
     /// @return Encoded DISPATCH block bytes.
-    function toDispatchBlock(uint chain, uint resources, bytes memory payload) internal pure returns (bytes memory) {
-        return createBlock(Keys.Dispatch, bytes.concat(bytes32(chain), bytes32(resources), toBytesBlock(payload)));
+    function toDispatchBlock(uint portal, uint resources, bytes memory payload) internal pure returns (bytes memory) {
+        return createBlock(Keys.Dispatch, bytes.concat(bytes32(portal), bytes32(resources), toBytesBlock(payload)));
     }
 
     // -------------------------------------------------------------------------
@@ -1100,7 +1100,7 @@ library Cursors {
     /// The `req` slice is the raw payload of the block's required BYTES child.
     /// @param cur Cursor; advanced past the block.
     /// @return target Destination node ID for the sub-command.
-    /// @return resources Chain resources assigned to the step.
+    /// @return resources Packed resources assigned to the step.
     /// @return req Embedded request bytes for the sub-command.
     function unpackStep(Cur memory cur) internal pure returns (uint target, uint resources, bytes calldata req) {
         uint end = cur.enter(Keys.Step, 64 + Sizes.Header, 0);
@@ -1114,7 +1114,7 @@ library Cursors {
     /// The `data` slice is the raw payload of the block's required BYTES child.
     /// @param cur Cursor; advanced past the block.
     /// @return target Target node ID to call.
-    /// @return resources Chain resources assigned to the call.
+    /// @return resources Packed resources assigned to the call.
     /// @return data Raw calldata payload for the target.
     function unpackCall(Cur memory cur) internal pure returns (uint target, uint resources, bytes calldata data) {
         uint end = cur.enter(Keys.Call, 64 + Sizes.Header, 0);
@@ -1140,50 +1140,50 @@ library Cursors {
         cur.exit(end);
     }
 
-    /// @notice Consume a RELAY block and return its destination chain, resources, and request stream.
+    /// @notice Consume a RELAY block and return its destination portal, resources, and request stream.
     /// @param cur Cursor; advanced past the block.
-    /// @return chain Destination chain node ID.
-    /// @return resources Chain-adapter-specific resources for the destination context.
+    /// @return portal Destination portal identifier, often the destination host ID.
+    /// @return resources Chain-specific resources for the destination context.
     /// @return request Embedded request block stream.
     function unpackRelay(
         Cur memory cur
-    ) internal pure returns (uint chain, uint resources, bytes calldata request) {
+    ) internal pure returns (uint portal, uint resources, bytes calldata request) {
         uint end = cur.enter(Keys.Relay, 64 + Sizes.Header, 0);
-        chain = cur.readUint();
+        portal = cur.readUint();
         resources = cur.readUint();
         request = cur.unpackBytes();
         cur.exit(end);
     }
 
-    /// @notice Consume a DISPATCH block and return its destination chain, resources, and payload.
+    /// @notice Consume a DISPATCH block and return its destination portal, resources, and payload.
     /// @param cur Cursor; advanced past the block.
-    /// @return chain Destination chain node ID.
-    /// @return resources Chain-adapter-specific resources for the destination dispatch.
-    /// @return payload Encoded cross-chain payload.
+    /// @return portal Destination portal identifier, often the destination host ID.
+    /// @return resources Chain-specific resources for the destination dispatch.
+    /// @return payload Encoded payload.
     function unpackDispatch(
         Cur memory cur
-    ) internal pure returns (uint chain, uint resources, bytes calldata payload) {
+    ) internal pure returns (uint portal, uint resources, bytes calldata payload) {
         uint end = cur.enter(Keys.Dispatch, 64 + Sizes.Header, 0);
-        chain = cur.readUint();
+        portal = cur.readUint();
         resources = cur.readUint();
         payload = cur.unpackBytes();
         cur.exit(end);
     }
 
-    /// @notice Consume a CONTEXT_RECOVERY block and return its port, key, resources, and embedded context cursor.
+    /// @notice Consume a RECOVER block and return its handler, resources, key, and witness bytes.
     /// @param cur Cursor; advanced past the block.
-    /// @return port Recovery handler port node ID.
-    /// @return key Commitment or recovery lookup key.
-    /// @return resources Chain resources assigned to the recovery attempt.
-    /// @return context Cursor scoped to the embedded CONTEXT witness block.
-    function unpackContextRecovery(
+    /// @return handler Recovery handler port node ID.
+    /// @return resources Packed resources assigned to the recovery attempt.
+    /// @return key Recovery lookup key.
+    /// @return witness Witness bytes used by the recovery handler.
+    function unpackRecover(
         Cur memory cur
-    ) internal pure returns (uint port, bytes32 key, uint resources, Cur memory context) {
-        uint end = cur.enter(Keys.ContextRecovery, 96 + Sizes.Header, 0);
-        port = cur.readUint();
-        key = cur.read32();
+    ) internal pure returns (uint handler, uint resources, bytes32 key, bytes calldata witness) {
+        uint end = cur.enter(Keys.Recover, 96 + Sizes.Header, 0);
+        handler = cur.readUint();
         resources = cur.readUint();
-        context = cur.take(Keys.Context);
+        key = cur.read32();
+        witness = cur.unpackBytes();
         cur.exit(end);
     }
 
@@ -1379,16 +1379,16 @@ library Cursors {
     /// @param cur Cursor; advanced past the RELAY block.
     /// @param account Account identifier to embed in the destination context.
     /// @param state State block stream to embed in the destination context.
-    /// @return chain Destination chain node ID.
-    /// @return resources Chain resources assigned to the destination context.
+    /// @return portal Destination portal identifier, often the destination host ID.
+    /// @return resources Chain-specific resources assigned to the destination context.
     /// @return context Encoded CONTEXT block containing `account`, `state`, and relay request.
     function relayToContext(
         Cur memory cur,
         bytes32 account,
         bytes calldata state
-    ) internal pure returns (uint chain, uint resources, bytes memory context) {
+    ) internal pure returns (uint portal, uint resources, bytes memory context) {
         bytes calldata request;
-        (chain, resources, request) = cur.unpackRelay();
+        (portal, resources, request) = cur.unpackRelay();
         context = toContextBlock(account, bytes(state), bytes(request));
     }
 

package/blocks/Keys.sol

@@ -41,13 +41,13 @@ library Keys {
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
     /// @dev Sub-command invocation - (uint target, uint resources, #bytes as request)
     bytes4 constant Step = bytes4(keccak256("#step"));
-    /// @dev Cross-chain relay request - (uint chain, uint resources, #bytes as request)
+    /// @dev Portal relay request - (uint portal, uint resources, #bytes as request)
     bytes4 constant Relay = bytes4(keccak256("#relay"));
     /// @dev Command context transport - (bytes32 account, #bytes as state, #bytes as request)
     bytes4 constant Context = bytes4(keccak256("#context"));
-    /// @dev Recoverable context witness - (uint port, bytes32 key, uint resources, #context)
-    bytes4 constant ContextRecovery = bytes4(keccak256("#contextRecovery"));
-    /// @dev Cross-chain encoded payload dispatch - (uint chain, uint resources, #bytes as payload)
+    /// @dev Recoverable witness - (uint handler, uint resources, bytes32 key, #bytes as witness)
+    bytes4 constant Recover = bytes4(keccak256("#recover"));
+    /// @dev Portal encoded payload dispatch - (uint portal, uint resources, #bytes as payload)
     bytes4 constant Dispatch = bytes4(keccak256("#dispatch"));
     /// @dev Raw external call - (uint target, uint resources, #bytes as payload)
     bytes4 constant Call = bytes4(keccak256("#call"));

package/blocks/Schema.sol

@@ -16,10 +16,11 @@ pragma solidity ^0.8.33;
 // - run items may repeat at top level for batching
 // - `maybe #x { ... }` marks an optional block item
 // - `many #x { ... }` emits one generic list block containing repeated `#x` items
-// - `resources` fields are chain-specific resource words; one chain type may
-//   pack them differently from another, but a given chain type must use one
-//   stable format everywhere. EVM resources use the low 128 bits as native value.
-// - dotted field names and aliases, e.g. `dst.chain` or `#bytes as dst.payload`,
+// - `portal` fields are routing identifiers, often destination host IDs
+// - `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
 // - a child block without an inline body, e.g. `#context as witness`, may resolve
 //   to a known schema in the active schema context; unresolved aliases are invalid
@@ -71,11 +72,11 @@ library Schemas {
     string constant Allowance = "#allowance { uint host, bytes32 asset, uint amount }";
     string constant Transaction = "#transaction { bytes32 from, bytes32 to, bytes32 asset, uint amount }";
     string constant Context = "#context { bytes32 account, #bytes as state, #bytes as request }";
-    string constant ContextRecovery = "#contextRecovery { uint port, bytes32 key, uint resources, #context as witness }";
+    string constant Recover = "#recover { uint handler, uint resources, bytes32 key, #bytes as witness }";
     string constant Call = "#call { uint target, uint resources, #bytes as payload }";
     string constant Step = "#step { uint target, uint resources, #bytes as request }";
-    string constant Relay = "#relay { uint chain, uint resources, #bytes as request }";
-    string constant Dispatch = "#dispatch { uint chain, uint resources, #bytes as payload }";
+    string constant Relay = "#relay { uint portal, uint resources, #bytes as request }";
+    string constant Dispatch = "#dispatch { uint portal, uint resources, #bytes as payload }";
     string constant Bounty = "#bounty { uint amount, bytes32 relayer }";
     string constant Fee = "#fee { uint amount }";
     string constant Auth = "#auth { uint cid, uint deadline, #bytes as proof }";

package/blocks/Writers.sol

@@ -872,7 +872,7 @@ library Writers {
     /// @notice Append a STEP block with a nested request BYTES payload.
     /// @param writer Destination writer; `i` is advanced by the encoded STEP block length.
     /// @param target Command target identifier.
-    /// @param resources Chain resources assigned to the step.
+    /// @param resources Packed resources assigned to the step.
     /// @param request Raw nested request payload.
     function appendStep(Writer memory writer, uint target, uint resources, bytes memory request) internal pure {
         appendBlock64Bytes(writer, Keys.Step, bytes32(target), bytes32(resources), request);
@@ -881,7 +881,7 @@ library Writers {
     /// @notice Append a CALL block with a nested payload BYTES block.
     /// @param writer Destination writer; `i` is advanced by the encoded CALL block length.
     /// @param target Call target identifier.
-    /// @param resources Chain resources assigned to the call.
+    /// @param resources Packed resources assigned to the call.
     /// @param data Raw nested call payload.
     function appendCall(Writer memory writer, uint target, uint resources, bytes memory data) internal pure {
         appendBlock64Bytes(writer, Keys.Call, bytes32(target), bytes32(resources), data);

package/commands/Recover.sol

@@ -3,42 +3,35 @@ pragma solidity ^0.8.33;
 
 import {CommandBase, CommandContext, Keys} from "./Base.sol";
 import {Payable} from "../core/Payable.sol";
+import {RecoverHook} from "../core/Portal.sol";
 import {Cursors, Cur, Schemas} from "../Cursors.sol";
 import {Budget} from "../utils/Value.sol";
 
 using Cursors for Cur;
 
-abstract contract RecoverContextPayableHook {
-    /// @notice Override to recover one committed context witness.
-    /// @param port Recovery handler port node ID.
-    /// @param key Commitment or recovery lookup key.
-    /// @param resources Chain resources assigned to the recovery attempt.
-    /// @param context Cursor scoped to the embedded CONTEXT witness block.
-    /// @param budget Mutable native-value budget available to the recovery attempt.
-    function recoverContext(uint port, bytes32 key, uint resources, Cur memory context, Budget memory budget) internal virtual;
-}
-
-/// @title RecoverContextPayable
-/// @notice Command that forwards ContextRecovery request blocks to a virtual hook.
+/// @title RecoverPayable
+/// @notice Command that forwards recover request blocks to a virtual hook.
+/// Recovery is witness-driven: the command account pays and receives leftover
+/// value settlement, but the recovered subject is defined by each witness.
 /// Produces no output state.
-abstract contract RecoverContextPayable is CommandBase, Payable, RecoverContextPayableHook {
-    uint internal immutable recoverContextPayableId = commandId(this.recoverContextPayable.selector);
+abstract contract RecoverPayable is CommandBase, Payable, RecoverHook {
+    uint internal immutable recoverPayableId = commandId(this.recoverPayable.selector);
 
     constructor() {
-        emit Command(host, recoverContextPayableId, "1:0:0", Schemas.ContextRecovery, Keys.Empty, Keys.Empty, true);
-        emit Labeled(recoverContextPayableId, bytes32(0), "recoverContextPayable");
+        emit Command(host, recoverPayableId, "1:0:0", Schemas.Recover, Keys.Empty, Keys.Empty, true);
+        emit Labeled(recoverPayableId, bytes32(0), "recoverPayable");
     }
 
-    /// @notice Recover each ContextRecovery block in the command request.
-    /// @param c Command context; `c.request` must contain ContextRecovery blocks.
+    /// @notice Recover each recover block in the command request.
+    /// @param c Command context; `c.request` must contain Recover blocks.
     /// @return Empty output state.
-    function recoverContextPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory) {
+    function recoverPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory) {
         (Cur memory request, , ) = Cursors.init(c.request, 1);
         Budget memory budget = openValue();
 
         while (request.i < request.len) {
-            (uint port, bytes32 key, uint resources, Cur memory context) = request.unpackContextRecovery();
-            recoverContext(port, key, resources, context, budget);
+            (uint handler, uint resources, bytes32 key, bytes calldata witness) = request.unpackRecover();
+            recover(handler, key, witness, useValue(budget, resources));
         }
 
         closeValue(c.account, budget);

package/commands/Relay.sol

@@ -3,28 +3,18 @@ pragma solidity ^0.8.33;
 
 import {CommandBase, CommandContext, Keys} from "./Base.sol";
 import {Payable} from "../core/Payable.sol";
+import {RoutePayableHook} from "../core/Portal.sol";
 import {Cursors, Cur, Schemas} from "../Cursors.sol";
 import {Budget} from "../utils/Value.sol";
 
 using Cursors for Cur;
 
-abstract contract DispatchPayableHook {
-    /// @notice Override to dispatch an encoded payload to `chain`.
-    /// @param chain Destination chain node ID.
-    /// @param resources Chain-adapter-specific destination resources. EVM adapters
-    /// may interpret this as packed execution gas and destination value.
-    /// @param payload Encoded payload ready for the transport layer.
-    /// @param budget Source-chain native-value budget available for transport
-    /// fees and destination resource funding.
-    function dispatch(uint chain, uint resources, bytes memory payload, Budget memory budget) internal virtual;
-}
-
 /// @title RelayPayable
 /// @notice Command that forwards one RELAY block to a host-defined relay hook.
 /// Reverts unless the request contains exactly one RELAY block, preventing
 /// the same state from being duplicated across multiple relays.
 /// Produces no output state.
-abstract contract RelayPayable is CommandBase, Payable, DispatchPayableHook {
+abstract contract RelayPayable is CommandBase, Payable, RoutePayableHook {
     uint internal immutable relayPayableId = commandId(this.relayPayable.selector);
 
     constructor() {
@@ -39,9 +29,9 @@ abstract contract RelayPayable is CommandBase, Payable, DispatchPayableHook {
         (Cur memory request, ) = Cursors.init(c.request, 1, 1);
         Budget memory budget = openValue();
 
-        (uint chain, uint resources, bytes memory context) = request.relayToContext(c.account, c.state);
-        dispatch(chain, resources, context, budget);
-        
+        (uint portal, uint resources, bytes memory context) = request.relayToContext(c.account, c.state);
+        route(portal, resources, context, budget);
+
         closeValue(c.account, budget);
         request.complete();
         return "";

package/commands/admin/Destroy.sol

@@ -18,6 +18,7 @@ abstract contract DestroyHook {
 abstract contract Destroy is AdminBase, DestroyHook {
     uint internal immutable destroyId = commandId(this.destroy.selector);
 
+    /// @param input Request schema advertised for destruction input.
     constructor(string memory input) {
         emit Admin(host, destroyId, "1:0:0", input, Keys.Empty, Keys.Empty, false);
         emit Labeled(destroyId, bytes32(0), "destroy");

package/commands/admin/Execute.sol

@@ -10,7 +10,7 @@ using Cursors for Cur;
 
 /// @title ExecutePayable
 /// @notice Admin command that forwards raw calldata to one or more target nodes.
-/// Each CALL block specifies a target node ID, chain resources, and raw calldata payload.
+/// Each CALL block specifies a target node ID, packed resources, and raw calldata payload.
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` remains on this host.
 abstract contract ExecutePayable is AdminBase, Payable {

package/commands/admin/Init.sol

@@ -18,6 +18,7 @@ abstract contract InitHook {
 abstract contract Init is AdminBase, InitHook {
     uint internal immutable initId = commandId(this.init.selector);
 
+    /// @param input Request schema advertised for initialization input.
     constructor(string memory input) {
         emit Admin(host, initId, "1:0:0", input, Keys.Empty, Keys.Empty, false);
         emit Labeled(initId, bytes32(0), "init");

package/core/Access.sol

@@ -30,6 +30,7 @@ abstract contract AccessControl is Runtime, NodeEvent, GuardianEvent {
     /// @dev Thrown when a caller, account, or node lacks required access.
     error AccessDenied();
 
+    /// @param cmdr Commander address, or zero to make this contract self-managed.
     constructor(address cmdr) {
         commander = addrOr(cmdr, address(this));
         admin = Accounts.toAdmin(commander);

package/core/Calls.sol

@@ -107,12 +107,23 @@ abstract contract CommandCalls is NodeCalls {
 /// @title PortCalls
 /// @notice Trusted port-call helpers for contracts that route port nodes.
 abstract contract PortCalls is NodeCalls {
+    /// @notice Try to encode and call a trusted port node.
+    /// @param port Port node ID embedding the target selector.
+    /// @param value Native value to forward in wei.
+    /// @param input Port input block stream.
+    /// @return success True if the low-level port call succeeded.
+    function tryCallPort(uint port, uint128 value, bytes calldata input) internal returns (bool success) {
+        bytes4 selector = Nodes.portSelector(port);
+        bytes memory data = abi.encodeWithSelector(selector, input);
+        return tryTrustedCall(port, value, data);
+    }
+
     /// @notice Encode and call a trusted port node.
     /// @param port Port node ID embedding the target selector.
     /// @param value Native value to forward in wei.
     /// @param input Port input block stream.
     /// @return Decoded port output block stream.
-    function callPort(uint port, uint128 value, bytes memory input) internal returns (bytes memory) {
+    function callPort(uint port, uint128 value, bytes calldata input) internal returns (bytes memory) {
         bytes4 selector = Nodes.portSelector(port);
         bytes memory data = abi.encodeWithSelector(selector, input);
         return abi.decode(trustedCall(port, value, data), (bytes));

package/core/Payable.sol

@@ -19,7 +19,7 @@ abstract contract Payable {
     /// @notice Deduct the EVM value lane from a packed resource word and return it.
     /// @dev EVM resources use the low 128 bits as native value/endowment.
     /// @param budget Mutable budget to deduct from.
-    /// @param resources Packed chain resources.
+    /// @param resources Packed resources.
     /// @return value Native value to forward in wei.
     function useValue(Budget memory budget, uint resources) internal pure returns (uint128 value) {
         value = uint128(resources);

package/core/Portal.sol

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {PortCalls} from "./Calls.sol";
+import {ResolvedEvent} from "../events/Resolved.sol";
+import {UndeliveredEvent} from "../events/Undelivered.sol";
+import {Budget} from "../utils/Value.sol";
+
+abstract contract RoutePayableHook {
+    /// @notice Override to route an encoded payload through `portal`.
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @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.
+    /// @param budget Source native-value budget available for transport
+    /// fees and destination resource funding.
+    function route(uint portal, uint resources, bytes memory payload, Budget memory budget) internal virtual;
+}
+
+abstract contract RecoverHook {
+    /// @notice Override to recover a previously undelivered witness through `handler`.
+    /// @param handler Port that should attempt recovery.
+    /// @param key Recovery lookup key.
+    /// @param witness Witness payload used to prove and replay recovery.
+    /// @param value Native EVM value assigned to the recovery attempt.
+    function recover(uint handler, bytes32 key, bytes calldata witness, uint128 value) internal virtual;
+}
+
+/// @title Portal
+/// @notice Base contract for hosts that route payloads through portal adapters.
+abstract contract Portal is PortCalls, RecoverHook, ResolvedEvent, UndeliveredEvent {
+    error BadWitness();
+
+    /// @dev Remote port used to handle messages delivered through this portal.
+    uint private immutable port;
+
+    mapping(bytes32 key => bytes32 digest) internal undelivered;
+
+    /// @param handler Remote port used to handle messages delivered through this portal.
+    constructor(uint handler) {
+        port = handler;
+    }
+
+    /// @notice Try to deliver `message` to this portal's handler port.
+    /// @dev Records `keccak256(message)` under `key` only when delivery fails.
+    /// @param key Delivery/recovery lookup key.
+    /// @param message Encoded port input to deliver.
+    /// @param value Native EVM value assigned to the delivery attempt.
+    function deliver(bytes32 key, bytes calldata message, uint128 value) internal {
+        if (tryCallPort(port, value, message)) return;
+        bytes32 digest = keccak256(message);
+        undelivered[key] = digest;
+        emit Undelivered(host, key, digest);
+    }
+
+    /// @notice Recover a previously undelivered witness through `handler`.
+    /// @dev The witness must hash to the digest stored under `key`.
+    /// @param handler Port that should attempt recovery.
+    /// @param key Recovery lookup key.
+    /// @param witness Witness payload used to prove and replay recovery.
+    /// @param value Native EVM value assigned to the recovery attempt.
+    function recover(uint handler, bytes32 key, bytes calldata witness, uint128 value) internal virtual override {
+        if (keccak256(witness) != undelivered[key]) revert BadWitness();
+        delete undelivered[key];
+        callPort(handler, value, witness);
+        emit Resolved(host, key);
+    }
+}

package/docs/Schema.md

@@ -120,7 +120,7 @@ Aliases may be used on any block item, including child blocks and prime items.
 A child block without an inline body may also be used as a schema reference:
 
 ```txt
-#contextRecovery { uint port, bytes32 key, uint resources, #context as witness }
+#recover { uint handler, uint resources, bytes32 key, #bytes as witness }
 ```
 
 Alias resolution is context-dependent. A consumer may resolve `#context` from the
@@ -136,13 +136,13 @@ path does not change the block key, payload bytes, payload length, cursor
 behavior, or any onchain validation. It is metadata only.
 
 ```txt
-#dispatch { uint dst.chain, uint dst.resources, #bytes as dst.payload }
+#dispatch { uint dst.portal, uint dst.resources, #bytes as dst.payload }
 ```
 
 This has the same runtime layout as:
 
 ```txt
-#dispatch { uint chain, uint resources, #bytes as payload }
+#dispatch { uint portal, uint resources, #bytes as payload }
 ```
 
 Offchain tooling may decode the dotted form into a nested object:
@@ -150,7 +150,7 @@ Offchain tooling may decode the dotted form into a nested object:
 ```ts
 {
   dst: {
-    chain,
+    portal,
     resources,
     payload
   }
@@ -165,8 +165,8 @@ object.
 Tooling should reject duplicate full paths and prefix/value collisions:
 
 ```txt
-uint dst.chain, uint dst.chain      // duplicate path
-uint dst, uint dst.chain            // prefix/value collision
+uint dst.portal, uint dst.portal    // duplicate path
+uint dst, uint dst.portal           // prefix/value collision
 ```
 
 The same rule applies to block aliases:
@@ -196,10 +196,14 @@ true. `bytesN` values are encoded as exactly `N` bytes with no padding.
 
 ## Chain Resources
 
-Fields named `resources` are chain-specific resource words. Different chain
-types may pack these words differently, but a given chain type 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.
+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
 
@@ -282,7 +286,7 @@ Common protocol schemas live in `contracts/blocks/Schema.sol`:
 #call { uint target, uint resources, #bytes as payload }
 #step { uint target, uint resources, #bytes as request }
 #context { bytes32 account, #bytes as state, #bytes as request }
-#contextRecovery { uint port, bytes32 key, uint resources, #context as witness }
+#recover { uint handler, uint resources, bytes32 key, #bytes as witness }
 #auth { uint cid, uint deadline, #bytes as proof }
 ```
 

package/events/Dispatch.sol

@@ -5,14 +5,14 @@ import {EventEmitter} from "./Emitter.sol";
 
 /// @notice Emitted when a host records an outbound dispatch reference.
 abstract contract DispatchEvent is EventEmitter {
-    string private constant ABI = "event Dispatch(uint indexed host, uint chain, uint resources, bytes32 digest, bytes32 ref)";
+    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 chain Destination chain/domain node ID.
-    /// @param resources Chain-adapter-specific resources assigned to the dispatch.
+    /// @param portal Destination portal identifier, often the destination 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.
-    /// @param ref Dispatch correlation or recovery reference.
-    event Dispatch(uint indexed host, uint chain, uint resources, bytes32 digest, bytes32 ref);
+    event Dispatch(uint indexed host, uint portal, uint resources, bytes32 key, bytes32 digest);
 
     constructor() {
         emit EventAbi(ABI);

package/events/Resolved.sol

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted when a host resolves a previously recorded key.
+abstract contract ResolvedEvent is EventEmitter {
+    string private constant ABI = "event Resolved(uint indexed host, bytes32 key)";
+
+    /// @param host Host node ID that owns the resolved key.
+    /// @param key Resolution lookup key.
+    event Resolved(uint indexed host, bytes32 key);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Route.sol

@@ -3,14 +3,14 @@ pragma solidity ^0.8.33;
 
 import {EventEmitter} from "./Emitter.sol";
 
-/// @notice Emitted when a host announces a route to another chain/domain.
+/// @notice Emitted when a host updates a portal route.
 abstract contract RouteEvent is EventEmitter {
-    string private constant ABI = "event Route(uint indexed host, uint chain, uint context)";
+    string private constant ABI = "event Route(uint indexed host, uint portal, uint status)";
 
     /// @param host Host node ID that owns the route.
-    /// @param chain Destination chain/domain node ID.
-    /// @param context Route context identifier.
-    event Route(uint indexed host, uint chain, uint context);
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param status Route status. Zero means inactive; nonzero means active.
+    event Route(uint indexed host, uint portal, uint status);
 
     constructor() {
         emit EventAbi(ABI);

package/events/Undelivered.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted when a host records an undelivered portal message.
+abstract contract UndeliveredEvent is EventEmitter {
+    string private constant ABI = "event Undelivered(uint indexed host, bytes32 key, bytes32 digest)";
+
+    /// @param host Host node ID that owns the undelivered message.
+    /// @param key Delivery lookup key.
+    /// @param digest Digest of the undelivered message.
+    event Undelivered(uint indexed host, bytes32 key, bytes32 digest);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",

package/ports/Dispatch.sol

@@ -3,15 +3,15 @@ pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
 import { Payable } from "../core/Payable.sol";
+import { RoutePayableHook } from "../core/Portal.sol";
 import { Cursors, Cur, Schemas } from "../Cursors.sol";
-import { DispatchPayableHook } from "../commands/Relay.sol";
 import { Budget } from "../utils/Value.sol";
 
 using Cursors for Cur;
 
 /// @title PortDispatchPayable
-/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined dispatch hook.
-abstract contract PortDispatchPayable is PortBase, Payable, DispatchPayableHook {
+/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined route hook.
+abstract contract PortDispatchPayable is PortBase, Payable, RoutePayableHook {
     uint internal immutable portDispatchPayableId = portId(this.portDispatchPayable.selector);
 
     constructor() {
@@ -19,8 +19,8 @@ abstract contract PortDispatchPayable is PortBase, Payable, DispatchPayableHook
         emit Labeled(portDispatchPayableId, bytes32(0), "portDispatchPayable");
     }
 
-    /// @notice Forward peer-supplied dispatches to the host-defined dispatch hook.
-    /// @dev Dispatch hooks receive the shared top-level source-chain value
+    /// @notice Forward peer-supplied dispatches to the host-defined route hook.
+    /// @dev Route hooks receive the shared top-level source value
     ///      budget. Any `msg.value` not spent by the hook remains on this host.
     /// @param data DISPATCH block stream supplied by the trusted peer.
     /// @return output Empty response bytes.
@@ -29,8 +29,8 @@ abstract contract PortDispatchPayable is PortBase, Payable, DispatchPayableHook
         Budget memory budget = openValue();
 
         while (input.i < input.len) {
-            (uint chain, uint resources, bytes calldata payload) = input.unpackDispatch();
-            dispatch(chain, resources, bytes(payload), budget);
+            (uint portal, uint resources, bytes calldata payload) = input.unpackDispatch();
+            route(portal, resources, bytes(payload), budget);
         }
 
         input.complete();

package/queries/Positions.sol

@@ -29,6 +29,7 @@ abstract contract GetPositionHook {
 abstract contract GetPosition is QueryBase, GetPositionHook {
     uint public immutable getPositionId = queryId(this.getPosition.selector);
 
+    /// @param output Response schema advertised for each position output block.
     constructor(string memory output) {
         emit Query(host, getPositionId, "1:1", Forms.AccountAsset, output);
         emit Labeled(getPositionId, bytes32(0), "getPosition");

package/core/Commitments.sol

@@ -1,19 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import {CommitmentEvent} from "../events/Commitment.sol";
-
-/// @title Commitments
-/// @notice On-chain registry for digest commitments.
-abstract contract Commitments is CommitmentEvent {
-    /// @dev key -> committed digest.
-    mapping(bytes32 key => bytes32 digest) internal commitments;
-
-    /// @notice Clear the commitment under `key` and return the removed digest.
-    /// @param key Commitment lookup key.
-    /// @return digest Removed digest.
-    function uncommit(bytes32 key) internal returns (bytes32 digest) {
-        digest = commitments[key];
-        delete commitments[key];
-    }
-}

package/events/Commitment.sol

@@ -1,19 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-import { EventEmitter } from "./Emitter.sol";
-
-/// @notice Emitted when a host-scoped commitment is updated.
-abstract contract CommitmentEvent is EventEmitter {
-    string private constant ABI = "event Commitment(uint indexed host, bytes32 key, bytes32 digest, uint status)";
-
-    /// @param host Host node ID that manages the commitment.
-    /// @param key Commitment lookup key.
-    /// @param digest Committed digest. Zero may be used when clearing without revealing the previous digest.
-    /// @param status Commitment status. Zero means cleared; nonzero means committed or application-defined.
-    event Commitment(uint indexed host, bytes32 key, bytes32 digest, uint status);
-
-    constructor() {
-        emit EventAbi(ABI);
-    }
-}