@rootzero/contracts 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.21.0
+
+### Breaking Changes
+
+- Repacked endpoint descriptors as `[state key:4][stride:1]`,
+  `[input key:4][stride:1]`,
+  `[output key:4][min:4][max:4][hint:3][stride:1]`, four reserved bytes,
+  one transaction-count byte, and one flags byte. The input child-key field was
+  removed; indexers and request builders must decode the new layout.
+- Removed container metadata and the `many` and `keys` helpers from `Specs`.
+  Top-level lists are now emitted custom schemas whose context-local key is the
+  endpoint input key; nested lists continue to use the generic `#list` key.
+- Replaced the `funded` and `admin` boolean parameters on command helpers and
+  the `funded` boolean parameter on port helpers with a packed `uint8 flags`
+  argument. Endpoint flags now live in the dedicated `Flags` library.
+- Renamed the portal lifecycle events from `Undelivered` and `Recovered` to
+  `Unresolved` and `Resolved`, and renamed `Portal.retry` to `Portal.resolve`.
+  `Portal` now composes the node-access, runtime, and lifecycle-event
+  capabilities; concrete implementations remain responsible for explicitly
+  emitting lifecycle events.
+
+### Added
+
+- Added custom-spec overloads for `Decoders.list(cur, spec)` and
+  `Executions.list(exec, spec, lane)` so custom-keyed top-level lists can use
+  the same cursor model as generic nested lists.
+- Added `Specs.lane` for canonical descriptor lane packing and exported
+  `Flags` from the codec, command, and endpoint package entry points.
+
+### Changed
+
+- Updated schema and indexing documentation and the list example for the
+  custom-keyed top-level list convention.
+
 ## 1.20.0
 
 ### Breaking Changes

package/Codec.sol

@@ -7,7 +7,7 @@ pragma solidity ^0.8.33;
 import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
-import { Descriptors } from "./codec/Descriptors.sol";
+import { Descriptors, Flags } from "./codec/Descriptors.sol";
 import { Schemas } from "./codec/Schema.sol";
 import { Decoders } from "./codec/Decoders.sol";
 import { Cursors, Cur } from "./utils/Cursors.sol";

package/Commands.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file for both standard Execution-based commands and custom decoders.
 
 import {CommandBase} from "./commands/Base.sol";
+import {Flags} from "./codec/Descriptors.sol";
 import {Execution, Executions} from "./execution/Execution.sol";
 import {Lanes} from "./utils/Lanes.sol";
 import {Blocks} from "./codec/Blocks.sol";

package/Endpoints.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
 // Shared endpoint hooks
+import {Flags} from "./codec/Descriptors.sol";
 import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} from "./core/Settlement.sol";
 
 // Commands

package/Events.sol

@@ -12,7 +12,7 @@ import { CommanderEvent } from "./events/Commander.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
 import { ReceivedEvent } from "./events/Received.sol";
-import { RecoveredEvent } from "./events/Recovered.sol";
+import { ResolvedEvent } from "./events/Resolved.sol";
 import { RelayEvent } from "./events/Relay.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
@@ -22,7 +22,7 @@ import { NodeEvent } from "./events/Node.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 { UnresolvedEvent } from "./events/Unresolved.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";
 
 

package/README.md

@@ -121,17 +121,18 @@ on the wire. The full schema language is specified in
 `Schemas` and their runtime keys in `Keys` (both via
 `@rootzero/contracts/Codec.sol`).
 
+A rare top-level list is published as a custom schema such as `many #asset`.
+Its context-local schema key becomes the outer block key accepted by the
+endpoint; nested lists continue to use the generic `#list` key.
+
 ## Batches
 
 A input is not a single struct; it is a run of blocks. One `#amount` block
 asks for one deposit, five blocks ask for five, and the code path is identical
 — every endpoint parses with a cursor and loops until the stream is exhausted.
 The descriptor lane key is the prime item: it is the block type that may repeat
