@rootzero/contracts 1.21.0 → 1.23.0

package/commands/Allocate.sol

@@ -28,23 +28,20 @@ abstract contract Allocate is CommandBase, AllocateHook {
     }
 
     /// @notice Allocate BALANCE state blocks to matching NODE input blocks.
-    /// @param state BALANCE block stream.
-    /// @param input Matching NODE block stream.
+    /// @param context Command context carrying BALANCE state and matching NODE input.
     /// @return CUSTODY block stream matching the allocated balances.
     /// @return Empty transaction stream.
     function allocate(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             HostAmount memory custody = exec.unpackBalanceForHost(Lanes.State, exec.unpackNode(Lanes.Input));
-            allocate(account, custody);
+            allocate(exec.account, custody);
             exec.outputCustody(custody);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Base.sol

@@ -70,40 +70,56 @@ abstract contract CommandBase is CallerAccess, EndpointBase, ReceivedEvent {
         published = endpoint(id, name, descriptor);
     }
 
-    /// @notice Open and validate both command lanes, including lanes declared EMPTY.
+    /// @notice Decode the command ABI argument as exactly one complete CONTEXT block.
+    /// @dev Rejects empty input, trailing bytes, and additional context blocks.
+    function unpackCommandContext(
+        bytes calldata context
+    ) internal pure returns (bytes32 account, bytes calldata state, bytes calldata input) {
+        uint abs;
+        assembly ("memory-safe") {
+            abs := context.offset
+        }
+
+        uint end;
+        (account, state, input, end) = Blocks.unpackContext(abs);
+        if (end != abs + context.length) revert Blocks.InvalidBlock();
+    }
+
+    /// @notice Decode one command context and validate both lanes, including lanes declared EMPTY.
     /// Batches are derived from the input and state lanes. A non-empty stream for
     /// a lane whose descriptor has zero stride reverts instead of being ignored.
     /// Commands must account for the complete validated state by consuming it,
     /// transforming and returning it, forwarding it intact, or reverting.
-    /// @param state Current command state block stream.
-    /// @param input Command input block stream.
+    /// @param context Exactly one CONTEXT block carrying the account, state, and input.
     /// @param descriptor Packed command endpoint descriptor.
     /// @param batches Required batch count, or zero to reconcile the lane counts.
     /// @return exec Execution with its output buffer metadata initialized for the reconciled batch count.
     function openCommand(
-        bytes calldata state,
-        bytes calldata input,
+        bytes calldata context,
         uint descriptor,
         uint batches
     ) internal view returns (Execution memory exec) {
-        return Executions.open(state, input, descriptor, batches);
+        bytes32 account;
+        bytes calldata state;
+        bytes calldata input;
+        (account, state, input) = unpackCommandContext(context);
+        exec = Executions.open(state, input, descriptor, batches);
+        exec.account = account;
     }
 
-    /// @notice Close a command execution and refund unspent value to `account`.
+    /// @notice Close a command execution and refund unspent value to its account.
     /// @param exec Command execution to close.
-    /// @param account Account that should receive any unspent value.
     /// @return output Final encoded output block stream.
     /// @return transactions Final encoded transaction block stream.
-    function close(
-        Execution memory exec,
-        bytes32 account
+    function closeCommand(
+        Execution memory exec
     ) internal returns (bytes memory output, bytes memory transactions) {
         if (exec.budget == 0 && Cursors.initial(exec.writers)) return ("", "");
 
         output = close(exec);
-        uint amount = exec.refundValue(account, nativeAsset);
+        uint amount = exec.refundValue(exec.account, nativeAsset);
         if (amount != 0) {
-            emit Received(account, nativeAsset, amount, Actions.Refund, 0);
+            emit Received(exec.account, nativeAsset, amount, Actions.Refund, 0);
         }
 
         transactions = exec.finishTransactions();

package/commands/Burn.sol

@@ -30,22 +30,20 @@ abstract contract Burn is CommandBase, BurnHook, Action {
     }
 
     /// @notice Burn each BALANCE block from the command state.
-    /// @param state BALANCE block stream.
+    /// @param context Command context carrying the BALANCE state stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function burn(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
-            burn(account, asset, amount);
+            burn(exec.account, asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/Credit.sol

@@ -26,22 +26,20 @@ abstract contract CreditAccount is CommandBase, CreditAccountHook {
     }
 
     /// @notice Credit each BALANCE block from the command state to the command account.
-    /// @param state BALANCE block stream.
+    /// @param context Command context carrying the BALANCE state stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function creditAccount(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
-            creditAccount(account, asset, amount);
+            creditAccount(exec.account, asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/Debit.sol

@@ -29,23 +29,21 @@ abstract contract DebitAccount is CommandBase, DebitAccountHook {
     }
 
     /// @notice Debit AMOUNT input blocks from the command account and output matching BALANCE blocks.
-    /// @param input AMOUNT block stream.
+    /// @param context Command context carrying the AMOUNT input stream.
     /// @return BALANCE block stream matching the debited amounts.
     /// @return Empty transaction stream.
     function debitAccount(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-            debitAccount(account, asset, amount);
+            debitAccount(exec.account, asset, amount);
             exec.outputBalance(asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/Deposit.sol

@@ -44,23 +44,21 @@ abstract contract Deposit is CommandBase, DepositHook, Action {
     }
 
     /// @notice Deposit AMOUNT input blocks into the command account and output matching BALANCE blocks.
-    /// @param input AMOUNT block stream.
+    /// @param context Command context carrying the AMOUNT input stream.
     /// @return BALANCE block stream matching the deposited amounts.
     /// @return Empty transaction stream.
     function deposit(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-            deposit(account, asset, amount);
+            deposit(exec.account, asset, amount);
             exec.outputBalance(asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 
@@ -77,22 +75,20 @@ abstract contract DepositPayable is CommandBase, DepositPayableHook, Action {
     }
 
     /// @notice Deposit AMOUNT input blocks with access to a mutable native-value budget.
-    /// @param input AMOUNT block stream.
+    /// @param context Command context carrying the AMOUNT input stream.
     /// @return BALANCE block stream matching the deposited amounts.
     /// @return Remaining native value as a refund transaction stream.
     function depositPayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
-            deposit(account, asset, amount, exec);
+            deposit(exec.account, asset, amount, exec);
             exec.outputBalance(asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Payout.sol

@@ -31,22 +31,19 @@ abstract contract Payout is CommandBase, PayoutHook, Action {
     }
 
     /// @notice Pay out BALANCE state blocks to matching ACCOUNT input blocks.
-    /// @param state BALANCE block stream.
-    /// @param input Matching ACCOUNT block stream.
+    /// @param context Command context carrying BALANCE state and matching ACCOUNT input.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function payout(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
-            payout(account, exec.unpackAccount(Lanes.Input), asset, amount);
+            payout(exec.account, exec.unpackAccount(Lanes.Input), asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Provision.sol

@@ -36,23 +36,21 @@ abstract contract Provision is CommandBase, ProvisionHook {
     }
 
     /// @notice Provision ALLOCATION input blocks and output matching CUSTODY state blocks.
-    /// @param input ALLOCATION block stream.
+    /// @param context Command context carrying the ALLOCATION input stream.
     /// @return CUSTODY block stream matching the provisioned allocations.
     /// @return Empty transaction stream.
     function provision(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             HostAmount memory allocation = exec.unpackAllocationValue(Lanes.Input);
-            provision(account, allocation);
+            provision(exec.account, allocation);
             exec.outputCustody(allocation);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 
@@ -68,23 +66,21 @@ abstract contract ProvisionPayable is CommandBase, ProvisionPayableHook {
     }
 
     /// @notice Provision ALLOCATION input blocks with access to a mutable native-value budget.
-    /// @param input ALLOCATION block stream.
+    /// @param context Command context carrying the ALLOCATION input stream.
     /// @return CUSTODY block stream matching the provisioned allocations.
     /// @return Remaining native value as a refund transaction stream.
     function provisionPayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             HostAmount memory allocation = exec.unpackAllocationValue(Lanes.Input);
-            provision(account, allocation, exec);
+            provision(exec.account, allocation, exec);
             exec.outputCustody(allocation);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/Recover.sol

@@ -35,21 +35,19 @@ abstract contract RecoverPayable is CommandBase, RecoverPayableHook {
     }
 
     /// @notice Recover each recover block in the command input.
-    /// @param input RECOVER block stream.
+    /// @param context Command context carrying the RECOVER input stream.
     /// @return Empty output state.
     /// @return Remaining native value as a refund transaction stream.
     function recoverPayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (uint handler, uint resources, bytes32 key, bytes calldata witness) = exec.unpackRecover(Lanes.Input);
             recover(handler, resources, key, witness, exec);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Relay.sol

@@ -8,21 +8,20 @@ using Executions for Execution;
 /// @notice Hook implemented by hosts that relay command contexts.
 abstract contract RelayPayableHook {
     /// @notice Override to relay a command context 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 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.
+    /// @param exec Execution carrying the source state and value available for
+    /// transport fees and destination resource funding.
     function relay(
         uint portal,
         uint resources,
         bytes32 account,
-        bytes calldata state,
         bytes calldata input,
-        Execution memory funds
+        Execution memory exec
     ) internal virtual;
 }
 
@@ -37,15 +36,13 @@ abstract contract RelayPayable is CommandBase, RelayPayableHook {
 
     /// @notice Relay one RELAY input block with the command account and empty state.
     function relayPayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 1);
-        (uint portal, uint resources, bytes calldata relayInput) = exec.unpackRelay(Lanes.Input);
-        relay(portal, resources, account, state, relayInput, exec);
+        Execution memory exec = openCommand(context, descriptor, 1);
+        (uint portal, uint resources, bytes calldata input) = exec.unpackRelay(Lanes.Input);
+        relay(portal, resources, exec.account, input, exec);
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 
@@ -62,19 +59,16 @@ abstract contract RelayBalancePayable is CommandBase, RelayPayableHook {
     }
 
     /// @notice Relay one RELAY input block with the command account and current state.
-    /// @param state State forwarded into the destination context.
-    /// @param input Exactly one RELAY block.
+    /// @param context Command context carrying state and exactly one RELAY input block.
     /// @return Empty output state.
     /// @return Remaining native value as a refund transaction stream.
     function relayBalancePayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 1);
-        (uint portal, uint resources, bytes calldata relayInput) = exec.unpackRelay(Lanes.Input);
-        relay(portal, resources, account, state, relayInput, exec);
+        Execution memory exec = openCommand(context, descriptor, 1);
+        (uint portal, uint resources, bytes calldata input) = exec.unpackRelay(Lanes.Input);
+        relay(portal, resources, exec.account, input, exec);
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Repay.sol

@@ -30,23 +30,21 @@ abstract contract Repay is CommandBase, RepayHook, Action {
     }
 
     /// @notice Repay each POSITION liability and return its asset as BALANCE state.
-    /// @param state POSITION block stream.
+    /// @param context Command context carrying the POSITION state stream.
     /// @return BALANCE output state containing each released asset side.
     /// @return Empty transaction stream.
     function repay(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
-            repay(account, liability, debt);
+            repay(exec.account, liability, debt);
             exec.outputBalance(asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 
@@ -62,22 +60,20 @@ abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
     }
 
     /// @notice Repay each POSITION liability and return its asset as BALANCE state.
-    /// @param state POSITION block stream.
+    /// @param context Command context carrying the POSITION state stream.
     /// @return BALANCE output state containing each released asset side.
     /// @return Remaining native value as a refund transaction stream.
     function repayPayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
-            repay(account, liability, debt, exec);
+            repay(exec.account, liability, debt, exec);
             exec.outputBalance(asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/Settle.sol

@@ -47,22 +47,20 @@ abstract contract Settle is CommandBase, SettleHook, Action {
     }
 
     /// @notice Settle each POSITION block from the command state.
-    /// @param state POSITION block stream.
+    /// @param context Command context carrying the POSITION state stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function settle(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
-            settle(account, asset, amount, liability, debt);
+            settle(exec.account, asset, amount, liability, debt);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 
@@ -78,22 +76,20 @@ abstract contract SettlePayable is CommandBase, SettlePayableHook, Action {
     }
 
     /// @notice Settle each POSITION block with access to a shared native-value budget.
-    /// @param state POSITION block stream.
+    /// @param context Command context carrying the POSITION state stream.
     /// @return Empty output state.
     /// @return Remaining native value as a refund transaction stream.
     function settlePayable(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external payable onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
-            settle(account, asset, amount, liability, debt, exec);
+            settle(exec.account, asset, amount, liability, debt, exec);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/Withdraw.sol

@@ -30,21 +30,19 @@ abstract contract Withdraw is CommandBase, WithdrawHook, Action {
     }
 
     /// @notice Withdraw each BALANCE block from the command state to the command account.
-    /// @param state BALANCE block stream.
+    /// @param context Command context carrying the BALANCE state stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function withdraw(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
+        bytes calldata context
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        Execution memory exec = openCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (bytes32 asset, uint amount) = exec.unpackBalance(Lanes.State);
-            withdraw(account, asset, amount);
+            withdraw(exec.account, asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }

package/commands/admin/AllowAssets.sol

@@ -23,22 +23,20 @@ abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     }
 
     /// @notice Allow each ASSET block in the admin input.
-    /// @param input ASSET block stream.
+    /// @param context Admin command context carrying the ASSET input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function allowAssets(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             bytes32 asset = exec.unpackAsset(Lanes.Input);
             allowAsset(asset);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }
 

package/commands/admin/Allowance.sol

@@ -27,21 +27,19 @@ abstract contract Allowance is AdminBase, AllowanceHook {
     }
 
     /// @notice Apply each ALLOWANCE block in the admin input.
-    /// @param input ALLOWANCE block stream.
+    /// @param context Admin command context carrying the ALLOWANCE input stream.
     /// @return Empty output state.
     /// @return Empty transaction stream.
     function allowance(
-        bytes32 account,
-        bytes calldata state,
-        bytes calldata input
-    ) external onlyAdmin(account) returns (bytes memory, bytes memory) {
-        Execution memory exec = openCommand(state, input, descriptor, 0);
+        bytes calldata context
+    ) external returns (bytes memory, bytes memory) {
+        Execution memory exec = openAdminCommand(context, descriptor, 0);
 
         while (exec.more()) {
             (uint peer, bytes32 asset, uint amount) = exec.unpackAllowance(Lanes.Input);
             allowance(peer, asset, amount);
         }
 
-        return close(exec, account);
+        return closeCommand(exec);
     }
 }