@rootzero/contracts 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## Unreleased
+
+## 1.10.0
+
+### Breaking Changes
+
+- Moved `RecoverHook` from `Portal.sol` to `commands/Recover.sol`.
+- Moved `RoutePayableHook` from `Portal.sol` to `commands/Relay.sol`.
+- Renamed Portal helpers to `forward` / `retry`; hosts now explicitly bridge
+  the `RecoverPayable` hook to Portal retry behavior.
+- Renamed the generic `Resolved` event to `Recovered`.
+- Portal no longer emits `Recovered` when retrying an undelivered witness.
+- Renamed `Cursors.exit` to `ensureAt` and renamed its position argument to
+  `pos`.
+- Removed the redundant `next` return value from both `Cursors.init` overloads;
+  callers should use the returned cursor's `len` as the run boundary.
+- Changed `Cursors.list` to require the expected current cursor position as
+  `pos` before entering the LIST block.
+
 ## 1.9.0
 
 ### Breaking Changes
@@ -18,10 +37,10 @@ breaking API changes. Breaking changes are called out explicitly.
   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
+- Added `Recovered(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`.
+  of domain-specific events such as `Undelivered` and `Recovered`.
 
 ## 1.8.0
 

package/Core.sol

@@ -12,7 +12,8 @@ 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 { Portal } from "./core/Portal.sol";
+import { RecoverHook } from "./commands/Recover.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 

package/Endpoints.sol

@@ -16,9 +16,8 @@ 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 { RecoverPayable } from "./commands/Recover.sol";
-import { RelayPayable } from "./commands/Relay.sol";
-import { RecoverHook, RoutePayableHook } from "./core/Portal.sol";
+import { RecoverHook, RecoverPayable } from "./commands/Recover.sol";
+import { RelayPayable, RoutePayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands

package/Events.sol

@@ -13,7 +13,7 @@ import { CommandEvent } from "./events/Command.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 { RecoveredEvent } from "./events/Recovered.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardEvent } from "./events/Guard.sol";
 import { GuardianEvent } from "./events/Guardian.sol";

package/README.md

