@rootzero/contracts 1.20.0 → 1.22.0

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/Host.sol

@@ -61,16 +61,19 @@ abstract contract CommandHost is CommanderAccess, CallerAccess, HostIntroduction
     function enforceCaller(address caller) internal view virtual override returns (address) {
         return enforceCommander(caller);
     }
-
 }
 
 /// @title Admins
 /// @notice Optional bundle of the default host administration commands.
-abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {}
+abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {
+
+}
 
 /// @title Guardians
 /// @notice Optional bundle for guardian management and the default revoke guard.
-abstract contract Guardians is Appoint, Dismiss, Revoke {}
+abstract contract Guardians is Appoint, Dismiss, Revoke {
+
+}
 
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
@@ -78,13 +81,7 @@ abstract contract Guardians is Appoint, Dismiss, Revoke {}
 /// guardian management, the default guardian revoke action, and
 /// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.
-abstract contract Host is
-    Admins,
-    Guardians,
-    HostIntroduction,
-    IntroductionEvent,
-    IHostIntroduction
-{
+abstract contract Host is Admins, Guardians, HostIntroduction, IntroductionEvent, IHostIntroduction {
     /// @param cmdr Commander address; used by the composed access capabilities.
     ///        If `cmdr` is a deployed contract, the host calls `introduce`
     ///        on it during construction.

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/events/Dispatch.sol

@@ -8,7 +8,7 @@ abstract contract DispatchEvent is EventEmitter {
     string private constant ABI = "event Dispatch(uint indexed host, uint portal, uint resources, bytes32 key, bytes32 digest)";
 
     /// @param host Host node ID that owns the dispatch.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID.
     /// @param resources Chain-specific resources assigned to the dispatch.
     /// @param key Dispatch correlation or recovery lookup key.
     /// @param digest Digest of the dispatched payload or canonical envelope.

package/events/Relay.sol

@@ -8,7 +8,7 @@ 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 portal Destination portal implementation's 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.

package/events/Resolved.sol

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

package/events/Route.sol

@@ -8,7 +8,7 @@ abstract contract RouteEvent is EventEmitter {
     string private constant ABI = "event Route(uint indexed host, uint portal, uint status)";
 
     /// @param host Host node ID that owns the route.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID.
     /// @param status Route status. Zero means inactive; nonzero means active.
     event Route(uint indexed host, uint portal, uint status);
 

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

@@ -187,6 +187,25 @@ library Executions {
         return exec.decoders.any();
     }
 
+    /// @notice Return a decoder lane's current absolute calldata position.
+    /// @param exec Execution whose decoder is inspected.
+    /// @param lane Decoder lane to select.
+    /// @return Current absolute calldata position of the selected lane.
+    function absolute(Execution memory exec, uint8 lane) internal pure returns (uint) {
+        return exec.decoders.select(lane).absolute();
+    }
+
+    /// @notice Return whether the next block on `lane` has `key` and an empty payload.
+    /// @param exec Execution whose decoder is inspected without advancing.
+    /// @param lane Decoder lane to inspect.
+    /// @param key Expected block key.
+    /// @return Whether a complete matching empty block header occurs next.
+    function isEmpty(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (bool) {
+        uint cur = exec.decoders.select(lane);
+        (uint i, uint offset, uint len) = cur.decode();
+        return Blocks.isEmpty(offset + i, offset + len, key);
+    }
+
     /// @notice Validate and consume the next block from an execution decoder lane.
     /// @param exec Execution whose selected decoder cursor is advanced over the complete block.
     /// @param lane Execution decoder lane to select.
@@ -199,6 +218,20 @@ library Executions {
         exec.decoders = cur.seekAbs(end);
     }
 
+    /// @notice Consume a matching empty block from an execution decoder lane when present.
+    /// @param exec Execution whose selected decoder advances only for a matching empty block.
+    /// @param lane Decoder lane to consume.
+    /// @param key Expected block key.
+    /// @return Whether an empty block was consumed.
+    function tryConsumeEmpty(Execution memory exec, uint8 lane, bytes4 key) internal pure returns (bool) {
+        uint cur = exec.decoders.select(lane);
+        (uint i, uint offset, uint size) = cur.decode();
+        (bytes4 current, uint len) = Blocks.peek(offset + i, offset + size);
+        if (current != key || len != 0) return false;
+        exec.decoders = cur.seek(i + Sizes.Header);
+        return true;
+    }
+
     /// @notice Validate and enter the payload of the next block in an execution decoder lane.
     /// @dev The selected lane remains in its existing frame so callers can decode
     /// child blocks in place. Callers should prove complete payload consumption
@@ -209,9 +242,48 @@ library Executions {
     /// @return abs Absolute position of the first payload byte.
     /// @return end Absolute position immediately after the payload.
     function enter(Execution memory exec, uint8 lane, uint spec) internal pure returns (uint abs, uint end) {
+        return enter(exec, lane, spec, 0);
+    }
+
+    /// @notice Validate a parent block and advance over a fixed payload prefix.
+    /// @dev `amount` is relative to the payload start and cannot exceed the
+    /// current parent payload. The returned `abs` remains the payload start.
+    /// @param exec Execution whose selected decoder advances over the header and fixed prefix.
+    /// @param lane Execution decoder lane to select.
+    /// @param spec Expected parent block specification.
+    /// @param amount Number of initial payload bytes to advance over.
+    /// @return abs Absolute position of the first payload byte.
+    /// @return end Absolute position immediately after the payload.
+    function enter(
+        Execution memory exec,
+        uint8 lane,
+        uint spec,
+        uint amount
+    ) internal pure returns (uint abs, uint end) {
         uint cur = exec.decoders.select(lane);
         (abs, end) = Blocks.expect(cur.absolute(), spec);
-        exec.decoders = cur.seekAbs(abs);
+        if (amount > end - abs) revert Blocks.InvalidBlock();
+        exec.decoders = cur.seekAbs(abs + amount);
+    }
+
+    /// @notice Advance an execution decoder lane by a raw byte count.
+    /// @dev No block header or schema is validated.
+    /// @param exec Execution whose selected decoder cursor is advanced.
+    /// @param lane Decoder lane to select.
+    /// @param amount Number of bytes to advance.
+    function advance(Execution memory exec, uint8 lane, uint amount) internal pure {
+        uint cur = exec.decoders.select(lane);
+        exec.decoders = cur.advance(amount);
+    }
+
+    /// @notice Take a raw byte range from an execution decoder lane.
+    /// @dev No block header or schema is validated.
+    /// @param exec Execution whose selected decoder cursor is advanced.
+    /// @param lane Decoder lane to select.
+    /// @param amount Number of bytes to take.
+    /// @return abs Absolute position of the first taken byte.
+    function take(Execution memory exec, uint8 lane, uint amount) internal pure returns (uint abs) {
+        (exec.decoders, abs) = exec.decoders.consume(lane, amount);
     }
 
     /// @notice Require the active execution decoder to be at absolute position `abs`.
@@ -227,7 +299,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);
     }
 
@@ -237,9 +318,7 @@ library Executions {
 
     /// @dev Return the next raw calldata word from `lane` and advance by `size` bytes.
     function next(Execution memory exec, uint8 lane, uint size) private pure returns (bytes32 value) {
-        uint abs;
-        (exec.decoders, abs) = exec.decoders.consume(lane, size);
-        value = Blocks.read32(abs);
+        value = Blocks.read32(take(exec, lane, size));
     }
 
     /// @notice Return the next raw byte from a decoder lane and advance it by one byte.
@@ -797,6 +876,14 @@ library Executions {
         return reserve(exec, size, size);
     }
 
+    /// @notice Append an empty block to execution output.
+    /// @param exec Execution receiving the block.
+    /// @param key Block key.
+    function outputEmpty(Execution memory exec, bytes4 key) internal pure {
+        uint i = reserve(exec, Sizes.Header);
+        Blocks.writeEmpty(exec.output, i, key);
+    }
+
     /// @notice Append an ACCOUNT block to execution output.
     /// @param exec Execution receiving the block.
     /// @param account Account identifier to encode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",
@@ -9,8 +9,7 @@
     "**/*.sol",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE",
-    "docs/Schema.md"
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"

package/ports/AllowAssets.sol

@@ -15,7 +15,7 @@ abstract contract AllowAssetsPort is PortBase, AllowAssetsHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portAllowAssets", Specs.Asset, Specs.Empty, false);
+        (, descriptor) = port("portAllowAssets", Specs.Asset, Specs.Empty, 0);
     }
 
     /// @notice Execute the allow-assets peer call.

package/ports/Allowance.sol

@@ -16,7 +16,7 @@ abstract contract AllowancePort is PortBase, AllowanceHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portAllowance", Specs.Amount, Specs.Empty, false);
+        (, descriptor) = port("portAllowance", Specs.Amount, Specs.Empty, 0);
     }
 
     /// @notice Execute the allowance port call.

package/ports/Base.sol

@@ -32,16 +32,16 @@ abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
     /// match the Solidity port function name used by the canonical ABI.
     /// @param input Input block specification.
     /// @param output Output block specification.
-    /// @param funded Whether the port accepts nonzero native value.
+    /// @param flags Packed port behavior flags.
     /// @return id Port node ID.
     /// @return descriptor Packed endpoint lane metadata and flags.
     function port(
         string memory name,
         uint input,
         uint output,
-        bool funded
+        uint8 flags
     ) internal returns (uint id, uint descriptor) {
-        descriptor = Descriptors.create(Specs.Empty, input, output, 0, funded ? Descriptors.Funded : 0);
+        descriptor = Descriptors.create(Specs.Empty, input, output, 0, flags);
         return port(name, descriptor);
     }
 

package/ports/Credit.sol

@@ -15,7 +15,7 @@ abstract contract CreditAccountPort is PortBase, CreditAccountHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portCreditAccount", Specs.AccountAmount, Specs.Empty, false);
+        (, descriptor) = port("portCreditAccount", Specs.AccountAmount, Specs.Empty, 0);
     }
 
     /// @notice Execute the port-credit call.

package/ports/Debit.sol

@@ -15,7 +15,7 @@ abstract contract DebitAccountPort is PortBase, DebitAccountHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portDebitAccount", Specs.AccountAmount, Specs.Empty, false);
+        (, descriptor) = port("portDebitAccount", Specs.AccountAmount, Specs.Empty, 0);
     }
 
     /// @notice Execute the port-debit call.

package/ports/DenyAssets.sol

@@ -15,7 +15,7 @@ abstract contract DenyAssetsPort is PortBase, DenyAssetsHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portDenyAssets", Specs.Asset, Specs.Empty, false);
+        (, descriptor) = port("portDenyAssets", Specs.Asset, Specs.Empty, 0);
     }
 
     /// @notice Execute the deny-assets peer call.

