Add ERC: ERC-20 totalSupply Extension

ERCS/erc-7924.md

@@ -0,0 +1,155 @@
+---
+eip: 7924
+title: ERC-20 totalSupply Extension
+description: Manage the maximum supply of ERC-20 stablecoins.
+author: YuehuaZhang (@astroyhzcc) <[email protected]>, Yuxiang Fu (@tmac4096) <[email protected]>, Yanyi Liang <[email protected]>, Hao Zou (@BruceZH0915) <[email protected]>, Siyuan Zheng (@andrewcoder666) <[email protected]>
+discussions-to: https://ethereum-magicians.org/t/a-simple-mechanism-to-manage-the-maximum-supply-of-stable-coin-compliant-with-erc-20/23244
+status: Draft
+type: Standards Track
+category: ERC
+created: 2025-03-21
+requires: 20
+---
+
+## Abstract
+
+This proposal defines a validator role for [ERC-20](./eip-20.md) compliant stablecoins and introduces the concept of maximum supply. Validators manage stablecoin collateral and calculate the maximum token supply based on collateral value. The `maxSupply` method is provided to query the current supply cap, ensuring `totalSupply`  never exceeds `maxSupply`.
+
+## Motivation
+
+Most stablecoin issuers are required to hold reserve funds or collateralized assets to back the stablecoin's value. However, existing models lack a mechanism to enforce a supply cap aligned with reserve assets. This EIP aims to:
+1. Create a new role to regulate `totalSupply`.
+2. Allow validators to update the maximum supply based on collateral value.
+3. Enable transparent supply governance, , ensuring compliance with regulatory or protocol-specific requirements.
+
+## Specification
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
+
+### Definitions
+
+The existing definitions from [ERC-7540](./eip-7540.md) apply.
+
+* `_Issuer_`: the issuer of the stable coin
+
+* `_Validator_`: the reserve fund custodians or collateral managers 
+
+### Rule
+
+1. Validator Management
++ Validator address must be publicly verifiable
++ The maximum token supply update operations should contain the statement or receipt from the Validator, for example ISO 20022 message format used for bank-to-customer intraday account reporting such as CAMT.052 statement.
++ Validator changes require governance approval
+2. Supply Enforcement
++ all mint operations must check:totalSupply() + mintAmount ≤ maxSupply()
++ Burn operations unaffected by supply cap
+3. Privilege Separation
++ Issuer manages daily mint/burn operations
++ Validator controls collateral verification
+
+### Interface
+
+```solidity
+interface StablecoinMaxSupply {
+  // @notice The event emitted when the maximum supply of token is updated successfully.
+  // @param _validator the address of validator who updates the maximum supply of token.
+  // @param _maxSupply the maximum token supply.
+  // 
+  event MaxSupplyConfigured(address indexed _validator, uint256 _maxSupply);
+
+  // @notice      This function MUST return the number of maximum suppply of the token.
+  // @return      The maximum supply of the token
+  function maxSupply() external view returns (uint256);
+
+
+  // @notice      This function MUST return the address of validator.
+  // @return      The validator address of the token
+  function validator() external view returns (address);  
+
+  // @notice      This function MUST set the maximum suppply of the token.
+  // @param _maxSupply the maximum token supply.
+  // @param data       the bank statement file. for example the CAMT052 or CAMT053.
+  function setMaxSupply(uint256 _maxSupply, bytes calldata data) external;
+}
+```
+
+## Rationale
+
+1. Validator Role: Reserve custodians or collateral managers act as validators to ensure supply aligns with asset value.
+2. Maximum supply updates: Validators must update maxSupply promptly when collateral or reserve value changes.
+
+## Backwards Compatibility
+
+This standard is fully compatible with ERC-20.
+
+
+## Reference Implementation
+
+```solidity
+contract MyStabelecoin is ERC20, StablecoinMaxSupply{
+    // the address of validator
+    address private _validator;
+
+     // the address of issuer
+    address private  _issuer;
+
+    // the maximum supply of the token
+    uint256 private _maxSupply;
+
+    constructor(address validatorAddress, address issuerAddress) ERC20("TEST", "TST") {
+        _validator = validatorAddress;
+        _issuer = issuerAddress;
+    }
+
+    modifier onlyIssuer() {
+        require(msg.sender == _issuer, "caller is not a issuer");
+        _;
+    }
+
+    modifier onlyValidatorOrIssuer() {
+        require(msg.sender == _issuer || msg.sender == validator, "caller is not a issuer or a validator");
+        _;
+    }
+
+    modifier validateSupply(uint256 mintAmount) {
+    require(
+        (totalSupply() <= _maxSupply) && (_maxSupply-totalSupply()>=mintAmount), 
+        "Exceeds maximum allowable supply");
+        _;
+    }
+
+
+    function setMaxSupply(uint256 supply, uint256 statement053) public override 
+    onlyValidatorOrIssuer
+    {
+        _maxSupply = supply;
+        emit MaxSupplyConfigured(msg.sender, _maxSupply, statement053);
+    }
+
+    function maxSupply() external override  view returns (uint256) {
+       return _maxSupply; 
+   }
+
+   function mint(address _holder, uint256 _value) public 
+   onlyIssuer 
+   validateSupply(_value)
+   returns (bool) {
+        _mint(_holder, _value);
+        return true;
+    }
+
+    function validator() external  override view returns(address) {
+        return _validator;
+    }
+
+}
+```
+
+## Security Considerations
+
+1. Overflow Protection: Uses Solidity 0.8+ built-in checks for arithmetic operations
+2. Access Control: Restricts mint to authorized roles (e.g., onlyIssuer) to prevent unauthorized issuance.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).