@rootzero/contracts 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.18.0
+
+### Added
+
+- Added the non-funded `repay` and funded `repayPayable` commands. Both consume
+  `Position` state, settle only its liability side, and return the released
+  asset side as `Balance` state.
+- Added the reusable non-funded `RepayHook` settlement primitive and the
+  execution-funded `RepayPayableHook`.
+- Added the opt-in `RevokeAsset` guardian endpoint, which accepts `Asset`
+  entries and denies each asset through the existing `DenyAssetsHook`.
+
+### Changed
+
+- `Settlement.settle` now delegates its liability leg to the virtual `repay`
+  primitive. The default behavior remains a nonzero `debitAccount` call, while
+  derived settlement implementations can customize repayment in one place.
+- Exported the repayment commands and hooks and the asset-revocation guard from
+  their corresponding public barrels.
+
+### Upgrade Compatibility
+
+- Hosts inheriting `Settlement` retain the previous default settlement
+  behavior. Hosts that already declare an internal
+  `repay(bytes32,bytes32,uint)` function may need to mark it as an override or
+  rename it when upgrading.
+
 ## 1.17.0
 
 ### Breaking Changes

package/Core.sol

@@ -16,7 +16,7 @@ import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./
 import { EndpointBase, InputEndpointBase } from "./core/Endpoint.sol";
 import { Pipeline } from "./core/Pipeline.sol";
 import { Budget, Budgets } from "./execution/Budget.sol";
-import { CreditAccountHook, DebitAccountHook, PostHook, SettleHook, Settlement } from "./core/Settlement.sol";
+import { CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
 import { AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";

package/Endpoints.sol

@@ -5,7 +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 { CreditAccountHook, DebitAccountHook, PostHook, SettleHook } from "./core/Settlement.sol";
+import { CreditAccountHook, DebitAccountHook, PostHook, RepayHook, SettleHook } from "./core/Settlement.sol";
 
 // Commands
 import { CommandBase } from "./commands/Base.sol";
@@ -17,8 +17,14 @@ import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./comm
 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 { InternalSettle, Settle, SettlePayable, SettlePayableHook } from "./commands/Settle.sol";
+import {
+    InternalSettle,
+    Settle,
+    SettlePayable,
+    SettlePayableHook
+} from "./commands/Settle.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
@@ -47,7 +53,7 @@ import { PortPost } from "./ports/Post.sol";
 
 // Guard endpoints
 import { GuardBase } from "./guards/Base.sol";
-import { Revoke, RevokeAllowance } from "./guards/Revoke.sol";
+import { Revoke, RevokeAllowance, RevokeAsset } from "./guards/Revoke.sol";
 
 // Query endpoints
 import { QueryBase } from "./queries/Base.sol";

package/commands/Repay.sol

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Execution, Executions, CommandBase, Lanes, Specs} from "./Base.sol";
+import {RepayHook} from "../core/Settlement.sol";
+import {Action} from "../annotations/Action.sol";
+import {Actions} from "../utils/Actions.sol";
+
+using Executions for Execution;
+
+/// @notice Hook implemented by hosts that repay position liabilities using native value.
+abstract contract RepayPayableHook {
+    /// @notice Override to repay one liability for `account` with a shared value budget.
+    /// @param account Account whose liability is being repaid.
+    /// @param liability Identifier for the liability side.
+    /// @param debt Quantity on the liability side.
+    /// @param funds Mutable execution used only for its remaining native-value budget.
+    function repay(bytes32 account, bytes32 liability, uint debt, Execution memory funds) internal virtual;
+}
+
+/// @title Repay
+/// @notice Command that repays POSITION liabilities and returns their assets as BALANCE state.
+abstract contract Repay is CommandBase, RepayHook, Action {
+    uint private immutable descriptor;
+
+    constructor() {
+        uint id;
+        (id, descriptor) = command("repay", Specs.Position, Specs.Empty, Specs.Balance, 0, false, false);
+        action(id, Actions.Settle);
+    }
+
+    /// @notice Repay each POSITION liability and return its asset as BALANCE state.
+    /// @param state POSITION block stream.
+    /// @return BALANCE output state containing each released asset side.
+    /// @return Empty transaction stream.
+    function repay(
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
+    ) external onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
+            repay(account, liability, debt);
+            exec.outputBalance(asset, amount);
+        }
+
+        return close(exec, account);
+    }
+}
+
+/// @title RepayPayable
+/// @notice Funded command that repays POSITION liabilities and returns their assets as BALANCE state.
+abstract contract RepayPayable is CommandBase, RepayPayableHook, Action {
+    uint private immutable descriptor;
+
+    constructor() {
+        uint id;
+        (id, descriptor) = command("repayPayable", Specs.Position, Specs.Empty, Specs.Balance, 0, true, false);
+        action(id, Actions.Settle);
+    }
+
+    /// @notice Repay each POSITION liability and return its asset as BALANCE state.
+    /// @param state POSITION block 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
+    ) external payable onlyCommand returns (bytes memory, bytes memory) {
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+
+        while (exec.more()) {
+            (bytes32 asset, uint amount, bytes32 liability, uint debt) = exec.unpackPosition(Lanes.State);
+            repay(account, liability, debt, exec);
+            exec.outputBalance(asset, amount);
+        }
+
+        return close(exec, account);
+    }
+}

