@rootzero/contracts 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.20.0
+
+### Breaking Changes
+
+- `Nodes.toCommand`, `toPort`, `toQuery`, and `toGuard` now take an endpoint
+  name instead of a precomputed selector. The `Selectors` library was removed;
+  endpoint node IDs now derive their canonical selectors internally.
+- Renamed the memory-backed pipeline adapters from `InternalDebitAccount`,
+  `InternalCreditAccount`, and `InternalSettle` to `DebitAccountInternal`,
+  `CreditAccountInternal`, and `SettleInternal`.
+- Replaced `RelayPayableHook.relayTo(portal, resources, payload, funds)` with
+  `relay(portal, resources, account, state, input, funds)`. Relay commands now
+  pass their semantic context fields to the host instead of encoding a
+  `CONTEXT` payload before invoking the hook.
+- `DispatchPayablePort` now uses the dedicated
+  `DispatchPayableHook.dispatchTo(portal, resources, payload, funds)` hook
+  instead of sharing `RelayPayableHook`.
+
+### Added
+
+- Added `RelayEvent`, with account, portal, resources, correlation key, and
+  digest fields for recording outbound relay references.
+
+### Changed
+
+- Relay hooks retain state and nested relay input as calldata until an
+  implementation chooses to encode or otherwise consume the destination
+  context.
+
+### Upgrade Compatibility
+
+- Pass endpoint names directly to the `Nodes.to*` helpers and remove imports of
+  `Selectors`.
+- Update inherited internal adapter names and imports to the new postfix
+  convention.
+- Implement the structured `RelayPayableHook.relay` hook for relay commands and
+  `DispatchPayableHook.dispatchTo` for opaque dispatch payloads. Hosts that
+  support both surfaces must implement both hooks.
+
 ## 1.19.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -11,15 +11,15 @@ import {CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook} fr
 import {CommandBase} from "./commands/Base.sol";
 import {Allocate, AllocateHook} from "./commands/Allocate.sol";
 import {Burn, BurnHook} from "./commands/Burn.sol";
-import {CreditAccount, InternalCreditAccount} from "./commands/Credit.sol";
-import {DebitAccount, InternalDebitAccount} from "./commands/Debit.sol";
+import {CreditAccount, CreditAccountInternal} from "./commands/Credit.sol";
+import {DebitAccount, DebitAccountInternal} 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, RecoverPayableHook} from "./commands/Recover.sol";
 import {Repay, RepayPayable, RepayPayableHook} from "./commands/Repay.sol";
 import {RelayPayable, RelayBalancePayable, RelayPayableHook} from "./commands/Relay.sol";
-import {Settle, SettlePayable, SettlePayableHook, InternalSettle} from "./commands/Settle.sol";
+import {Settle, SettlePayable, SettlePayableHook, SettleInternal} from "./commands/Settle.sol";
 import {Withdraw, WithdrawHook} from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -43,7 +43,7 @@ import {CreditAccountPort} from "./ports/Credit.sol";
 import {DebitAccountPort} from "./ports/Debit.sol";
 import {DenyAssetsPort} from "./ports/DenyAssets.sol";
 import {PipePayablePort} from "./ports/Pipe.sol";
-import {DispatchPayablePort} from "./ports/Dispatch.sol";
+import {DispatchPayablePort, DispatchPayableHook} from "./ports/Dispatch.sol";
 import {PostPort} from "./ports/Post.sol";
 
 // Guard endpoints

package/Events.sol

@@ -13,6 +13,7 @@ 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 { RelayEvent } from "./events/Relay.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";

package/README.md

@@ -378,8 +378,8 @@ command batching — and `resources` is a chain-specific word interpreted by the
 portal adapter (on EVM, the low 128 bits are native value in wei, drawn from a
 shared budget), so the same pipeline bytes are meaningful to every port.
 
