@rootzero/contracts 1.19.0 → 1.21.0

package/commands/Provision.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Execution, Executions, CommandBase, HostAmount, Lanes, Specs} from "./Base.sol";
+import {Execution, Executions, CommandBase, Flags, HostAmount, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @notice Shared provision hook used by `Provision`.
@@ -32,7 +32,7 @@ abstract contract Provision is CommandBase, ProvisionHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("provision", Specs.Empty, Specs.Allocation, Specs.Custody, 0, false, false);
+        (, descriptor) = command("provision", Specs.Empty, Specs.Allocation, Specs.Custody, 0, 0);
     }
 
     /// @notice Provision ALLOCATION input blocks and output matching CUSTODY state blocks.
@@ -64,7 +64,7 @@ abstract contract ProvisionPayable is CommandBase, ProvisionPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("provisionPayable", Specs.Empty, Specs.Allocation, Specs.Custody, 0, true, false);
+        (, descriptor) = command("provisionPayable", Specs.Empty, Specs.Allocation, Specs.Custody, 0, Flags.Funded);
     }
 
     /// @notice Provision ALLOCATION input blocks with access to a mutable native-value budget.

package/commands/Recover.sol

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {Execution, Executions, CommandBase, Flags, Lanes, Specs} from "./Base.sol";
 
 using Executions for Execution;
 
-/// @notice Hook implemented by hosts that recover previously undelivered payloads.
+/// @notice Hook implemented by hosts that recover previously unresolved payloads.
 abstract contract RecoverPayableHook {
     /// @notice Override to recover a witness through `handler`.
     /// @param handler Port that should attempt recovery.
@@ -31,7 +31,7 @@ abstract contract RecoverPayable is CommandBase, RecoverPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("recoverPayable", Specs.Empty, Specs.Recover, Specs.Empty, 0, true, false);
+        (, descriptor) = command("recoverPayable", Specs.Empty, Specs.Recover, Specs.Empty, 0, Flags.Funded);
     }
 
     /// @notice Recover each recover block in the command input.

package/commands/Relay.sol

@@ -1,20 +1,29 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Blocks, Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {Execution, Executions, CommandBase, Flags, Lanes, Specs} from "./Base.sol";
 
 using Executions for Execution;
 
-/// @notice Hook implemented by hosts that forward funded relay payloads.
+/// @notice Hook implemented by hosts that relay command contexts.
 abstract contract RelayPayableHook {
-    /// @notice Override to relay an encoded payload to `portal`.
+    /// @notice Override to relay a command context to `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 account Destination command account.
+    /// @param state State forwarded into the destination context.
+    /// @param input Input forwarded into the destination context.
     /// @param funds Execution used for source value available for transport fees
     /// and destination resource funding.
-    function relayTo(uint portal, uint resources, bytes memory payload, Execution memory funds) internal virtual;
+    function relay(
+        uint portal,
+        uint resources,
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input,
+        Execution memory funds
+    ) internal virtual;
 }
 
 /// @title RelayPayable
@@ -23,7 +32,7 @@ abstract contract RelayPayable is CommandBase, RelayPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("relayPayable", Specs.Empty, Specs.Relay, Specs.Empty, 0, true, false);
+        (, descriptor) = command("relayPayable", Specs.Empty, Specs.Relay, Specs.Empty, 0, Flags.Funded);
     }
 
     /// @notice Relay one RELAY input block with the command account and empty state.
@@ -33,10 +42,8 @@ abstract contract RelayPayable is CommandBase, RelayPayableHook {
         bytes calldata input
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(state, input, descriptor, 1);
-        (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
-        bytes memory context = Blocks.contextCopy(account, state, payload);
-
-        relayTo(portal, resources, context, exec);
+        (uint portal, uint resources, bytes calldata relayInput) = exec.unpackRelay(Lanes.Input);
+        relay(portal, resources, account, state, relayInput, exec);
 
         return close(exec, account);
     }
@@ -51,7 +58,7 @@ abstract contract RelayBalancePayable is CommandBase, RelayPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("relayBalancePayable", Specs.Balance, Specs.Relay, Specs.Empty, 0, true, false);
+        (, descriptor) = command("relayBalancePayable", Specs.Balance, Specs.Relay, Specs.Empty, 0, Flags.Funded);
     }
 
     /// @notice Relay one RELAY input block with the command account and current state.