-for batching. Plain lanes are encoded as `[key][0]`; readers interpret the zero
-group byte as group size 1 when the lane is non-empty. Generic list lanes such
-as `many #asset` are encoded as
-`[Keys.List][Keys.Asset]`, so indexers can see both the top-level LIST container
-and the item type inside it.
+for batching. Readers interpret a zero group byte as group size 1 when the lane
+is non-empty.
 
 Off-chain, building a batch is concatenation. Using the reference encoders from
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts):
@@ -308,7 +309,7 @@ abstract contract MyCommand is CommandBase {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
+        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, 0);
     }
 
     function myCommand(
@@ -327,6 +328,10 @@ abstract contract MyCommand is CommandBase {
 }
 ```
 
+The final argument is a packed flags byte. Pass `0` for an ordinary endpoint,
+or compose values such as `Flags.Funded`, `Flags.Admin`, and
+`Flags.AdminFunded` from the command or endpoint package entry point.
+
 The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `settlePayable` (funded settlement),
 `withdraw` and `burn` (funds out),
@@ -466,12 +471,13 @@ Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
   `Settlement`, `Pipeline`, `Portal`, validator
-- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, codec
-  helpers, and shared value types for authoring custom commands
+- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, `Flags`,
+  codec helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
-  mixins and their hooks
+  mixins, their hooks, and `Flags`
 - `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
-  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`, and `Specs`
+  `Reader`/`Readers`, `Writers`, `Schemas`, `Descriptors`, `Flags`, `Keys`, and
+  `Specs`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts

package/codec/Decoders.sol

@@ -194,7 +194,15 @@ library Decoders {
     /// @param cur Cursor advanced past the list.
     /// @return items Cursor spanning the list payload.
     function list(Cur memory cur) internal pure returns (Cur memory items) {
-        (uint abs, uint end) = consume(cur, Specs.List);
+        return list(cur, Specs.List);
+    }
+
+    /// @notice Consume a list block described by `spec` and return a cursor over its items.
+    /// @param cur Cursor advanced past the list.
+    /// @param spec Custom list block specification.
+    /// @return items Cursor spanning the list payload.
+    function list(Cur memory cur, uint spec) internal pure returns (Cur memory items) {
+        (uint abs, uint end) = consume(cur, spec);
         items.state = Cursors.create(abs, end - abs, 0, 0, 0);
     }
 

package/codec/Descriptors.sol

@@ -4,25 +4,32 @@ pragma solidity ^0.8.33;
 import {Specs} from "./Specs.sol";
 import {Lanes} from "../utils/Lanes.sol";
 
+/// @title Flags
+/// @notice Packed endpoint behavior flags.
+library Flags {
+    /// @dev Endpoint accepts nonzero native value.
+    uint8 internal constant Funded = 1 << 0;
+    /// @dev Endpoint is restricted to the admin account.
+    uint8 internal constant Admin = 1 << 1;
+    /// @dev Endpoint accepts nonzero native value and is restricted to the admin account.
+    uint8 internal constant AdminFunded = Admin | Funded;
+}
+
 /// @title Descriptors
 /// @notice Packing and lane metadata helpers for endpoint descriptors.
 library Descriptors {
     /// @dev The requested lane is not part of an endpoint descriptor.
     error InvalidLane();
 
-    /// @dev Endpoint accepts nonzero native value.
-    uint8 internal constant Funded = 1 << 0;
-    /// @dev Endpoint is restricted to the admin account.
-    uint8 internal constant Admin = 1 << 1;
-
     /// @notice Create a descriptor from endpoint lane specifications and flags.
     /// @dev Layout: `[state key:4][stride:1]`
-    /// `[input key:4][item:4][stride:1]`
+    /// `[input key:4][stride:1]`
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
+    /// `[reserved:4]`
     /// `[transactions:1]`
     /// `[flags:1]`. Flag bits: funded = 0, admin = 1.
     /// @param state State lane specification.
-    /// @param input Input lane specification, optionally wrapped in a container.
+    /// @param input Direct input lane specification.
     /// @param output Output writer specification.
     /// @param transactions Transactions produced per batch.
     /// @param flags Endpoint behavior flags.
@@ -34,15 +41,13 @@ library Descriptors {
         uint8 transactions,
         uint8 flags
     ) internal pure returns (uint descriptor) {
-        state = Specs.normalize(state, true);
-        input = Specs.normalize(input, false);
-        output = Specs.normalize(output, true);
+        output = Specs.normalize(output);
         descriptor = pack(state, input, output, transactions, flags);
     }
 
-    /// @dev Pack normalized endpoint specs and flags into a descriptor.
-    /// @param state Normalized direct state specification.
-    /// @param input Normalized input specification.
+    /// @dev Pack endpoint specs and flags into a descriptor.
+    /// @param state State specification.
+    /// @param input Input specification.
     /// @param output Normalized direct output specification.
     /// @param transactions Transactions produced per batch.
     /// @param flags Endpoint behavior flags.
@@ -54,14 +59,9 @@ library Descriptors {
         uint8 transactions,
         uint8 flags
     ) private pure returns (uint descriptor) {
-        (bytes4 outer, bytes4 child) = Specs.keys(input);
-
-        descriptor |= uint(uint32(Specs.key(state))) << 224;
-        descriptor |= uint(Specs.stride(state)) << 216;
-        descriptor |= uint(uint32(outer)) << 184;
-        descriptor |= uint(uint32(child)) << 152;
-        descriptor |= uint(Specs.stride(input)) << 144;
-        descriptor |= (output >> 128) << 16;
+        descriptor |= uint(Specs.lane(state)) << 216;
+        descriptor |= uint(Specs.lane(input)) << 176;
+        descriptor |= (output >> 128) << 48;
         descriptor |= uint(transactions) << 8;
         descriptor |= flags;
     }
@@ -82,22 +82,22 @@ library Descriptors {
     /// @return Effective blocks per batch for the lane.
     function stride(uint descriptor, uint8 lane) internal pure returns (uint8) {
         if (lane == Lanes.State) return uint8(descriptor >> 216);
-        if (lane == Lanes.Input) return uint8(descriptor >> 144);
-        if (lane == Lanes.Output) return uint8(descriptor >> 16);
+        if (lane == Lanes.Input) return uint8(descriptor >> 176);
+        if (lane == Lanes.Output) return uint8(descriptor >> 48);
         if (lane == Lanes.Transactions) return uint8(descriptor >> 8);
         revert InvalidLane();
     }
 
     /// @notice Return the effective block key for `lane`.
-    /// @dev Input returns its outer key. Transaction blocks have a fixed
-    /// protocol key that is not stored in the descriptor.
+    /// @dev Transaction blocks have a fixed protocol key that is not stored in
+    /// the descriptor.
     /// @param descriptor Packed endpoint descriptor.
     /// @param lane Lane identifier from `Lanes`.
-    /// @return Effective outer block key for the lane.
+    /// @return Effective block key for the lane.
     function key(uint descriptor, uint8 lane) internal pure returns (bytes4) {
         if (lane == Lanes.State) return bytes4(uint32(descriptor >> 224));
         if (lane == Lanes.Input) return bytes4(uint32(descriptor >> 184));
-        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 112));
+        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 144));
         if (lane == Lanes.Transactions) return Specs.key(Specs.Transaction);
         revert InvalidLane();
     }
@@ -110,7 +110,7 @@ library Descriptors {
     /// @return growable Whether the writer may grow beyond that capacity.
     function allocation(uint descriptor, uint8 lane, uint groups) internal pure returns (uint capacity, bool growable) {
         if (lane == Lanes.Output) {
-            uint spec = uint(uint128(descriptor >> 16)) << 128;
+            uint spec = uint(uint128(descriptor >> 48)) << 128;
             return Specs.allocation(spec, groups);
         }
         if (lane == Lanes.Transactions) {

package/codec/Schema.sol

@@ -8,7 +8,7 @@ pragma solidity ^0.8.33;
 //
 // Schema:
 // - block aliases are published separately from payload schemas
-// - payload schemas are written as `{ fields }`
+// - payload schemas are `""`, `{ fields }`, or a top-level `many #x`
 // - an empty schema string means the block has no structured payload
 // - commas separate siblings at every level
 // - braces define the current block payload body
@@ -16,10 +16,10 @@ pragma solidity ^0.8.33;
 // - command state is a single active state run without trailing globals
 // - run items may repeat at top level for batching
 // - `maybe #x` marks an optional block item
-// - `many #x` emits one generic list block containing repeated `#x` items
-// - endpoint descriptor lanes are `[key bytes4][item bytes4]`; normal keys widen to `[key][0]`
-// - descriptor lanes for `many #x` use `[Keys.List][keyOfX]`; bare `[Keys.List][0]`
-//   is incomplete discovery metadata and should be rejected by tooling
+// - nested `many #x` emits one generic list block containing repeated `#x` items
+// - a custom schema consisting of top-level `many #x` uses its custom key for
+//   the outer list block and contains repeated `#x` items directly
+// - endpoint descriptor lanes identify their top-level block key directly
 // - `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

package/codec/Specs.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {Keys} from "./Keys.sol";
-import {max24, replace8, replace32} from "../utils/Utils.sol";
+import {max24, replace8} from "../utils/Utils.sol";
 
 /// @title Sizes
 /// @notice Total byte sizes for fixed-width block types, including the 8-byte header (4-byte key + 4-byte payloadLen).
@@ -39,15 +39,13 @@ library Sizes {
 
 /// @title Specs
 /// @notice Word-aligned block specifications encoded as
-/// `[key:4][min:4][max:4][hint:3][stride:1][container:4][reserved:12]`.
+/// `[key:4][min:4][max:4][hint:3][stride:1][reserved:16]`.
 /// The upper eight bytes of a fixed-layout spec are its encoded block header,
 /// allowing the entire spec word to be written directly as that header.
 /// A maximum of zero means unbounded and requires a growable writer.
 library Specs {
     /// @dev A payload is incompatible with its block specification.
     error InvalidSpec();
-    /// @dev A direct specification cannot contain a wrapper block.
-    error InvalidContainer();
     uint private constant SizeFields = (uint(1) << 192) | (uint(1) << 160) | (uint(1) << 136);
 
     // Reusable field shapes keep public specs readable while remaining valid
@@ -156,29 +154,20 @@ library Specs {
 
     /// @notice Return the canonical form of `spec` with implicit defaults resolved.
     /// @param spec Packed block specification.
-    /// @param direct Whether the specification must not contain a wrapper block.
     /// @dev A present spec with an encoded zero stride receives stride one;
     /// the empty spec remains unchanged.
     /// @return Canonical specification.
-    function normalize(uint spec, bool direct) internal pure returns (uint) {
-        if (direct && uint32(spec >> 96) != 0) revert InvalidContainer();
+    function normalize(uint spec) internal pure returns (uint) {
         if (stride(spec) == 0 && key(spec) != bytes4(0)) spec |= uint(1) << 128;
         return spec;
     }
 
-    /// @notice Return the effective outer block key and optional wrapped child key.
-    /// @dev A direct spec returns its own key as `outer` and a zero `child`.
+    /// @notice Return the canonical descriptor lane metadata for `spec`.
     /// @param spec Packed block specification.
-    /// @return outer Effective outer block key.
-    /// @return child Wrapped child key, or zero for a direct specification.
-    function keys(uint spec) internal pure returns (bytes4 outer, bytes4 child) {
-        child = key(spec);
-        outer = bytes4(uint32(spec >> 96));
-
-        if (outer == bytes4(0)) {
-            outer = child;
-            child = bytes4(0);
-        }
+    /// @return Packed `[key:4][stride:1]` lane metadata.
+    function lane(uint spec) internal pure returns (uint40) {
+        spec = normalize(spec);
+        return (uint40(uint32(key(spec))) << 8) | stride(spec);
     }
 
     /// @notice Return whether a payload size lies within a specification's bounds.
@@ -213,7 +202,7 @@ library Specs {
     /// @param groups Number of groups.
     /// @return Number of blocks across all groups.
     function count(uint spec, uint groups) internal pure returns (uint) {
-        return groups * stride(normalize(spec, false));
+        return groups * stride(normalize(spec));
     }
 
     /// @notice Return the buffer configuration for `groups` of `spec`.
@@ -227,13 +216,6 @@ library Specs {
         growable = uint32(spec >> 160) == 0;
     }
 
-    /// @notice Return `spec` annotated as a generic LIST item.
-    /// @param spec Child block specification.
-    /// @return Specification wrapped in a LIST container.
-    function many(uint spec) internal pure returns (uint) {
-        return replace32(spec, 96, uint32(key(List)));
-    }
-
     /// @notice Return `spec` grouped with an explicit stride.
     /// @param spec Packed block specification.
     /// @param n Number of blocks per group.

package/commands/Allocate.sol

@@ -24,7 +24,7 @@ abstract contract Allocate is CommandBase, AllocateHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("allocate", Specs.Balance, Specs.Node, Specs.Custody, 0, false, false);
+        (, descriptor) = command("allocate", Specs.Balance, Specs.Node, Specs.Custody, 0, 0);
     }
 
     /// @notice Allocate BALANCE state blocks to matching NODE input blocks.

package/commands/Base.sol

@@ -9,7 +9,7 @@ import {HostAmount, Position} from "../core/Types.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 import {ReceivedEvent} from "../events/Received.sol";
 import {Actions} from "../utils/Actions.sol";
-import {Descriptors} from "../codec/Descriptors.sol";
+import {Descriptors, Flags} from "../codec/Descriptors.sol";
 import {Nodes} from "../utils/Nodes.sol";
 import {Cursors} from "../utils/Cursors.sol";
 
@@ -44,8 +44,7 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
     /// @param input Input block specification.
     /// @param output Output block specification.
     /// @param transactions Number of transaction blocks produced per batch, or zero for none.
-    /// @param funded Whether the command accepts nonzero native value.
-    /// @param admin Whether the command is restricted to the admin account.
+    /// @param flags Packed command behavior flags.
     /// @return id Command node ID.
     /// @return descriptor Packed endpoint lane metadata and flags.
     function command(
@@ -54,12 +53,8 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
         uint input,
         uint output,
         uint8 transactions,
-        bool funded,
-        bool admin
+        uint8 flags
     ) internal returns (uint id, uint descriptor) {
-        uint8 flags = 0;
-        if (funded) flags |= Descriptors.Funded;
-        if (admin) flags |= Descriptors.Admin;
         descriptor = Descriptors.create(state, input, output, transactions, flags);
         return command(name, descriptor);
     }

package/commands/Burn.sol

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

package/commands/Credit.sol

@@ -17,7 +17,7 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("creditAccount", Specs.Balance, Specs.Empty, Specs.Empty, 0, false, false);
+        (id, descriptor) = command("creditAccount", Specs.Balance, Specs.Empty, Specs.Empty, 0, 0);
     }
 
     /// @notice Return the registered CREDIT_ACCOUNT command ID.

package/commands/Debit.sol

@@ -20,7 +20,7 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     uint private immutable id;
 
     constructor() {
-        (id, descriptor) = command("debitAccount", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
+        (id, descriptor) = command("debitAccount", Specs.Empty, Specs.Amount, Specs.Balance, 0, 0);
     }
 
     /// @notice Return the registered DEBIT_ACCOUNT command ID.

package/commands/Deposit.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 {Action} from "../annotations/Action.sol";
 import {Actions} from "../utils/Actions.sol";
 
@@ -39,7 +39,7 @@ abstract contract Deposit is CommandBase, DepositHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("deposit", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
+        (id, descriptor) = command("deposit", Specs.Empty, Specs.Amount, Specs.Balance, 0, 0);
         action(id, Actions.Deposit);
     }
 
@@ -72,7 +72,7 @@ abstract contract DepositPayable is CommandBase, DepositPayableHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("depositPayable", Specs.Empty, Specs.Amount, Specs.Balance, 0, true, false);
+        (id, descriptor) = command("depositPayable", Specs.Empty, Specs.Amount, Specs.Balance, 0, Flags.Funded);
         action(id, Actions.Deposit);
     }
 
@@ -96,10 +96,3 @@ abstract contract DepositPayable is CommandBase, DepositPayableHook, Action {
         return close(exec, account);
     }
 }
-
-
-
-
-
-
-

package/commands/Payout.sol

@@ -26,7 +26,7 @@ abstract contract Payout is CommandBase, PayoutHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = command("payout", Specs.Balance, Specs.Account, Specs.Empty, 0, false, false);
+        (id, descriptor) = command("payout", Specs.Balance, Specs.Account, Specs.Empty, 0, 0);
         action(id, Actions.Payout);
     }
 

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,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";
 
 using Executions for Execution;
 
@@ -32,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.
@@ -58,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.

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);
     }