-Hosts that implement a pipeline locally can inherit `InternalDebitAccount`,
-`InternalCreditAccount`, and `InternalSettle` to advertise the canonical command
+Hosts that implement a pipeline locally can inherit `DebitAccountInternal`,
+`CreditAccountInternal`, and `SettleInternal` to advertise the canonical command
 endpoints while routing their local command IDs through `executeDebitAccount`,
 `executeCreditAccount`, and `executeSettle`. These adapters consume the
 memory-backed pipeline state directly and avoid an external self-call. Pass the

package/Utils.sol

@@ -11,7 +11,6 @@ import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
 import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
-import { Selectors } from "./utils/Selectors.sol";
 import { Layout } from "./utils/Layout.sol";
 import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, clear8, clear16, clear32, clear64, divisible, ensureAddr, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, replace8, replace16, replace32, replace64, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow, ZeroAddress } from "./utils/Utils.sol";
 

package/commands/Base.sol

@@ -11,7 +11,6 @@ import {ReceivedEvent} from "../events/Received.sol";
 import {Actions} from "../utils/Actions.sol";
 import {Descriptors} from "../codec/Descriptors.sol";
 import {Nodes} from "../utils/Nodes.sol";
-import {Selectors} from "../utils/Selectors.sol";
 import {Cursors} from "../utils/Cursors.sol";
 
 using Executions for Execution;
@@ -72,7 +71,7 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
     /// @return id Command node ID.
     /// @return published Published endpoint descriptor.
     function command(string memory name, uint descriptor) internal returns (uint id, uint published) {
-        id = Nodes.toCommand(Selectors.command(name), address(this));
+        id = Nodes.toCommand(name, address(this));
         published = endpoint(id, name, descriptor);
     }
 

package/commands/Credit.sol

@@ -45,11 +45,11 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     }
 }
 
-/// @title InternalCreditAccount
+/// @title CreditAccountInternal
 /// @notice Extends the advertised credit-account command with memory-state pipeline dispatch.
 /// @dev This adapter is not a separate command. It uses the command ID and account hook
 /// inherited from `CreditAccount` while accepting the state location used by `Pipeline`.
-abstract contract InternalCreditAccount is CreditAccount {
+abstract contract CreditAccountInternal is CreditAccount {
     /// @notice Execute the inherited credit-account command from an internal pipeline.
     /// @param account Account credited by each balance.
     /// @param state BALANCE block stream held in pipeline memory.

package/commands/Debit.sol

@@ -49,11 +49,11 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     }
 }
 
-/// @title InternalDebitAccount
+/// @title DebitAccountInternal
 /// @notice Extends the advertised debit-account command with memory-state pipeline dispatch.
 /// @dev This adapter is not a separate command. It uses the command ID and account hook
 /// inherited from `DebitAccount` while accepting the state location used by `Pipeline`.
-abstract contract InternalDebitAccount is DebitAccount {
+abstract contract DebitAccountInternal is DebitAccount {
     /// @notice Execute the inherited debit-account command from an internal pipeline.
     /// @param account Account whose funds are debited.
     /// @param state Empty pipeline state required by the command schema.

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, 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
@@ -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);
     }
@@ -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/Settle.sol

@@ -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/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/guards/Base.sol

@@ -5,7 +5,6 @@ import {InputEndpointBase} from "../core/Endpoint.sol";
 import {GuardianAccess} from "../core/Access.sol";
 import {Specs} from "../codec/Specs.sol";
 import {Nodes} from "../utils/Nodes.sol";
-import {Selectors} from "../utils/Selectors.sol";
 
 /// @title GuardBase
 /// @notice Abstract base for guardian-only direct host actions.
@@ -27,7 +26,7 @@ abstract contract GuardBase is GuardianAccess, InputEndpointBase {
         string memory name,
         uint input
     ) internal returns (uint id, uint descriptor) {
-        id = Nodes.toGuard(Selectors.guard(name), address(this));
+        id = Nodes.toGuard(name, address(this));
         descriptor = endpoint(id, name, Specs.Empty, input, Specs.Empty, 0, 0);
     }
 }

package/package.json

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

package/ports/Base.sol

@@ -6,7 +6,6 @@ import { NodeAccess } from "../core/Access.sol";
 import { Specs } from "../codec/Specs.sol";
 import { InputEndpointBase } from "../core/Endpoint.sol";
 import { Nodes } from "../utils/Nodes.sol";
