@rootzero/contracts 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -8,6 +8,19 @@ sections are immutable and must continue to describe the tagged release.
 
 ## Unreleased
 
+## 1.29.0
+
+### Breaking Changes
+
+- `ExecuteHook.execute` and the optimized local command helpers now return a
+  leading `bool handled`. A local command returned as unhandled is invoked
+  through its trusted normal external command entrypoint; handled commands keep
+  the optimized internal path and are authorized by the hook implementation.
+- Renamed `CashoutInternal`, `DebitAccountInternal`, `CreditAccountInternal`,
+  `SettleInternal`, and `RepayInternal` to `ExecuteCashout`,
+  `ExecuteDebitAccount`, `ExecuteCreditAccount`, `ExecuteSettle`, and
+  `ExecuteRepay`.
+
 ## 1.28.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -14,23 +14,23 @@ import {CommandBase} from "./commands/Base.sol";
 import {Allocate, AllocateHook} from "./commands/Allocate.sol";
 import {Burn, BurnHook} from "./commands/Burn.sol";
 import {Bootstrap} from "./commands/Bootstrap.sol";
-import {Cashout, CashoutHook, CashoutInternal} from "./commands/Cashout.sol";
-import {CreditAccount, CreditAccountInternal} from "./commands/Credit.sol";
-import {DebitAccount, DebitAccountInternal} from "./commands/Debit.sol";
+import {Cashout, CashoutHook, ExecuteCashout} from "./commands/Cashout.sol";
+import {CreditAccount, ExecuteCreditAccount} from "./commands/Credit.sol";
+import {DebitAccount, ExecuteDebitAccount} 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,
-    RepayInternal,
+    ExecuteRepay,
     RepayPayable,
     RepayPayableHook,
     RepayPosition,
     RepayPositionPayable
 } from "./commands/Repay.sol";
 import {RelayPayable, RelayBalancePayable, RelayPayableHook} from "./commands/Relay.sol";
-import {Settle, SettlePayable, SettlePayableHook, SettleInternal} from "./commands/Settle.sol";
+import {Settle, SettlePayable, SettlePayableHook, ExecuteSettle} from "./commands/Settle.sol";
 import {Withdraw, WithdrawHook} from "./commands/Withdraw.sol";
 
 // Admin commands

package/README.md

@@ -388,13 +388,17 @@ while (cur.more()) {
     (bytes4 selector, address target) = unpackCommand(cmd);
     if (budget < value) revert InsufficientValue();
     unchecked { budget -= value; }
+    bool handled;
+    bytes memory output;
     uint credit;
     if (target == address(this)) {
-        (state, credit) = execute(cmd, account, state, input, value);
-    } else {
+        (handled, output, credit) = execute(cmd, account, state, input, value);
+    }
+    if (!handled) {
         ensureTrusted(cmd);
-        (state, credit) = rawCommandCall(selector, target, value, account, state, input);
+        (output, credit) = rawCommandCall(selector, target, value, account, state, input);
     }
+    state = output;
     budget += credit;
 }
 if (state.length != 0) revert UnexpectedState();
@@ -414,15 +418,18 @@ parameters. A `resources` word is never itself native value; EVM adapters use
 `useResourceValue` to extract its low 128-bit value lane before spending it.
 
 Hosts that implement a pipeline locally can inherit `Bootstrap`,
-`CashoutInternal`, `DebitAccountInternal`, `CreditAccountInternal`,
-`SettleInternal`, and
-`RepayInternal` to register canonical command metadata while routing
+`ExecuteCashout`, `ExecuteDebitAccount`, `ExecuteCreditAccount`,
+`ExecuteSettle`, and
+`ExecuteRepay` to register canonical command metadata while executing
 their local command IDs through `executeBootstrap`, `executeCashout`,
 `executeDebitAccount`, `executeCreditAccount`, `executeSettle`, and
 `executeRepay`. The bootstrap, cashout, and debit adapters decode fixed-stride
 calldata input directly; the other three
-decode memory-backed pipeline state. All avoid an external self-call. Pass the
-step value into each adapter. Bootstrap is pipeline-local rather than an
+decode memory-backed pipeline state. All return `handled = true` and avoid an
+external self-call. The host's `execute` hook must authorize a command before
+returning true. Returning `handled = false` delegates a local command to its
+trusted normal external entrypoint. Pass the step value into each adapter.
+Bootstrap is pipeline-local rather than an
 externally callable command and may consume value for native-asset balance;
 the other five reject nonzero value because those commands are non-funded.
 