package/ports/Dispatch.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
+import {Flags} from "../codec/Descriptors.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
@@ -10,7 +11,8 @@ using Executions for Execution;
 /// @notice Hook implemented by hosts that forward funded dispatch payloads.
 abstract contract DispatchPayableHook {
     /// @notice Override to dispatch an encoded payload to `portal`.
-    /// @param portal Destination portal identifier, often the destination host ID.
+    /// @param portal Destination portal implementation's host ID. Implementations
+    /// may validate or resolve it for their transport.
     /// @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.
@@ -25,7 +27,7 @@ abstract contract DispatchPayablePort is PortBase, DispatchPayableHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portDispatchPayable", Specs.Dispatch, Specs.Empty, true);
+        (, descriptor) = port("portDispatchPayable", Specs.Dispatch, Specs.Empty, Flags.Funded);
     }
 
     /// @notice Forward peer-supplied dispatches to the host-defined dispatch hook.

package/ports/Pipe.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
+import {Flags} from "../codec/Descriptors.sol";
 import {Pipeline} from "../core/Pipeline.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
@@ -16,7 +17,7 @@ abstract contract PipePayablePort is PortBase, Pipeline {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portPipePayable", Specs.Context, Specs.Empty, true);
+        (, descriptor) = port("portPipePayable", Specs.Context, Specs.Empty, Flags.Funded);
     }
 
     /// @notice Execute peer-supplied contexts through the shared payable pipe.

package/ports/Post.sol

@@ -18,7 +18,7 @@ abstract contract PostPort is PortBase, PostHook, Action {
 
     constructor() {
         uint id;
-        (id, descriptor) = port("portPost", Specs.Transaction, Specs.Empty, false);
+        (id, descriptor) = port("portPost", Specs.Transaction, Specs.Empty, 0);
         action(id, Actions.Post);
     }
 

package/ports/Redeem.sol

@@ -24,7 +24,7 @@ abstract contract RedeemBalancePort is PortBase, RedeemBalanceHook {
     uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = port("portRedeemBalance", Specs.Balance, Specs.Empty, false);
+        (, descriptor) = port("portRedeemBalance", Specs.Balance, Specs.Empty, 0);
     }
 
     /// @notice Execute the balance redemption port call.