feat: coin issuer uses percentage of total supply (#17738)

# Redesign CoinIssuer to use annual percentage-based minting budgets

This PR redesigns the CoinIssuer contract to implement a more
sophisticated token issuance model:

- Replaces the continuous rate-based minting with a discrete annual
budget system
- Budgets are calculated as a percentage of total supply at the start of
each year
- Implements a "use-it-or-lose-it" model where unused budget is lost
when crossing year boundaries
- Enables proper compounding as each year's budget is based on the
actual supply at that time
- Sets a hard cap of 20% annual inflation in the deployment script

The implementation includes:
- New state variables to track current year, budget, and cumulative
minted amount
- Logic to handle year boundary transitions and budget recalculation
- Comprehensive test coverage for various scenarios including partial
minting, year transitions, and skipping years

This approach provides more predictable token issuance with clear annual
caps while still allowing flexibility in the actual minting schedule
within each year.

Author: LHerskind

cspell.json

@@ -189,6 +189,7 @@
     "merkleizing",
     "messagebox",
     "mimc",
+    "mintable",
     "mktemp",
     "mload",
     "mockify",

l1-contracts/src/governance/CoinIssuer.sol

@@ -11,44 +11,120 @@ import {Ownable2Step} from "@oz/access/Ownable2Step.sol";
 /**
  * @title CoinIssuer
  * @author Aztec Labs
- * @notice A contract that allows minting of coins at a maximum fixed rate
+ * @notice A contract that allows minting of coins at a maximum percentage rate per year using discrete annual budgets
+ *
+ * This contract uses a discrete annual budget model:
+ * - Years are fixed periods from deployment:
+ *   - year 0 = [deployment, deployment + 365d)
+ *   - year 1 = [deployment + 365d, deployment + (2) * 365d)
+ *   - ...
+ *   - year n = [deployment + 365d * n, deployment + (n + 1) * 365d)
+ * - Each year's budget is calculated at the start of that year based on the actual supply at that moment
+ * - Budget = totalSupply() × NOMINAL_ANNUAL_PERCENTAGE_CAP / 1e18
+ * - Unused budget from year N is LOST when year N+1 begins (use-it-or-lose-it)
+ *
+ * Rate semantics: If the full budget is minted every year, the effective annual inflation rate equals
+ * NOMINAL_ANNUAL_PERCENTAGE_CAP. For example, setting the rate to 0.10e18 (10%) and fully minting each
+ * year will result in supply growing by exactly 10% annually: supply(year N) = supply(year 0) × (1.10)^N
+ *
+ * Partial minting: If less than the full budget is minted in year N, the remaining allowance is lost
+ * at the year N→N+1 boundary. Year N+1's budget is calculated based on the actual supply at the start
+ * of year N+1, which reflects only what was actually minted.
+ *
+ * @dev The NOMINAL_ANNUAL_PERCENTAGE_CAP is in e18 precision where 1e18 = 100%
+ *
+ * @dev The token MUST have a non-zero initial supply at deployment, or an alternative way to mint the token.
  */
 contract CoinIssuer is ICoinIssuer, Ownable {
   IMintableERC20 public immutable ASSET;
-  uint256 public immutable RATE;
-  uint256 public timeOfLastMint;
+  uint256 public immutable NOMINAL_ANNUAL_PERCENTAGE_CAP;
+  uint256 public immutable DEPLOYMENT_TIME;
 
-  constructor(IMintableERC20 _asset, uint256 _rate, address _owner) Ownable(_owner) {
+  // Note that the state variables below are "cached":
+  // they are only updated when minting after a year boundary.
+  uint256 public cachedBudgetYear;
+  uint256 public cachedBudget;
+
+  constructor(IMintableERC20 _asset, uint256 _annualPercentage, address _owner) Ownable(_owner) {
     ASSET = _asset;
-    RATE = _rate;
-    timeOfLastMint = block.timestamp;
+    NOMINAL_ANNUAL_PERCENTAGE_CAP = _annualPercentage;
+    DEPLOYMENT_TIME = block.timestamp;
+
+    cachedBudgetYear = 0;
+    cachedBudget = _getNewBudget();
+
+    emit BudgetReset(0, cachedBudget);
   }
 
   function acceptTokenOwnership() external override(ICoinIssuer) onlyOwner {
     Ownable2Step(address(ASSET)).acceptOwnership();
   }
 
   /**
-   * @notice  Mint tokens up to the `mintAvailable` limit
-   *          Beware that the mintAvailable will be reset to 0, and not just
-   *          reduced by the amount minted.
+   * @notice  Mint `_amount` tokens to `_to`
+   *
+   * @dev     The `_amount` must be within the `cachedBudget`
    *
    * @param _to - The address to receive the funds
    * @param _amount - The amount to mint
    */
   function mint(address _to, uint256 _amount) external override(ICoinIssuer) onlyOwner {
-    uint256 maxMint = mintAvailable();
-    require(_amount <= maxMint, Errors.CoinIssuer__InsufficientMintAvailable(maxMint, _amount));
-    timeOfLastMint = block.timestamp;
+    // Update state if we've crossed into a new year (will reset budget and forfeit unused amount)
+    _updateBudgetIfNeeded();
+
+    require(_amount <= cachedBudget, Errors.CoinIssuer__InsufficientMintAvailable(cachedBudget, _amount));
+    cachedBudget -= _amount;
+
     ASSET.mint(_to, _amount);
   }
 
   /**
-   * @notice  The amount of funds that is available for "minting"
+   * @notice  The amount of funds that is available for "minting" in the current year
+   *          If we've crossed into a new year since the last mint, returns the fresh budget
+   *          for the new year based on current supply.
    *
    * @return The amount mintable
    */
   function mintAvailable() public view override(ICoinIssuer) returns (uint256) {
-    return RATE * (block.timestamp - timeOfLastMint);
+    uint256 currentYear = _yearSinceGenesis();
+
+    // Until the budget is stale, return the cached budget
+    if (cachedBudgetYear >= currentYear) {
+      return cachedBudget;
+    }
+
+    // Crossed into new year(s): compute fresh budget
+    return _getNewBudget();
+  }
+
+  /**
+   * @notice  Internal function to update year and budget when crossing year boundaries
+   *
+   * @dev     If multiple years have passed without minting, jumps directly to current year
+   *          and all intermediate years' budgets are lost
+   */
+  function _updateBudgetIfNeeded() private {
+    uint256 currentYear = _yearSinceGenesis();
+    // If the budget is for the past, update the budget.
+    if (cachedBudgetYear < currentYear) {
+      cachedBudgetYear = currentYear;
+      cachedBudget = _getNewBudget();
+
+      emit BudgetReset(currentYear, cachedBudget);
+    }
+  }
+
+  /**
+   * @notice  Internal function to compute the current year since genesis
+   */
+  function _yearSinceGenesis() private view returns (uint256) {
+    return (block.timestamp - DEPLOYMENT_TIME) / 365 days;
+  }
+
+  /**
+   * @notice  Internal function to compute a fresh budget
+   */
+  function _getNewBudget() private view returns (uint256) {
+    return ASSET.totalSupply() * NOMINAL_ANNUAL_PERCENTAGE_CAP / 1e18;
   }
 }

l1-contracts/src/governance/interfaces/ICoinIssuer.sol

@@ -3,6 +3,8 @@
 pragma solidity >=0.8.27;
 
 interface ICoinIssuer {
+  event BudgetReset(uint256 indexed newYear, uint256 newBudget);
+
   function mint(address _to, uint256 _amount) external;
   function acceptTokenOwnership() external;
   function mintAvailable() external view returns (uint256);

l1-contracts/test/DateGatedRelayer.t.sol

@@ -35,7 +35,8 @@ contract DateGatedRelayerTest is Test {
     uint256 gatedUntil = bound(_gatedUntil, block.timestamp + 1, type(uint32).max);
 
     TestERC20 testERC20 = new TestERC20("test", "TEST", address(this));
-    CoinIssuer coinIssuer = new CoinIssuer(testERC20, 100, address(this));
+    testERC20.mint(address(this), 1e18);
+    CoinIssuer coinIssuer = new CoinIssuer(testERC20, 100e18, address(this));
     testERC20.transferOwnership(address(coinIssuer));
     coinIssuer.acceptTokenOwnership();
 
@@ -45,11 +46,15 @@ contract DateGatedRelayerTest is Test {
     uint256 warp = bound(_warp, gatedUntil, type(uint32).max);
 
     vm.expectRevert();
-    coinIssuer.mint(address(this), 100);
+    coinIssuer.mint(address(this), 1);
 
     vm.warp(warp);
-    dateGatedRelayer.relay(address(coinIssuer), abi.encodeWithSelector(CoinIssuer.mint.selector, address(this), 100));
+    uint256 mintAvailable = coinIssuer.mintAvailable();
+    dateGatedRelayer.relay(
+      address(coinIssuer), abi.encodeWithSelector(CoinIssuer.mint.selector, address(this), mintAvailable)
+    );
 
-    assertEq(testERC20.balanceOf(address(this)), 100);
+    assertEq(testERC20.balanceOf(address(this)), mintAvailable + 1e18, "balanceOf");
+    assertEq(testERC20.totalSupply(), mintAvailable + 1e18, "totalSupply");
   }
 }

l1-contracts/test/governance/coin-issuer/Base.t.sol

@@ -13,9 +13,10 @@ contract CoinIssuerBase is Test {
 
   CoinIssuer internal nom;
 
-  function _deploy(uint256 _rate) internal {
+  function _deploy(uint256 _rate, uint256 _initialSupply) internal {
     TestERC20 testERC20 = new TestERC20("test", "TEST", address(this));
     token = IMintableERC20(address(testERC20));
+    token.mint(address(this), _initialSupply);
     nom = new CoinIssuer(token, _rate, address(this));
     testERC20.transferOwnership(address(nom));
     nom.acceptTokenOwnership();

l1-contracts/test/governance/coin-issuer/acceptTokenOwnership.t.sol

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity >=0.8.27;
+
+import {Ownable} from "@oz/access/Ownable.sol";
+import {Ownable2Step} from "@oz/access/Ownable2Step.sol";
+import {CoinIssuerBase} from "./Base.t.sol";
+import {TestERC20} from "@aztec/mock/TestERC20.sol";
+import {IMintableERC20} from "@aztec/shared/interfaces/IMintableERC20.sol";
+import {CoinIssuer} from "@aztec/governance/CoinIssuer.sol";
+
+contract AcceptTokenOwnershipTest is CoinIssuerBase {
+  function setUp() public {
+    _deploy(1e18, 1_000_000);
+  }
+
+  function test_GivenCallerIsNotOwner(address _caller) external {
+    // it reverts
+    vm.assume(_caller != address(this));
+    vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, _caller));
+    vm.prank(_caller);
+    nom.acceptTokenOwnership();
+  }
+
+  function test_GivenCallerIsOwnerButNoOwnershipTransferPending() external {
+    // it reverts because ownership was already accepted in Base setup
+    // Attempting to accept again should fail
+    vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, address(nom)));
+    nom.acceptTokenOwnership();
+  }
+
+  function test_GivenCallerIsOwnerAndOwnershipTransferPending() external {
+    // it successfully accepts ownership of the token
+    // We need to test the flow from a fresh deployment where ownership hasn't been accepted
+
+    // Create token and CoinIssuer but don't call acceptTokenOwnership
+    TestERC20 testERC20 = new TestERC20("test", "TEST", address(this));
+    IMintableERC20 newToken = IMintableERC20(address(testERC20));
+    newToken.mint(address(this), 1_000_000);
+    CoinIssuer newNom = new CoinIssuer(newToken, 1e18, address(this));
+
+    // Transfer ownership but don't accept yet
+    testERC20.transferOwnership(address(newNom));
+
+    // Verify pendingOwner is set but owner hasn't changed
+    assertEq(Ownable(address(newToken)).owner(), address(this));
+    assertEq(Ownable2Step(address(newToken)).pendingOwner(), address(newNom));
+
+    // Accept ownership through CoinIssuer
+    newNom.acceptTokenOwnership();
+
+    // Verify ownership was transferred
+    assertEq(Ownable(address(newToken)).owner(), address(newNom));
+    assertEq(Ownable2Step(address(newToken)).pendingOwner(), address(0));
+  }
+
+  function test_GivenMultipleAcceptanceAttempts() external {
+    // it should fail on second attempt since ownership already accepted
+    // Create token and CoinIssuer
+    TestERC20 testERC20 = new TestERC20("test", "TEST", address(this));
+    IMintableERC20 newToken = IMintableERC20(address(testERC20));
+    newToken.mint(address(this), 1_000_000);
+    CoinIssuer newNom = new CoinIssuer(newToken, 1e18, address(this));
+
+    // Transfer ownership
+    testERC20.transferOwnership(address(newNom));
+
+    // First acceptance should succeed
+    newNom.acceptTokenOwnership();
+    assertEq(Ownable(address(newToken)).owner(), address(newNom));
+
+    // Second acceptance should fail (no pending ownership)
+    vm.expectRevert(abi.encodeWithSelector(Ownable.OwnableUnauthorizedAccount.selector, address(newNom)));
+    newNom.acceptTokenOwnership();
+  }
+}

l1-contracts/test/governance/coin-issuer/acceptTokenOwnership.tree

@@ -0,0 +1,11 @@
+AcceptTokenOwnershipTest
+├── given caller is not owner
+│   └── it reverts
+├── given caller is owner but no ownership transfer pending
+│   └── it reverts because ownership was already accepted
+├── given caller is owner and ownership transfer pending
+│   ├── it successfully accepts ownership of the token
+│   ├── it updates the token owner to the CoinIssuer
+│   └── it clears the pendingOwner
+└── given multiple acceptance attempts
+    └── it should fail on second attempt since ownership already accepted