package/commands/Bootstrap.sol

@@ -52,6 +52,7 @@ abstract contract Bootstrap is CommandBase, DebitAccountHook {
     /// @param state Empty pipeline state required by the command schema.
     /// @param input BOOTSTRAP block stream.
     /// @param value Native value available to fund native-asset balances.
+    /// @return handled Always true because this helper executed the command.
     /// @return output One BALANCE block per BOOTSTRAP input.
     /// @return credit Sourced budget contributions plus unused assigned value.
     function executeBootstrap(
@@ -59,7 +60,7 @@ abstract contract Bootstrap is CommandBase, DebitAccountHook {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory output, uint credit) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (state.length != 0) revert UnexpectedState();
         if (input.length % Sizes.Bootstrap != 0) revert Blocks.InvalidBlock();
 
@@ -77,5 +78,6 @@ abstract contract Bootstrap is CommandBase, DebitAccountHook {
                 i += Sizes.Balance;
             }
         }
+        handled = true;
     }
 }

package/commands/Cashout.sol

@@ -54,14 +54,15 @@ abstract contract Cashout is CommandBase, CashoutHook, Action {
     }
 }
 
-/// @title CashoutInternal
-/// @notice Extends cashout with optimized local pipeline dispatch.
-abstract contract CashoutInternal is Cashout {
+/// @title ExecuteCashout
+/// @notice Extends cashout with optimized local pipeline execution.
+abstract contract ExecuteCashout is Cashout {
     /// @notice Execute cashout directly against a calldata CASHOUT stream.
     /// @param account Account whose native asset is withdrawn.
     /// @param state Empty pipeline state required by the command schema.
     /// @param input CASHOUT block stream.
     /// @param value Native value assigned to this command; must be zero.
+    /// @return handled Always true because this helper executed the command.
     /// @return output Empty output state.
     /// @return credit Zero native budget credit.
     function executeCashout(
@@ -69,7 +70,7 @@ abstract contract CashoutInternal is Cashout {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory, uint) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert UnexpectedState();
         if (input.length % Sizes.Cashout != 0) revert Blocks.InvalidBlock();
@@ -81,6 +82,6 @@ abstract contract CashoutInternal is Cashout {
                 abs += Sizes.Cashout;
             }
         }
-        return ("", 0);
+        return (true, "", 0);
     }
 }

package/commands/Credit.sol

@@ -43,16 +43,17 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     }
 }
 
-/// @title CreditAccountInternal
-/// @notice Extends the advertised credit-account command with memory-state pipeline dispatch.
+/// @title ExecuteCreditAccount
+/// @notice Extends the advertised credit-account command with memory-state pipeline execution.
 /// @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 CreditAccountInternal is CreditAccount {
+abstract contract ExecuteCreditAccount 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.
     /// @param input Empty input required by the command schema.
     /// @param value Native value assigned to the command; must be zero.
+    /// @return handled Always true because this helper executed the command.
     /// @return output Empty output state.
     /// @return credit Zero native budget credit.
     function executeCreditAccount(
@@ -60,7 +61,7 @@ abstract contract CreditAccountInternal is CreditAccount {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory, uint) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
@@ -74,6 +75,6 @@ abstract contract CreditAccountInternal is CreditAccount {
             }
         }
 
-        return ("", 0);
+        return (true, "", 0);
     }
 }

package/commands/Debit.sol

@@ -46,16 +46,17 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     }
 }
 
-/// @title DebitAccountInternal
-/// @notice Extends the advertised debit-account command with optimized pipeline dispatch.
+/// @title ExecuteDebitAccount
+/// @notice Extends the advertised debit-account command with optimized pipeline execution.
 /// @dev This adapter is not a separate command. It uses the command ID and account hook
 /// inherited from `DebitAccount` while decoding its fixed-stride input directly from calldata.
-abstract contract DebitAccountInternal is DebitAccount {
+abstract contract ExecuteDebitAccount 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.
     /// @param input AMOUNT block stream.
     /// @param value Native value assigned to the command; must be zero.
+    /// @return handled Always true because this helper executed the command.
     /// @return output BALANCE block stream matching the debited amounts.
     /// @return credit Zero native budget credit.
     function executeDebitAccount(
@@ -63,14 +64,14 @@ abstract contract DebitAccountInternal is DebitAccount {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory, uint) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (value != 0) revert ValueNotAllowed();
         if (state.length != 0) revert UnexpectedState();
         if (input.length == 0) revert Blocks.EmptyRun();
         if (input.length % Sizes.Amount != 0) revert Blocks.InvalidBlock();
 
         (uint abs, uint end) = Cursors.bounds(input);
-        bytes memory output = new bytes(input.length);
+        output = new bytes(input.length);
         uint i;
 
         while (abs < end) {
@@ -83,6 +84,6 @@ abstract contract DebitAccountInternal is DebitAccount {
             }
         }
 
-        return (output, 0);
+        return (true, output, 0);
     }
 }