@@ -220,7 +220,7 @@ the batch, call the hook, write the output run:
 
 ```solidity
 function deposit(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-    (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+    (Cur memory request, uint groups) = Cursors.init(c.request, 1);
     Writer memory writer = Writers.allocBalances(groups);
 
     while (request.i < request.len) {

package/blocks/Cursors.sol

@@ -76,16 +76,14 @@ library Cursors {
     /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
     /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
     /// @return groups Number of block groups in the run (`block count / group`).
-    /// @return next Byte offset immediately after the run, relative to `source`.
     function init(
         bytes calldata source,
         uint group
-    ) internal pure returns (Cur memory cur, uint groups, uint next) {
+    ) internal pure returns (Cur memory cur, uint groups) {
         cur = open(source);
         if (cur.i == cur.len) revert ZeroCursor();
         (bytes4 key, ) = cur.peek(cur.i);
         groups = cur.run(key, group);
-        next = cur.len;
     }
 
     /// @notice Create a cursor over `source`, restrict it to its first grouped run, and require an exact group count.
@@ -93,14 +91,13 @@ library Cursors {
     /// @param group Expected block group size (e.g. 1 for single, 2 for paired).
     /// @param expectedGroups Required number of groups in the run.
     /// @return cur Cursor with `len` truncated to the end of the first run in `source`.
-    /// @return next Byte offset immediately after the run, relative to `source`.
     function init(
         bytes calldata source,
         uint group,
         uint expectedGroups
-    ) internal pure returns (Cur memory cur, uint next) {
+    ) internal pure returns (Cur memory cur) {
         uint groups;
-        (cur, groups, next) = init(source, group);
+        (cur, groups) = init(source, group);
         if (groups != expectedGroups) revert BadRatio();
     }
 
@@ -333,13 +330,16 @@ library Cursors {
         return find(cur, cur.i, key);
     }
 
-    /// @notice Enter a List block at the current position and return the next offset.
+    /// @notice Enter a LIST block at the expected current position and return its next offset.
+    /// Reverts with `IncompleteCursor` if `cur.i` is not exactly `pos`.
     /// Advances `cur.i` past the list header so the list members can be parsed
     /// directly from the same cursor. The returned `next` is the byte offset
     /// immediately after the list payload, relative to the current cursor region.
-    /// @param cur Cursor positioned at a list block; advanced past the 8-byte header.
+    /// @param cur Cursor expected to be positioned at a list block; advanced past the 8-byte header.
+    /// @param pos Expected current cursor position, relative to the cursor region.
     /// @return next Byte offset immediately after the list payload.
-    function list(Cur memory cur) internal pure returns (uint next) {
+    function list(Cur memory cur, uint pos) internal pure returns (uint next) {
+        cur.ensureAt(pos);
         next = enter(cur, Keys.List, 0, 0);
     }
 
@@ -387,13 +387,13 @@ library Cursors {
         return maybeTake(cur, Keys.Data);
     }
 
-    /// @notice Exit a nested region at an exact boundary.
-    /// Reverts with `IncompleteCursor` if `end` exceeds the cursor region length
-    /// or `cur.i != end`.
+    /// @notice Ensure the cursor is at an exact position.
+    /// Reverts with `IncompleteCursor` if `pos` exceeds the cursor region length
+    /// or `cur.i != pos`.
     /// @param cur Cursor to check.
-    /// @param end Relative end offset of the nested region.
-    function exit(Cur memory cur, uint end) internal pure {
-        if (end > cur.len || cur.i != end) revert IncompleteCursor();
+    /// @param pos Relative byte offset the cursor must be positioned at.
+    function ensureAt(Cur memory cur, uint pos) internal pure {
+        if (pos > cur.len || cur.i != pos) revert IncompleteCursor();
     }
 
     /// @notice Assert that the cursor has consumed its entire source region.
@@ -747,7 +747,7 @@ library Cursors {
         id = cur.readUint();
         namespace = cur.read32();
         name = cur.unpackString();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a dynamic block with a single bytes32 payload.
@@ -1107,7 +1107,7 @@ library Cursors {
         target = uint(cur.read32());
         resources = uint(cur.read32());
         req = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a CALL block and return its target invocation fields.
@@ -1121,7 +1121,7 @@ library Cursors {
         target = uint(cur.read32());
         resources = uint(cur.read32());
         data = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a CONTEXT block and return its command context fields.
@@ -1137,7 +1137,7 @@ library Cursors {
         account = cur.read32();
         state = cur.unpackBytes();
         request = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a RELAY block and return its destination portal, resources, and request stream.
@@ -1152,7 +1152,7 @@ library Cursors {
         portal = cur.readUint();
         resources = cur.readUint();
         request = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a DISPATCH block and return its destination portal, resources, and payload.
@@ -1167,7 +1167,7 @@ library Cursors {
         portal = cur.readUint();
         resources = cur.readUint();
         payload = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     /// @notice Consume a RECOVER block and return its handler, resources, key, and witness bytes.
@@ -1184,7 +1184,7 @@ library Cursors {
         resources = cur.readUint();
         key = cur.read32();
         witness = cur.unpackBytes();
-        cur.exit(end);
+        cur.ensureAt(end);
     }
 
     // Type-specific validators

package/commands/Burn.sol

@@ -30,7 +30,7 @@ abstract contract Burn is CommandBase, BurnHook {
     /// @param c Command context; `c.state` must contain BALANCE blocks.
     /// @return Empty output state.
     function burn(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory state, , ) = Cursors.init(c.state, 1);
+        (Cur memory state, ) = Cursors.init(c.state, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();

package/commands/Credit.sol

@@ -32,7 +32,7 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     function creditAccount(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory state, , ) = Cursors.init(c.state, 1);
+        (Cur memory state, ) = Cursors.init(c.state, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();

package/commands/Debit.sol

@@ -32,7 +32,7 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     /// The default implementation iterates AMOUNT blocks, calls
     /// `debitAccount`, and emits matching BALANCE blocks.
     function debitAccount(bytes32 account, bytes calldata request) internal virtual returns (bytes memory) {
-        (Cur memory input, uint groups, ) = Cursors.init(request, 1);
+        (Cur memory input, uint groups) = Cursors.init(request, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
         while (input.i < input.len) {

package/commands/Deposit.sol

@@ -48,7 +48,7 @@ abstract contract Deposit is CommandBase, DepositHook {
     function deposit(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+        (Cur memory request, uint groups) = Cursors.init(c.request, 1);
         Writer memory writer = Writers.allocBalances(groups);
 
         while (request.i < request.len) {
@@ -79,7 +79,7 @@ abstract contract DepositPayable is CommandBase, Payable, DepositPayableHook {
     function depositPayable(
         CommandContext calldata c
     ) external payable onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+        (Cur memory request, uint groups) = Cursors.init(c.request, 1);
         Writer memory writer = Writers.allocBalances(groups);
         Budget memory budget = openValue();
 

package/commands/Payout.sol

@@ -31,8 +31,8 @@ abstract contract Payout is CommandBase, PayoutHook {
     /// @param c Command context; `c.state` must contain BALANCE blocks and `c.request` matching ACCOUNT blocks.
     /// @return Empty output state.
     function payout(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory state, uint groups, ) = Cursors.init(c.state, 1);
-        (Cur memory request, ) = Cursors.init(c.request, 1, groups);
+        (Cur memory state, uint groups) = Cursors.init(c.state, 1);
+        Cur memory request = Cursors.init(c.request, 1, groups);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();

package/commands/Provision.sol

@@ -44,7 +44,7 @@ abstract contract Provision is CommandBase, ProvisionHook {
     /// @param c Command context; `c.request` must contain ALLOCATION blocks.
     /// @return CUSTODY block stream matching the provisioned allocations.
     function provision(CommandContext calldata c) external onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+        (Cur memory request, uint groups) = Cursors.init(c.request, 1);
         Writer memory writer = Writers.allocCustodies(groups);
 
         while (request.i < request.len) {
@@ -76,7 +76,7 @@ abstract contract ProvisionPayable is CommandBase, Payable, ProvisionPayableHook
     function provisionPayable(
         CommandContext calldata c
     ) external payable onlyCommand returns (bytes memory) {
-        (Cur memory request, uint groups, ) = Cursors.init(c.request, 1);
+        (Cur memory request, uint groups) = Cursors.init(c.request, 1);
         Writer memory writer = Writers.allocCustodies(groups);
         Budget memory budget = openValue();
 

package/commands/Recover.sol

@@ -3,12 +3,20 @@ 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 RecoverHook {
+    /// @notice Override to recover a 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 RecoverPayable
 /// @notice Command that forwards recover request blocks to a virtual hook.
 /// Recovery is witness-driven: the command account pays and receives leftover
@@ -26,7 +34,7 @@ abstract contract RecoverPayable is CommandBase, Payable, RecoverHook {
     /// @param c Command context; `c.request` must contain Recover blocks.
     /// @return Empty output state.
     function recoverPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
         Budget memory budget = openValue();
 
         while (request.i < request.len) {

package/commands/Relay.sol

@@ -3,12 +3,22 @@ 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 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;
+}
+
 /// @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
@@ -26,7 +36,7 @@ abstract contract RelayPayable is CommandBase, Payable, RoutePayableHook {
     /// @param c Command context; `c.request` must contain exactly one RELAY block.
     /// @return output Empty output state.
     function relayPayable(CommandContext calldata c) external payable onlyCommand returns (bytes memory output) {
-        (Cur memory request, ) = Cursors.init(c.request, 1, 1);
+        Cur memory request = Cursors.init(c.request, 1, 1);
         Budget memory budget = openValue();
 
         (uint portal, uint resources, bytes memory context) = request.relayToContext(c.account, c.state);

package/commands/Withdraw.sol

@@ -32,7 +32,7 @@ abstract contract Withdraw is CommandBase, WithdrawHook {
     function withdraw(
         CommandContext calldata c
     ) external onlyCommand returns (bytes memory) {
-        (Cur memory state, , ) = Cursors.init(c.state, 1);
+        (Cur memory state, ) = Cursors.init(c.state, 1);
 
         while (state.i < state.len) {
             (bytes32 asset, uint amount) = state.unpackBalance();

package/commands/admin/AllowAssets.sol

@@ -29,7 +29,7 @@ abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     function allowAssets(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             bytes32 asset = request.unpackAsset();

package/commands/admin/Allowance.sol

@@ -31,7 +31,7 @@ abstract contract Allowance is AdminBase, AllowanceHook {
     /// @param c Admin command context; `c.request` must contain ALLOWANCE blocks.
     /// @return Empty output state.
     function allowance(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             (uint peer, bytes32 asset, uint amount) = request.unpackAllowance();

package/commands/admin/Appoint.sol

@@ -23,7 +23,7 @@ abstract contract Appoint is AdminBase {
     function appoint(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             bytes32 account = request.unpackAccount();

package/commands/admin/Authorize.sol

@@ -23,7 +23,7 @@ abstract contract Authorize is AdminBase {
     function authorize(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             uint node = request.unpackNode();

package/commands/admin/DenyAssets.sol

@@ -29,7 +29,7 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     function denyAssets(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             bytes32 asset = request.unpackAsset();

package/commands/admin/Dismiss.sol

@@ -23,7 +23,7 @@ abstract contract Dismiss is AdminBase {
     function dismiss(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             bytes32 account = request.unpackAccount();

package/commands/admin/Execute.sol

@@ -25,7 +25,7 @@ abstract contract ExecutePayable is AdminBase, Payable {
     /// @param c Admin command context; `c.request` must contain CALL blocks.
     /// @return Empty output state.
     function executePayable(CommandContext calldata c) external payable onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
         Budget memory budget = openValue();
 
         while (request.i < request.len) {

package/commands/admin/Label.sol

@@ -21,7 +21,7 @@ abstract contract Label is AdminBase {
     /// @param c Admin command context; `c.request` must contain LABEL blocks.
     /// @return Empty output state.
     function label(CommandContext calldata c) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             (uint id, bytes32 namespace, string memory name) = request.unpackLabel();

package/commands/admin/Unauthorize.sol

@@ -23,7 +23,7 @@ abstract contract Unauthorize is AdminBase {
     function unauthorize(
         CommandContext calldata c
     ) external onlyAdmin(c.account) returns (bytes memory) {
-        (Cur memory request, , ) = Cursors.init(c.request, 1);
+        (Cur memory request, ) = Cursors.init(c.request, 1);
 
         while (request.i < request.len) {
             uint node = request.unpackNode();

package/core/Payable.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {Budget, Values} from "../utils/Value.sol";
+import {max128} from "../utils/Utils.sol";
 
 /// @title Payable
 /// @notice Abstract mixin for entrypoints that accept native value (`msg.value`).
@@ -16,6 +17,12 @@ abstract contract Payable {
         return Budget({remaining: msg.value});
     }
 
+    /// @notice Return the current call's native value as a checked uint128.
+    /// @return value Current `msg.value` in wei.
+    function msgValue() internal view returns (uint128 value) {
+        return uint128(max128(msg.value));
+    }
+
     /// @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.

package/core/Pipeline.sol

@@ -43,7 +43,7 @@ abstract contract Pipeline is Payable {
         bytes calldata steps,
         Budget memory budget
     ) internal {
-        (Cur memory input, , ) = Cursors.init(steps, 1);
+        (Cur memory input, ) = Cursors.init(steps, 1);
 
         while (input.i < input.len) {
             (uint target, uint resources, bytes calldata request) = input.unpackStep();

package/core/Portal.sol

@@ -2,67 +2,38 @@
 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 {
+abstract contract Portal is PortCalls {
     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 forward `message` to `port`.
+    /// @dev Records and returns `keccak256(message)` under `key` only when forwarding fails.
+    /// @param port Port that should handle the forwarded message.
+    /// @param key Forwarding/recovery lookup key.
+    /// @param message Encoded port input to forward.
+    /// @param value Native EVM value assigned to the forwarding attempt.
+    /// @return miss Message digest recorded for recovery when forwarding fails; zero on success.
+    function forward(uint port, bytes32 key, bytes calldata message, uint128 value) internal returns (bytes32 miss) {
+        if (tryCallPort(port, value, message)) return bytes32(0);
+
+        miss = keccak256(message);
+        undelivered[key] = miss;
     }
 
-    /// @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`.
+    /// @notice Retry a previously undelivered witness through `port`.
     /// @dev The witness must hash to the digest stored under `key`.
