Merge pull request #100 from curvefi/killable

AlbertoCentonze · web-flow · commit 306c430b0106 · 2025-12-09T16:19:54.000+01:00
docs: contracts sunsetting procedure
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -25,11 +25,21 @@ repos:
     rev: v0.1.9
     hooks:
       - id: natrix
-        args: [lint, curve_stablecoin/lending/, curve_stablecoin/Controller.vy, curve_stablecoin/constants.vy, curve_stablecoin/ControllerView.vy, curve_stablecoin/MintController.vy, -d, NTX1, NTX4, NTX5, NTX2, NTX9, NTX10]
+        args: [lint, curve_stablecoin/lending/, curve_stablecoin/controller.vy, curve_stablecoin/constants.vy, curve_stablecoin/ControllerView.vy, curve_stablecoin/MintController.vy, -d, NTX1, NTX4, NTX5, NTX2, NTX9, NTX10]
 
   - repo: https://github.com/benber86/mamushi
     rev: v0.0.9
     hooks:
       - id: mamushi
         args: [--line-length=100]
         files: ^(curve_stablecoin/lending/LendingFactory\.vy|curve_stablecoin/zaps/CreateFromPool\.vy)$ # TODO slowly increase natrix coverage
+
+  - repo: local
+    hooks:
+      - id: check-kill-docs
+        name: Check @custom:kill in Vyper devdoc
+        entry: python scripts/check_kill_docs.py
+        language: system
+        files: \.vy$
+        exclude: ^curve_stablecoin/(testing|price_oracles|zaps)/|^curve_stablecoin/Stableswap\.vy$
+        require_serial: true
diff --git a/STYLE.md b/STYLE.md
@@ -0,0 +1,31 @@
+# Style Guide
+
+## File Naming Conventions
+
+### Vyper Files
+
+- **CamelCase** (e.g., `LendFactory.vy`, `Controller.vy`): Deployable contracts
+- **snake_case** (e.g., `blueprint_registry.vy`, `constants.vy`): Libraries and modules
+
+This naming convention determines whether a file is treated as a compilation target:
+
+| Naming | Type | Example | Requires `@custom:kill` |
+|--------|------|---------|------------------------|
+| CamelCase | Contract | `LendFactory.vy` | Yes |
+| snake_case | Library | `blueprint_registry.vy` | No |
+
+### Python Files
+
+- **snake_case** for all Python files (e.g., `constants.py`, `deployers.py`)
+
+## Contract Documentation
+
+All deployable contracts (CamelCase `.vy` files) must include a `@custom:kill` attribute in their module docstring explaining how to disable or kill the contract:
+
+```vyper
+"""
+@title My Contract
+@author Curve.fi
+@custom:kill Describe how to kill/disable this contract
+"""
+```
diff --git a/curve_stablecoin/AMM.vy b/curve_stablecoin/AMM.vy
@@ -3,6 +3,8 @@
 @title LLAMMA - crvUSD AMM
 @author Curve.Fi
 @license Copyright (c) Curve.Fi, 2020-2024 - all rights reserved
+@custom:security security@curve.fi
+@custom:kill AMM is controlled by its Controller. Kill the Controller to halt new loans and liquidations.
 """
 
 # Glossary of variables and terms
diff --git a/curve_stablecoin/ControllerView.vy b/curve_stablecoin/ControllerView.vy
@@ -7,13 +7,14 @@
 @notice This contract never requires any direct interaction as the
     main controller contract forwards all relevant calls.
 @custom:security security@curve.fi
+@custom:kill Stateless contract doesn't need to be killed.
 """
 
 from curve_stablecoin.interfaces import IAMM
 from curve_stablecoin.interfaces import IController
 from curve_std.interfaces import IERC20
 
-from curve_stablecoin import Controller as core
+from curve_stablecoin import controller as core
 import curve_stablecoin.lib.liquidation_lib as liq
 from curve_stablecoin import constants as c
 from snekmate.utils import math
