Add ERC20Collateral (#15)

* Implement `ERC20Collateral`

* Update tests

* Update timestamp type

Co-authored-by: Ernesto García <[email protected]>

* Implement IERC6372

* Add uint128 constant

Co-authored-by: Ernesto García <[email protected]>

* Use constant

* Use clock

---------

Co-authored-by: Ernesto García <[email protected]>

Author: cairoeth

contracts/mocks/token/ERC20CollateralMock.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC20, ERC20Collateral} from "../../token/ERC20/extensions/ERC20Collateral.sol";
+
+abstract contract ERC20CollateralMock is ERC20Collateral {
+    ERC20Collateral.Collateral private _collateral;
+
+    constructor(
+        uint48 liveness_,
+        string memory name_,
+        string memory symbol_
+    ) ERC20(name_, symbol_) ERC20Collateral(liveness_) {
+        _collateral = ERC20Collateral.Collateral({amount: type(uint128).max, timestamp: clock()});
+    }
+
+    function collateral() public view override returns (ERC20Collateral.Collateral memory) {
+        return _collateral;
+    }
+}

contracts/token/ERC20/extensions/ERC20Collateral.sol

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {IERC6372} from "@openzeppelin/contracts/interfaces/IERC6372.sol";
+
+/**
+ * @dev Extension of {ERC20} that limits the supply of tokens based
+ * on a collateral amount and time-based expiration.
+ *
+ * The {collateral} function must be implemented to return the collateral
+ * data. This function can call external oracles or use any local storage.
+ */
+abstract contract ERC20Collateral is ERC20, IERC6372 {
+    // Structure that stores the details of the collateral
+    struct Collateral {
+        uint256 amount;
+        uint48 timestamp;
+    }
+
+    /**
+     * @dev Liveness duration of collateral, defined in seconds.
+     */
+    uint48 private immutable _liveness;
+
+    /**
+     * @dev Total supply cap has been exceeded.
+     */
+    error ERC20ExceededSupply(uint256 increasedSupply, uint256 cap);
+
+    /**
+     * @dev Collateral amount has expired.
+     */
+    error ERC20ExpiredCollateral(uint48 timestamp, uint48 expiration);
+
+    /**
+     * @dev Sets the value of the `_liveness`. This value is immutable, it can only be
+     * set once during construction.
+     */
+    constructor(uint48 liveness_) {
+        _liveness = liveness_;
+    }
+
+    /**
+     * @dev Returns the minimum liveness duration of collateral.
+     */
+    function liveness() public view virtual returns (uint48) {
+        return _liveness;
+    }
+
+    /**
+     * @inheritdoc IERC6372
+     */
+    function clock() public view virtual returns (uint48) {
+        return uint48(block.timestamp);
+    }
+
+    /**
+     * @inheritdoc IERC6372
+     */
+    function CLOCK_MODE() public view virtual returns (string memory) {
+        return "mode=timestamp";
+    }
+
+    /**
+     * @dev Returns the collateral data of the token.
+     */
+    function collateral() public view virtual returns (Collateral memory);
+
+    /**
+     * @dev See {ERC20-_update}.
+     */
+    function _update(address from, address to, uint256 value) internal virtual override {
+        super._update(from, to, value);
+
+        if (from == address(0)) {
+            Collateral memory _collateral = collateral();
+
+            uint48 expiration = _collateral.timestamp + liveness();
+            if (expiration < clock()) {
+                revert ERC20ExpiredCollateral(_collateral.timestamp, expiration);
+            }
+
+            uint256 supply = totalSupply();
+            if (supply > _collateral.amount) {
+                revert ERC20ExceededSupply(supply, _collateral.amount);
+            }
+        }
+    }
+}

test/token/ERC20/extensions/ERC20Collateral.test.js

@@ -0,0 +1,46 @@
+const { ethers } = require('hardhat');
+const { expect } = require('chai');
+const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+const { time } = require('@nomicfoundation/hardhat-network-helpers');
+
+const name = 'My Token';
+const symbol = 'MTKN';
+const initialSupply = 100n;
+
+async function fixture() {
+    const [holder, recipient, approved] = await ethers.getSigners();
+
+    const token = await ethers.deployContract('$ERC20CollateralMock', [3600, name, symbol]);
+    await token.$_mint(holder, initialSupply);
+
+    return { holder, recipient, approved, token };
+}
+
+describe('ERC20Collateral', function () {
+    beforeEach(async function () {
+        Object.assign(this, await loadFixture(fixture));
+    });
+
+    describe('amount', function () {
+        const MAX_UINT128 = 2n ** 128n - 1n;
+
+        it('mint all of collateral amount', async function () {
+            await expect(this.token.$_mint(this.holder, MAX_UINT128 - initialSupply)).to.changeTokenBalance(this.token, this.holder, MAX_UINT128 - initialSupply);
+        });
+
+        it('reverts when minting more than collateral amount', async function () {
+            await expect(this.token.$_mint(this.holder, MAX_UINT128)).to.be.revertedWithCustomError(this.token, 'ERC20ExceededSupply');
+        });
+    });
+
+    describe('expiration', function () {
+        it('mint before expiration', async function () {
+            await expect(this.token.$_mint(this.holder, initialSupply)).to.changeTokenBalance(this.token, this.holder, initialSupply);
+        });
+
+        it('reverts when minting after expiration', async function () {
+            await time.increase(await this.token.liveness());
+            await expect(this.token.$_mint(this.holder, initialSupply)).to.be.revertedWithCustomError(this.token, 'ERC20ExpiredCollateral');
+        });
+    });
+});