package/core/Settlement.sol

@@ -28,22 +28,23 @@ abstract contract PostHook {
     function post(bytes32 from, bytes32 to, bytes32 asset, uint amount) internal virtual;
 }
 
+/// @title RepayHook
+/// @notice Hook for repaying one account liability.
+abstract contract RepayHook {
+    /// @notice Override to repay `debt` denominated in `liability` for `account`.
+    function repay(bytes32 account, bytes32 liability, uint debt) internal virtual;
+}
+
 /// @title SettleHook
 /// @notice Hook for settling one asset-liability position.
 abstract contract SettleHook {
     /// @notice Override to settle one position for `account`.
-    function settle(
-        bytes32 account,
-        bytes32 asset,
-        uint amount,
-        bytes32 liability,
-        uint debt
-    ) internal virtual;
+    function settle(bytes32 account, bytes32 asset, uint amount, bytes32 liability, uint debt) internal virtual;
 }
 
 /// @title Settlement
 /// @notice Default account-hook implementation for transaction posting and position settlement.
-abstract contract Settlement is PostHook, SettleHook, DebitAccountHook, CreditAccountHook {
+abstract contract Settlement is PostHook, SettleHook, RepayHook, DebitAccountHook, CreditAccountHook {
     /// @notice Post one transaction by debiting its source and crediting its destination.
     /// Returns without calling either hook when `amount` is zero and skips either
     /// operation when the corresponding account is zero.
@@ -53,6 +54,12 @@ abstract contract Settlement is PostHook, SettleHook, DebitAccountHook, CreditAc
         if (to != 0) creditAccount(to, asset, amount);
     }
 
+    /// @notice Repay one liability by debiting it from the account.
+    /// Skips the debit when `debt` is zero.
+    function repay(bytes32 account, bytes32 liability, uint debt) internal virtual override {
+        if (debt != 0) debitAccount(account, liability, debt);
+    }
+
     /// @notice Settle one position by crediting its asset and debiting its liability.
     /// Skips either operation when its corresponding amount is zero.
     function settle(

package/guards/Revoke.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.33;
 
 import {AllowanceHook} from "../commands/admin/Allowance.sol";
+import {DenyAssetsHook} from "../commands/admin/DenyAssets.sol";
 import {GuardBase} from "./Base.sol";
 import {Specs} from "../Codec.sol";
 import {Execution, Executions, Lanes} from "../execution/Execution.sol";
@@ -49,3 +50,24 @@ abstract contract RevokeAllowance is GuardBase, AllowanceHook {
         }
     }
 }
+
+/// @title RevokeAsset
+/// @notice Guardian action that denies assets through the host's existing asset hook.
+/// @dev Opt-in guard. Hosts expose it by inheriting this contract and implementing DenyAssetsHook.
+abstract contract RevokeAsset is GuardBase, DenyAssetsHook {
+    uint private immutable descriptor;
+
+    constructor() {
+        (, descriptor) = guard("revokeAsset", Specs.Asset);
+    }
+
+    /// @notice Deny every ASSET block in `input` as the active guardian.
+    function revokeAsset(bytes calldata input) external onlyGuardian {
+        Execution memory exec = openInput(input, descriptor, 0);
+
+        while (exec.more()) {
+            bytes32 asset = exec.unpackAsset(Lanes.Input);
+            denyAsset(asset);
+        }
+    }
+}

package/package.json

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