diff --git a/curve_stablecoin/LMCallback.vy b/curve_stablecoin/LMCallback.vy
@@ -4,6 +4,8 @@
 @author Curve.Fi
 @license Copyright (c) Curve.Fi, 2020-2023 - all rights reserved
 @notice LM callback works like a gauge for collateral in LlamaLend/crvUSD AMMs
+@custom:security security@curve.fi
+@custom:kill Call set_killed(true) via factory admin to stop CRV emissions
 """
 
 from curve_std.interfaces import IERC20
diff --git a/curve_stablecoin/MintController.vy b/curve_stablecoin/MintController.vy
@@ -2,15 +2,18 @@
 # pragma nonreentrancy on
 # pragma optimize codesize
 """
-@title Mint Controller
+@title Llamalend Mint Market Controller
 @author Curve.Fi
 @license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
-@notice This is just a simple adapter not to have to deploy a new
+@notice Main contract to interact with a Llamalend Mint Market. Each
+    contract is specific to a single mint market.
+@dev This is just a simple adapter not to have to deploy a new
     factory for mint markets.
 @custom:security security@curve.fi
+@custom:kill Set debt_ceiling to 0 via ControllerFactory to prevent new loans. Existing loans can still be repaid/liquidated.
 """
 
-from curve_stablecoin import Controller as core
+from curve_stablecoin import controller as core
 
 initializes: core
 
diff --git a/curve_stablecoin/controller.vy b/curve_stablecoin/controller.vy
@@ -1,14 +1,6 @@
 # pragma version 0.4.3
 # pragma nonreentrancy on
 # pragma optimize codesize
-"""
-@title Llamalend Mint Market Controller
-@author Curve.Fi
-@license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
-@notice Main contract to interact with a Llamalend Mint Market. Each
-    contract is specific to a single mint market.
-@custom:security security@curve.fi
-"""
 
 from curve_stablecoin.interfaces import IAMM
 from curve_stablecoin.interfaces import IMonetaryPolicy
diff --git a/curve_stablecoin/lending/LendController.vy b/curve_stablecoin/lending/LendController.vy
@@ -6,8 +6,9 @@
 @author Curve.Fi
 @license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
 @notice Main contract to interact with a Llamalend Lend Market. Each
-    contract is specific to a single mint market.
+    contract is specific to a single lending market.
 @custom:security security@curve.fi
+@custom:kill Set borrow_cap to 0 and vault's max_supply to 0 to prevent new deposits. Existing loans can still be repaid/liquidated.
 """
 
 from curve_std.interfaces import IERC20
@@ -22,7 +23,7 @@ from curve_stablecoin.interfaces import ILendController
 
 implements: ILendController
 
-from curve_stablecoin import Controller as core
+from curve_stablecoin import controller as core
 
 from curve_stablecoin.interfaces import IControllerView as IView
 
diff --git a/curve_stablecoin/lending/LendControllerView.vy b/curve_stablecoin/lending/LendControllerView.vy
@@ -6,6 +6,8 @@
 @license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
 @notice This contract never requires any direct interaction as the
     main controller contract forwards all relevant calls.
+@custom:security security@curve.fi
+@custom:kill Stateless contract doesn't need to be killed.
 """
 
 from curve_std.interfaces import IERC20
diff --git a/curve_stablecoin/lending/LendFactory.vy b/curve_stablecoin/lending/LendFactory.vy
@@ -6,6 +6,7 @@
 @author Curve.fi
 @license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
 @custom:security security@curve.fi
+@custom:kill Set blueprints implementations to zero to halt deployments.
 """
 
 from curve_std.interfaces import IERC20
diff --git a/curve_stablecoin/lending/Vault.vy b/curve_stablecoin/lending/Vault.vy
@@ -5,6 +5,8 @@
 @notice ERC4626+ Vault for lending using LLAMMA algorithm
 @author Curve.Fi
 @license Copyright (c) Curve.Fi, 2020-2025 - all rights reserved