@@ -65,10 +72,8 @@ abstract contract RelayBalancePayable is CommandBase, RelayPayableHook {
         bytes calldata input
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
         Execution memory exec = openCommand(state, input, descriptor, 1);
-        (uint portal, uint resources, bytes calldata payload) = exec.unpackRelay(Lanes.Input);
-        bytes memory context = Blocks.contextCopy(account, state, payload);
-
-        relayTo(portal, resources, context, exec);
+        (uint portal, uint resources, bytes calldata relayInput) = exec.unpackRelay(Lanes.Input);
+        relay(portal, resources, account, state, relayInput, exec);
 
         return close(exec, account);
     }

package/commands/Repay.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {Execution, Executions, CommandBase, Flags, Lanes, Specs} from "./Base.sol";
 import {RepayHook} from "../core/Settlement.sol";
 import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
@@ -25,7 +25,7 @@ abstract contract Repay is CommandBase, RepayHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("repay", Specs.Position, Specs.Empty, Specs.Balance, 0, false, false);
+        (id, descriptor) = command("repay", Specs.Position, Specs.Empty, Specs.Balance, 0, 0);
         action(id, Actions.Settle);
     }
 
@@ -57,7 +57,7 @@ abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("repayPayable", Specs.Position, Specs.Empty, Specs.Balance, 0, true, false);
+        (id, descriptor) = command("repayPayable", Specs.Position, Specs.Empty, Specs.Balance, 0, Flags.Funded);
         action(id, Actions.Settle);
     }
 

package/commands/Settle.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {Execution, Executions, CommandBase, Flags, Lanes, Specs} from "./Base.sol";
 import {SettleHook} from "../core/Settlement.sol";
 import {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
@@ -37,7 +37,7 @@ abstract contract Settle is CommandBase, SettleHook, Action {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("settle", Specs.Position, Specs.Empty, Specs.Empty, 0, false, false);
+        (id, descriptor) = command("settle", Specs.Position, Specs.Empty, Specs.Empty, 0, 0);
         action(id, Actions.Settle);
     }
 
@@ -73,7 +73,7 @@ abstract contract SettlePayable is CommandBase, SettlePayableHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("settlePayable", Specs.Position, Specs.Empty, Specs.Empty, 0, true, false);
+        (id, descriptor) = command("settlePayable", Specs.Position, Specs.Empty, Specs.Empty, 0, Flags.Funded);
         action(id, Actions.Settle);
     }
 
@@ -97,11 +97,11 @@ abstract contract SettlePayable is CommandBase, SettlePayableHook, Action {
     }
 }
 
-/// @title InternalSettle
+/// @title SettleInternal
 /// @notice Extends the advertised settle command with memory-state pipeline dispatch.
 /// @dev This adapter is not a separate command. It uses the command ID and settlement hook
 /// inherited from `Settle` while accepting the state location used by `Pipeline`.