package/commands/Repay.sol

@@ -146,16 +146,17 @@ abstract contract RepayPositionPayable is CommandBase, RepayPayableHook, Action
     }
 }
 
-/// @title RepayInternal
-/// @notice Extends the advertised repay command with memory-state pipeline dispatch.
+/// @title ExecuteRepay
+/// @notice Extends the advertised repay command with memory-state pipeline execution.
 /// @dev This adapter is not a separate command. It uses the command ID and repayment hook
 /// inherited from `Repay` while accepting the state location used by `Pipeline`.
-abstract contract RepayInternal is Repay {
+abstract contract ExecuteRepay is Repay {
     /// @notice Execute the inherited repay command from an internal pipeline.
     /// @param account Account whose liabilities are repaid.
     /// @param state DEBT block stream held in pipeline memory.
     /// @param input Empty input required by the command schema.
     /// @param value Native value assigned to the command; must be zero.
+    /// @return handled Always true because this helper executed the command.
     /// @return output Empty output state.
     /// @return credit Zero native budget credit.
     function executeRepay(
@@ -163,7 +164,7 @@ abstract contract RepayInternal is Repay {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory, uint) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
@@ -177,6 +178,6 @@ abstract contract RepayInternal is Repay {
             }
         }
 
-        return ("", 0);
+        return (true, "", 0);
     }
 }

package/commands/Settle.sol

@@ -93,16 +93,17 @@ abstract contract SettlePayable is CommandBase, SettlePayableHook, Action {
     }
 }
 
-/// @title SettleInternal
-/// @notice Extends the advertised settle command with memory-state pipeline dispatch.
+/// @title ExecuteSettle
+/// @notice Extends the advertised settle command with memory-state pipeline execution.
 /// @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 SettleInternal is Settle {
+abstract contract ExecuteSettle 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.
     /// @param input Empty input required by the command schema.
     /// @param value Native value assigned to the command; must be zero.
+    /// @return handled Always true because this helper executed the command.
     /// @return output Empty output state.
     /// @return credit Zero native budget credit.
     function executeSettle(
@@ -110,7 +111,7 @@ abstract contract SettleInternal is Settle {
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal returns (bytes memory, uint) {
+    ) internal returns (bool handled, bytes memory output, uint credit) {
         if (value != 0) revert ValueNotAllowed();
         if (input.length != 0) revert UnexpectedInput();
         if (state.length == 0) revert Blocks.EmptyRun();
@@ -124,6 +125,6 @@ abstract contract SettleInternal is Settle {
             }
         }
 
-        return ("", 0);
+        return (true, "", 0);
     }
 }

package/core/Pipeline.sol

@@ -21,15 +21,17 @@ abstract contract PipeHook {
 
 /// @notice Hook implemented by pipeline hosts that execute host-local commands.
 abstract contract ExecuteHook {
-    /// @notice Execute one command whose node ID targets the current host.
-    /// @dev Implementations must revert for unsupported local command IDs.
+    /// @notice Try to execute one command whose node ID targets the current host.
+    /// @dev Implementations returning `handled = true` are responsible for
+    /// authorizing the command. Return false without side effects to delegate to
+    /// the trusted normal external entrypoint. Implementations may revert instead.
     function execute(
         uint cmd,
         bytes32 account,
         bytes memory state,
         bytes calldata input,
         uint value
-    ) internal virtual returns (bytes memory output, uint credit);
+    ) internal virtual returns (bool handled, bytes memory output, uint credit);
 }
 
 /// @title Pipeline
@@ -43,7 +45,11 @@ abstract contract Pipeline is TrustAccess, PipeHook, ExecuteHook {
         uint value
     ) private returns (bytes memory output, uint credit) {
         (bytes4 selector, address target) = unpackCommand(cmd);
-        if (target == address(this)) return execute(cmd, account, state, input, value);
+        if (target == address(this)) {
+            bool handled;
+            (handled, output, credit) = execute(cmd, account, state, input, value);
+            if (handled) return (output, credit);
+        }
         ensureTrusted(cmd);
         return rawCommandCall(selector, target, value, account, state, input);
     }

package/package.json

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