-    /// @param handler Port that should attempt recovery.
+    /// @param port 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();
+    function retry(uint port, bytes32 key, bytes calldata witness, uint128 value) internal virtual {
+        if (undelivered[key] != keccak256(witness)) revert BadWitness();
+
         delete undelivered[key];
-        callPort(handler, value, witness);
-        emit Resolved(host, key);
+        callPort(port, value, witness);
     }
 }

package/events/Recovered.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 recovers a previously recorded key.
+abstract contract RecoveredEvent is EventEmitter {
+    string private constant ABI = "event Recovered(uint indexed host, bytes32 key)";
+
+    /// @param host Host node ID that owns the recovered key.
+    /// @param key Recovery lookup key.
+    event Recovered(uint indexed host, bytes32 key);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/guards/Revoke.sol

@@ -18,7 +18,7 @@ abstract contract Revoke is GuardBase {
     }
 
     function revoke(bytes calldata request) external onlyGuardian {
-        (Cur memory input, , ) = Cursors.init(request, 1);
+        (Cur memory input, ) = Cursors.init(request, 1);
 
         while (input.i < input.len) {
             uint node = input.unpackNode();

package/package.json

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

package/ports/AllowAssets.sol

@@ -22,7 +22,7 @@ abstract contract PortAllowAssets is PortBase, AllowAssetsHook {
     /// @param data ASSET block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portAllowAssets(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory assets, , ) = Cursors.init(data, 1);
+        (Cur memory assets, ) = Cursors.init(data, 1);
 
         while (assets.i < assets.len) {
             bytes32 asset = assets.unpackAsset();

package/ports/Allowance.sol

@@ -23,7 +23,7 @@ abstract contract PortAllowance is PortBase, AllowanceHook {
     /// @param data AMOUNT block stream requested by the trusted peer.
     /// @return Empty response bytes.
     function portAllowance(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory amounts, , ) = Cursors.init(data, 1);
+        (Cur memory amounts, ) = Cursors.init(data, 1);
         uint peer = caller();
 
         while (amounts.i < amounts.len) {

package/ports/Credit.sol

@@ -22,7 +22,7 @@ abstract contract PortCreditAccount is PortBase, CreditAccountHook {
     /// @param data ACCOUNT_AMOUNT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portCreditAccount(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory amounts, , ) = Cursors.init(data, 1);
+        (Cur memory amounts, ) = Cursors.init(data, 1);
 
         while (amounts.i < amounts.len) {
             (bytes32 account, bytes32 asset, uint amount) = amounts.unpackAccountAmount();

package/ports/Debit.sol

@@ -22,7 +22,7 @@ abstract contract PortDebitAccount is PortBase, DebitAccountHook {
     /// @param data ACCOUNT_AMOUNT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portDebitAccount(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory amounts, , ) = Cursors.init(data, 1);
+        (Cur memory amounts, ) = Cursors.init(data, 1);
 
         while (amounts.i < amounts.len) {
             (bytes32 account, bytes32 asset, uint amount) = amounts.unpackAccountAmount();

package/ports/DenyAssets.sol

@@ -22,7 +22,7 @@ abstract contract PortDenyAssets is PortBase, DenyAssetsHook {
     /// @param data ASSET block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portDenyAssets(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory assets, , ) = Cursors.init(data, 1);
+        (Cur memory assets, ) = Cursors.init(data, 1);
 
         while (assets.i < assets.len) {
             bytes32 asset = assets.unpackAsset();

package/ports/Dispatch.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.33;
 
 import { PortBase } from "./Base.sol";
 import { Payable } from "../core/Payable.sol";
-import { RoutePayableHook } from "../core/Portal.sol";
+import { RoutePayableHook } from "../commands/Relay.sol";
 import { Cursors, Cur, Schemas } from "../Cursors.sol";
 import { Budget } from "../utils/Value.sol";
 
@@ -25,7 +25,7 @@ abstract contract PortDispatchPayable is PortBase, Payable, RoutePayableHook {
     /// @param data DISPATCH block stream supplied by the trusted peer.
     /// @return output Empty response bytes.
     function portDispatchPayable(bytes calldata data) external payable onlyPeer returns (bytes memory output) {
-        (Cur memory input, , ) = Cursors.init(data, 1);
+        (Cur memory input, ) = Cursors.init(data, 1);
         Budget memory budget = openValue();
 
         while (input.i < input.len) {

package/ports/Pipe.sol

@@ -25,7 +25,7 @@ abstract contract PortPipePayable is PortBase, Pipeline {
     /// @param data CONTEXT block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portPipePayable(bytes calldata data) external payable onlyPeer returns (bytes memory) {
-        (Cur memory input, , ) = Cursors.init(data, 1);
+        (Cur memory input, ) = Cursors.init(data, 1);
         Budget memory budget = openValue();
 
         while (input.i < input.len) {

package/ports/Redeem.sol

@@ -30,7 +30,7 @@ abstract contract PortRedeemBalance is PortBase, RedeemBalanceHook {
     /// @param data BALANCE block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portRedeemBalance(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory input, , ) = Cursors.init(data, 1);
+        (Cur memory input, ) = Cursors.init(data, 1);
         uint peer = caller();
 
         while (input.i < input.len) {

package/ports/Settle.sol

@@ -23,7 +23,7 @@ abstract contract PortSettle is PortBase, DebitAccountHook, CreditAccountHook {
     /// @param data TRANSACTION block stream supplied by the trusted peer.
     /// @return Empty response bytes.
     function portSettle(bytes calldata data) external onlyPeer returns (bytes memory) {
-        (Cur memory state, , ) = Cursors.init(data, 1);
+        (Cur memory state, ) = Cursors.init(data, 1);
 
         while (state.i < state.len) {
             (bytes32 from, bytes32 to, bytes32 asset, uint amount) = state.unpackTransaction();

package/queries/Assets.sol

@@ -32,7 +32,7 @@ abstract contract AssetStatus is QueryBase, AssetStatusHook {
     /// @param request Block-stream request consisting of `#asset { bytes32 asset }` blocks.
     /// @return Block-stream response containing one `#status { uint code }` per asset block.
     function assetStatus(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory query, uint groups, ) = Cursors.init(request, 1);
+        (Cur memory query, uint groups) = Cursors.init(request, 1);
         Writer memory response = Writers.allocStatuses(groups);
 
         while (query.i < query.len) {

package/queries/Balances.sol

@@ -32,7 +32,7 @@ abstract contract GetBalances is QueryBase, GetBalancesHook {
     /// @param request Block-stream request consisting of `accountAsset(account, asset)*`.
     /// @return Block-stream response containing one `accountAmount(account, asset, amount)` block per request block.
     function getBalances(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory query, uint groups, ) = Cursors.init(request, 1);
+        (Cur memory query, uint groups) = Cursors.init(request, 1);
         Writer memory response = Writers.allocAccountAmounts(groups);
 
         while (query.i < query.len) {

package/queries/Positions.sol

@@ -40,7 +40,7 @@ abstract contract GetPosition is QueryBase, GetPositionHook {
     /// @param request Block-stream request consisting of `accountAsset(account, asset)*`.
     /// @return Block-stream response containing one output-schema block per position block.
     function getPosition(bytes calldata request) external view returns (bytes memory) {
-        (Cur memory query, uint groups, ) = Cursors.init(request, 1);
+        (Cur memory query, uint groups) = Cursors.init(request, 1);
         Writer memory response = Writers.allocAny(groups);
 
         while (query.i < query.len) {

package/events/Resolved.sol

@@ -1,17 +0,0 @@
-// 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);
-    }
-}