-abstract contract InternalSettle is Settle {
+abstract contract SettleInternal is Settle {
     /// @notice Execute the inherited settle command from an internal pipeline.
     /// @param account Account for which each position is settled.
     /// @param state POSITION block stream held in pipeline memory.

package/commands/Withdraw.sol

@@ -25,7 +25,7 @@ abstract contract Withdraw is CommandBase, WithdrawHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("withdraw", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
+        (id, descriptor) = command("withdraw", Specs.Balance, Specs.Empty, Specs.Empty, 0, 0);
         action(id, Actions.Withdraw);
     }
 

package/commands/admin/AllowAssets.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import { AdminBase, Execution, Executions, Flags, Lanes, Specs } from "./Base.sol";
 using Executions for Execution;
 
 /// @notice Hook implemented by hosts that allow assets.
@@ -19,7 +19,7 @@ abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("allowAssets", Specs.Empty, Specs.Asset, Specs.Empty, 0, false, true);
+        (, descriptor) = command("allowAssets", Specs.Empty, Specs.Asset, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Allow each ASSET block in the admin input.

package/commands/admin/Allowance.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @notice Hook implemented by hosts that configure peer asset allowances.
@@ -23,7 +23,7 @@ abstract contract Allowance is AdminBase, AllowanceHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("allowance", Specs.Empty, Specs.Allowance, Specs.Empty, 0, false, true);
+        (, descriptor) = command("allowance", Specs.Empty, Specs.Allowance, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Apply each ALLOWANCE block in the admin input.

package/commands/admin/Annotate.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @title Annotate
@@ -12,7 +12,7 @@ abstract contract Annotate is AdminBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("annotate", Specs.Empty, Specs.Annotation, Specs.Empty, 0, false, true);
+        (, descriptor) = command("annotate", Specs.Empty, Specs.Annotation, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Publish each ANNOTATION block in the admin input.

package/commands/admin/Appoint.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import { AdminBase, Execution, Executions, Flags, Lanes, Specs } from "./Base.sol";
 import { GuardianAccess } from "../../core/Access.sol";
 using Executions for Execution;
 
@@ -13,7 +13,7 @@ abstract contract Appoint is GuardianAccess, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("appoint", Specs.Empty, Specs.Account, Specs.Empty, 0, false, true);
+        (, descriptor) = command("appoint", Specs.Empty, Specs.Account, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Appoint each user ACCOUNT block in the admin input as a guardian.

package/commands/admin/Authorize.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @title Authorize
@@ -13,7 +13,7 @@ abstract contract Authorize is AdminBase {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("authorize", Specs.Empty, Specs.Node, Specs.Empty, 0, false, true);
+        (id, descriptor) = command("authorize", Specs.Empty, Specs.Node, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Return the registered AUTHORIZE command ID.

package/commands/admin/Base.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandBase, Execution, Executions, Lanes, Specs} from "../Base.sol";
+import {CommandBase, Execution, Executions, Flags, Lanes, Specs} from "../Base.sol";
 import {NodeAccess} from "../../core/Access.sol";
 
 /// @title AdminBase

package/commands/admin/DenyAssets.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @notice Hook implemented by hosts that deny assets.
@@ -19,7 +19,7 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("denyAssets", Specs.Empty, Specs.Asset, Specs.Empty, 0, false, true);
+        (, descriptor) = command("denyAssets", Specs.Empty, Specs.Asset, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Deny each ASSET block in the admin input.
@@ -41,9 +41,3 @@ abstract contract DenyAssets is AdminBase, DenyAssetsHook {
         return close(exec, account);
     }
 }
-
-
-
-
-
-

package/commands/admin/Dismiss.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { AdminBase, Execution, Executions, Lanes, Specs } from "./Base.sol";
+import { AdminBase, Execution, Executions, Flags, Lanes, Specs } from "./Base.sol";
 import { GuardianAccess } from "../../core/Access.sol";
 using Executions for Execution;
 
@@ -13,7 +13,7 @@ abstract contract Dismiss is GuardianAccess, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("dismiss", Specs.Empty, Specs.Account, Specs.Empty, 0, false, true);
+        (, descriptor) = command("dismiss", Specs.Empty, Specs.Account, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Dismiss each user ACCOUNT block in the admin input from guardian status.

package/commands/admin/Execute.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 import {RawNodeCalls} from "../../core/Calls.sol";
 
 using Executions for Execution;
@@ -15,7 +15,7 @@ abstract contract ExecutePayable is RawNodeCalls, AdminBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("executePayable", Specs.Empty, Specs.Call, Specs.Empty, 0, true, true);
+        (, descriptor) = command("executePayable", Specs.Empty, Specs.Call, Specs.Empty, 0, Flags.AdminFunded);
     }
 
     /// @notice Execute each CALL block in the admin input.

package/commands/admin/Unauthorize.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AdminBase, Execution, Executions, Lanes, Specs} from "./Base.sol";
+import {AdminBase, Execution, Executions, Flags, Lanes, Specs} from "./Base.sol";
 using Executions for Execution;
 
 /// @title Unauthorize
@@ -13,7 +13,7 @@ abstract contract Unauthorize is AdminBase {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("unauthorize", Specs.Empty, Specs.Node, Specs.Empty, 0, false, true);
+        (id, descriptor) = command("unauthorize", Specs.Empty, Specs.Node, Specs.Empty, 0, Flags.Admin);
     }
 
     /// @notice Return the registered UNAUTHORIZE command ID.

package/core/Portal.sol

@@ -2,13 +2,16 @@
 pragma solidity ^0.8.33;
 
 import {PortCalls} from "./Calls.sol";
+import {NodeAccess} from "./Access.sol";
+import {ResolvedEvent} from "../events/Resolved.sol";
+import {UnresolvedEvent} from "../events/Unresolved.sol";
 
 /// @title Portal
 /// @notice Base contract for hosts that route payloads through portal adapters.
-abstract contract Portal is PortCalls {
+abstract contract Portal is PortCalls, NodeAccess, UnresolvedEvent, ResolvedEvent {
     error BadWitness();
 
-    mapping(bytes32 key => bytes32 digest) internal undelivered;
+    mapping(bytes32 key => bytes32 digest) internal unresolved;
 
     /// @notice Try to forward `message` to `port`.
     /// @dev Records and returns `keccak256(message)` under `key` only when forwarding fails.
@@ -21,19 +24,19 @@ abstract contract Portal is PortCalls {
         if (tryCallPort(port, value, message)) return bytes32(0);
 
         miss = keccak256(message);
-        undelivered[key] = miss;
+        unresolved[key] = miss;
     }
 
-    /// @notice Retry a previously undelivered witness through `port`.
+    /// @notice Resolve a previously unresolved witness through `port`.
     /// @dev The witness must hash to the digest stored under `key`.
     /// @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 retry(uint port, bytes32 key, bytes calldata witness, uint128 value) internal virtual {
-        if (undelivered[key] != keccak256(witness)) revert BadWitness();
+    /// @param value Native EVM value assigned to the resolution attempt.
+    function resolve(uint port, bytes32 key, bytes calldata witness, uint128 value) internal virtual {
+        if (unresolved[key] != keccak256(witness)) revert BadWitness();
 
-        delete undelivered[key];
+        delete unresolved[key];
         callPort(port, value, witness);
     }
 }

package/docs/Schema.md

@@ -50,8 +50,16 @@ overloaded in the relevant host/schema context.
 
 ## Block Syntax
 
-A block definition has an event alias and a schema body. Fixed fields are
-written in braces:
+A block definition has an event alias and a schema body. A schema body is one
+of three forms:
+
+```txt
+""                 empty or raw payload
+{ fields }         structured payload
+many #item         top-level custom list payload
+```
+
+Fixed fields are written in braces:
 
 ```txt
 alias:  amount
@@ -66,9 +74,11 @@ A block body can reference another block alias as a child item with `#`:
 
 The empty schema string `""` means the block has no structured payload. This is
 used for zero-payload blocks such as `#unit` and raw dynamic blocks such as
-`#bytes`.
+`#bytes`. A root `many #item` body is reserved for an emitted custom schema
+whose own key identifies the outer list block.
 
-A schema body is a comma-separated list of items. Order is significant.
+A structured schema body is a comma-separated list of items. Order is
+significant.
 
 ```txt
 { #amount, maybe #account as recipient }
@@ -110,11 +120,30 @@ maybe many #balance
 
 - no prefix: one required item
 - `maybe`: optional item
-- `many`: one generic `#list` block whose payload contains repeated items
+- `many`: a list whose payload contains repeated items
 - `maybe many`: optional `#list` block
 
-`maybe` emits no placeholder when absent. `many` wraps repeated items in one
-generic list block; it does not repeat the item in place.
+`maybe` emits no placeholder when absent. Inside a structured schema body,
+`many` wraps repeated items in one generic `#list` block; it does not repeat the
+item in place:
+
+```txt
+{ uint id, many #asset as assets }
+```
+
+When an emitted custom schema consists entirely of a top-level `many` item, the
+custom schema key identifies the outer list block instead. Its payload contains
+the repeated items directly:
+
+```txt
+schema key: 0x00000001
+schema body: many #asset
+wire value: [0x00000001][length][ASSET][ASSET]...
+```
+
+This convention gives a top-level list a discoverable, context-local type while
+retaining the generic `#list` key for lists whose type is supplied by an
+enclosing schema.
 
 ## Endpoint Lanes
 
@@ -128,33 +157,28 @@ The packed descriptor uses these lane layouts:
 
 ```txt
 state   [key:4][group:1]
-input   [key:4][item:4][group:1]
-output  [key:4][min:4][max:4][hint:4][group:1]
+input   [key:4][group:1]
+output  [key:4][min:4][max:4][hint:3][group:1]
+reserve [reserved:4]
+tx      [transactions:1]
+flags   [flags:1]
 ```
 
-Containers are exclusive to input. A plain input spec is compressed into
-`[spec.key][0]`. A spec with a nonzero container is compressed into
-`[spec.container][spec.key]`: the container is the top-level wire key and the
-item is its contained block key. The built-in `many(spec)` helper annotates the
-spec with `Specs.List` as its container, matching the DSL form `many #item`.
-Output lanes retain their size bounds and allocation hint so execution can
-reconstruct the output spec and initialize its writer directly. The Solidity
-output decoder returns this as a left-aligned, writer-ready spec that retains
-its encoded group. Its container and reserved fields are cleared. `Specs.group`
-returns the effective group, interpreting an encoded zero as one for a
-non-empty spec.
+Each lane directly identifies its top-level block key. Output lanes retain their
+size bounds and allocation hint so execution can reconstruct the output spec and
+initialize its writer directly. Four descriptor-level bytes are reserved after
+the lane metadata. The Solidity output decoder returns a left-aligned,
+writer-ready spec that retains its encoded group and clears its reserved fields.
+`Specs.group` returns the effective group, interpreting an encoded zero as one
+for a non-empty spec.
 
 Any non-empty lane resolves its key to a block alias and schema body through the
-active schema context. If the item slot is nonzero, tooling also resolves that
-item key in the same context. A bare list lane, `[Keys.List][0]`, is incomplete
-discovery metadata because it does not say what the list contains; indexers
-should reject it for self-describing endpoints.
+active schema context. A top-level list lane uses the key of its emitted custom
+`many` schema; the descriptor treats it like every other direct lane spec.
 
 The lane key is the prime item. Prime items may repeat at the top level for
-batching. When the lane is `many #item`, the repeated prime item is the generic
-LIST block and each LIST payload contains repeated `item` blocks. Later
-top-level items are globals for the whole batch and are not counted as
-per-operation prime blocks.
+batching. Later top-level items are globals for the whole batch and are not
+counted as per-operation prime blocks.
 
 The prime item cannot be optional. If an endpoint needs a per-operation marker
 with no payload, use a zero-payload block such as `#unit`.
@@ -369,7 +393,7 @@ invalid in any path segment.
 
 - `#bytes`: raw dynamic bytes, written without a body
 - `#string`: UTF-8 string bytes, written without a body
-- `#list`: generic list wrapper emitted by `many`
+- `#list`: generic list wrapper emitted by nested `many`
 
 Custom input shapes should define their own context-local block spec and publish
 it with a `#schema` annotation. Endpoint contracts can use `schema(...)` to

package/events/Relay.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted when an account records an outbound relay reference.
+abstract contract RelayEvent is EventEmitter {
+    string private constant ABI = "event Relay(bytes32 indexed account, uint portal, uint resources, bytes32 key, bytes32 digest)";
+
+    /// @param account Account that owns the relayed context.
+    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param resources Chain-specific resources assigned to the relay.
+    /// @param key Relay correlation or recovery lookup key.
+    /// @param digest Digest of the relayed payload or canonical envelope.
+    event Relay(bytes32 indexed account, 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/Unresolved.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 a portal message awaiting resolution.
+abstract contract UnresolvedEvent is EventEmitter {
+    string private constant ABI = "event Unresolved(uint indexed host, bytes32 key, bytes32 digest)";
+
+    /// @param host Host node ID that owns the unresolved message.
+    /// @param key Resolution lookup key.
+    /// @param digest Digest of the unresolved message.
+    event Unresolved(uint indexed host, bytes32 key, bytes32 digest);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/execution/Execution.sol

@@ -227,7 +227,16 @@ library Executions {
     /// @param lane Decoder lane containing the LIST block.
     /// @return items Cursor over the nested list items.
     function list(Execution memory exec, uint8 lane) internal pure returns (Cur memory items) {
-        (uint abs, uint end) = consume(exec, lane, Specs.List);
+        return list(exec, Specs.List, lane);
+    }
+
+    /// @notice Consume a list block described by `spec` and return a cursor scoped to its payload.
+    /// @param exec Execution whose decoder is advanced.
+    /// @param spec Custom list block specification.
+    /// @param lane Decoder lane containing the list block.
+    /// @return items Cursor over the nested list items.
+    function list(Execution memory exec, uint spec, uint8 lane) internal pure returns (Cur memory items) {
+        (uint abs, uint end) = consume(exec, lane, spec);
         items.state = Cursors.create(abs, end - abs, 0, 0, 0);
     }