-import { Selectors } from "../utils/Selectors.sol";
 import { Descriptors } from "../codec/Descriptors.sol";
 
 /// @title PortBase
@@ -56,7 +55,7 @@ abstract contract PortBase is NodeCalls, NodeAccess, InputEndpointBase {
         string memory name,
         uint descriptor
     ) internal returns (uint id, uint published) {
-        id = Nodes.toPort(Selectors.port(name), address(this));
+        id = Nodes.toPort(name, address(this));
         published = endpoint(id, name, descriptor);
     }
 }

package/ports/Dispatch.sol

@@ -2,23 +2,34 @@
 pragma solidity ^0.8.33;
 
 import {PortBase} from "./Base.sol";
-import {RelayPayableHook} from "../commands/Relay.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
 
 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 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 funds Execution used for source value available for transport fees
+    /// and destination resource funding.
+    function dispatchTo(uint portal, uint resources, bytes memory payload, Execution memory funds) internal virtual;
+}
+
 /// @title DispatchPayablePort
-/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined relay hook.
-abstract contract DispatchPayablePort is PortBase, RelayPayableHook {
+/// @notice Port endpoint that forwards DISPATCH blocks to a host-defined dispatch hook.
+abstract contract DispatchPayablePort is PortBase, DispatchPayableHook {
     uint private immutable descriptor;
 
     constructor() {
         (, descriptor) = port("portDispatchPayable", Specs.Dispatch, Specs.Empty, true);
     }
 
-    /// @notice Forward peer-supplied dispatches to the host-defined relay hook.
-    /// @dev Relay hooks receive the shared top-level source value
+    /// @notice Forward peer-supplied dispatches to the host-defined dispatch hook.
+    /// @dev Dispatch hooks receive the shared top-level source value
     ///      budget. Any `msg.value` not spent by the hook remains on this host.
     /// @param data DISPATCH block stream supplied by the trusted peer.
     /// @return Empty response bytes.
@@ -27,7 +38,7 @@ abstract contract DispatchPayablePort is PortBase, RelayPayableHook {
 
         while (exec.more()) {
             (uint portal, uint resources, bytes calldata payload) = exec.unpackDispatch(Lanes.Input);
-            relayTo(portal, resources, payload, exec);
+            dispatchTo(portal, resources, payload, exec);
         }
         
         return "";

package/queries/Base.sol

@@ -5,7 +5,6 @@ import { InputEndpointBase } from "../core/Endpoint.sol";
 import { Descriptors } from "../codec/Descriptors.sol";
 import { Specs } from "../codec/Specs.sol";
 import { Nodes } from "../utils/Nodes.sol";
-import { Selectors } from "../utils/Selectors.sol";
 
 /// @title QueryBase
 /// @notice Abstract base for rootzero query contracts.
@@ -39,7 +38,7 @@ abstract contract QueryBase is InputEndpointBase {
         string memory name,
         uint descriptor
     ) internal returns (uint id, uint published) {
-        id = Nodes.toQuery(Selectors.query(name), address(this));
+        id = Nodes.toQuery(name, address(this));
         published = endpoint(id, name, descriptor);
     }
 }

package/utils/Nodes.sol

@@ -192,40 +192,45 @@ library Nodes {
         return toLocalBase(Host) | uint(uint160(target));
     }
 
-    /// @notice Build a chain-local command ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the command entry point.
+    /// @notice Build a chain-local command ID for the given endpoint name and contract.
+    /// @param name Command function name.
     /// @param target Command contract address.
     /// @return node Command node ID embedding both the selector and address.
-    function toCommand(bytes4 selector, address target) internal view returns (uint node) {
+    function toCommand(string memory name, address target) internal view returns (uint node) {
         node = toLocalBase(Command) | uint(uint160(target));
-        node |= uint(uint32(selector)) << 160;
+        node |= uint(uint32(toSelector(name, "(bytes32,bytes,bytes)"))) << 160;
     }
 
-    /// @notice Build a chain-local port ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the port entry point.
+    /// @notice Build a chain-local port ID for the given endpoint name and contract.
+    /// @param name Port function name.
     /// @param target Port contract address.
     /// @return node Port node ID embedding both the selector and address.
-    function toPort(bytes4 selector, address target) internal view returns (uint node) {
+    function toPort(string memory name, address target) internal view returns (uint node) {
         node = toLocalBase(Port) | uint(uint160(target));
-        node |= uint(uint32(selector)) << 160;
+        node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 
-    /// @notice Build a chain-local query ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the query entry point.
+    /// @notice Build a chain-local query ID for the given endpoint name and contract.
+    /// @param name Query function name.
     /// @param target Query contract address.
     /// @return node Query node ID embedding both the selector and address.
-    function toQuery(bytes4 selector, address target) internal view returns (uint node) {
+    function toQuery(string memory name, address target) internal view returns (uint node) {
         node = toLocalBase(Query) | uint(uint160(target));
-        node |= uint(uint32(selector)) << 160;
+        node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
     }
 
-    /// @notice Build a chain-local guard action ID for the given selector and contract.
-    /// @param selector 4-byte ABI selector of the guard action entry point.
+    /// @notice Build a chain-local guard action ID for the given endpoint name and contract.
+    /// @param name Guard action function name.
     /// @param target Guard action contract address.
     /// @return node Guard action node ID embedding both the selector and address.
-    function toGuard(bytes4 selector, address target) internal view returns (uint node) {
+    function toGuard(string memory name, address target) internal view returns (uint node) {
         node = toLocalBase(Guard) | uint(uint160(target));
-        node |= uint(uint32(selector)) << 160;
+        node |= uint(uint32(toSelector(name, "(bytes)"))) << 160;
+    }
+
+    /// @dev Derive an ABI selector from an endpoint name and argument signature.
+    function toSelector(string memory name, string memory args) private pure returns (bytes4) {
+        return bytes4(keccak256(bytes(string.concat(name, args))));
     }
 
     /// @notice Derive an opaque node ID from a keccak preimage.

package/utils/Selectors.sol

@@ -1,49 +0,0 @@
-// SPDX-License-Identifier: GPL-3.0-only
-pragma solidity ^0.8.33;
-
-/// @title Selectors
-/// @notice Canonical ABI selector derivation for rootzero endpoint types.
-library Selectors {
-    /// @notice Derive the ABI selector for a command entrypoint.
-    /// @param name Command function name.
-    /// @return Selector for `name(bytes32,bytes,bytes)`.
-    function command(string memory name) internal pure returns (bytes4) {
-        return derive(name, "(bytes32,bytes,bytes)");
-    }
-
-    /// @notice Derive the ABI selector for a port entrypoint.
-    /// @param name Port function name.
-    /// @return Selector for `name(bytes)`.
-    function port(string memory name) internal pure returns (bytes4) {
-        return direct(name);
-    }
-
-    /// @notice Derive the ABI selector for a query entrypoint.
-    /// @param name Query function name.
-    /// @return Selector for `name(bytes)`.
-    function query(string memory name) internal pure returns (bytes4) {
-        return direct(name);
-    }
-
-    /// @notice Derive the ABI selector for a guard action entrypoint.
-    /// @param name Guard action function name.
-    /// @return Selector for `name(bytes)`.
-    function guard(string memory name) internal pure returns (bytes4) {
-        return direct(name);
-    }
-
-    /// @dev Derive a direct endpoint selector with a single `bytes` argument.
-    /// @param name Endpoint function name.
-    /// @return Selector for `name(bytes)`.
-    function direct(string memory name) private pure returns (bytes4) {
-        return derive(name, "(bytes)");
-    }
-
-    /// @dev Derive an ABI selector from a function name and argument signature suffix.
-    /// @param name Function name.
-    /// @param args Parenthesized ABI argument signature.
-    /// @return First four bytes of the function signature hash.
-    function derive(string memory name, string memory args) private pure returns (bytes4) {
-        return bytes4(keccak256(bytes(string.concat(name, args))));
-    }
-}