+@custom:security security@curve.fi
+@custom:kill Set max_supply to 0 via set_max_supply() to prevent new deposits. Existing positions can still be withdrawn.
 """
 
 from curve_std.interfaces import IERC20
diff --git a/curve_stablecoin/zaps/PartialRepayZap.vy b/curve_stablecoin/zaps/PartialRepayZap.vy
@@ -12,7 +12,7 @@
 from curve_std.interfaces import IERC20
 from curve_stablecoin.interfaces import IAMM
 from curve_stablecoin.interfaces import IController
-from curve_stablecoin import Controller as ctrl
+from curve_stablecoin import controller as ctrl
 from curve_std import token as tkn
 from curve_stablecoin.interfaces import IPartialRepayZap as IZap
 import curve_stablecoin.lib.liquidation_lib as liq
diff --git a/curve_stablecoin/zaps/PartialRepayZapCallback.vy b/curve_stablecoin/zaps/PartialRepayZapCallback.vy
@@ -11,7 +11,7 @@
 from curve_std.interfaces import IERC20
 from curve_stablecoin.interfaces import IAMM
 from curve_stablecoin.interfaces import IController
-from curve_stablecoin import Controller as ctrl
+from curve_stablecoin import controller as ctrl
 from curve_std import token as tkn
 from curve_stablecoin.interfaces import IPartialRepayZapCallback as IZap
 import curve_stablecoin.lib.liquidation_lib as liq
diff --git a/scripts/check_kill_docs.py b/scripts/check_kill_docs.py
@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Pre-commit hook to verify Vyper contracts have @custom:kill documentation."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def is_contract(filepath: str) -> bool:
+    """
+    Determine if a file is a deployable contract based on naming convention.
+
+    CamelCase filenames are contracts and need @custom:kill.
+    snake_case filenames are libraries and are skipped.
+    """
+    filename = Path(filepath).stem
+    # A file is a contract if its first character is uppercase (CamelCase)
+    return filename[0].isupper()
+
+
+def check_file(filepath: str) -> bool:
+    """Check if a Vyper file has @custom:kill in its devdoc."""
+    try:
+        result = subprocess.run(
+            ["vyper", "-f", "devdoc", filepath],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            # Compilation failed, skip this file
+            return True
+
+        devdoc = json.loads(result.stdout)
+        return "custom:kill" in devdoc
+
+    except (json.JSONDecodeError, FileNotFoundError):
+        return True
+
+
+def main() -> int:
+    failed_files = []
+
+    for filepath in sys.argv[1:]:
+        if is_contract(filepath) and not check_file(filepath):
+            failed_files.append(filepath)
+
+    if failed_files:
+        print("Missing @custom:kill documentation in:")
+        for f in failed_files:
+            print(f"  - {f}")
+        print("\nAdd a '@custom:kill' attribute explaining how to kill the contract.")
+        print("See STYLE.md for naming conventions.")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tests/leverage/v2/conftest.py b/tests/leverage/v2/conftest.py
@@ -50,7 +50,7 @@ def alice(collateral_info):
 
 @pytest.fixture(scope="session")
 def controller_interface():
-    return boa.load_partial("curve_stablecoin/Controller.vy")
+    return boa.load_partial("curve_stablecoin/controller.vy")
 
 
 @pytest.fixture()
diff --git a/tests/utils/deployers.py b/tests/utils/deployers.py
@@ -40,7 +40,7 @@
     BASE_CONTRACT_PATH + "AMM.vy", compiler_args=compiler_args_default
 )
 CONTROLLER_DEPLOYER = boa.load_partial(
-    BASE_CONTRACT_PATH + "Controller.vy", compiler_args=compiler_args_codesize
+    BASE_CONTRACT_PATH + "controller.vy", compiler_args=compiler_args_codesize
 )
 CONTROLLER_VIEW_DEPLOYER = boa.load_partial(
     BASE_CONTRACT_PATH + "ControllerView.vy", compiler_args=compiler_args_codesize
