ethereum · catiga · Apr 7, 2024 · Apr 7, 2024 · Apr 7, 2024 · Apr 7, 2024
@@ -0,0 +1,261 @@
+---
+eip: 7680
+title: Valued Tokens with Layered Liquidity
+description: Layered liquidity protocol to ensure intrinsic value and enhanced stability for tokens
+author: Jackie JC.Lee (@catiga)
+discussions-to: https://ethereum-magicians.org/t/erc-7680-embedding-perpetual-value-and-liquidity-in-tokens/19577
+status: Draft
+type: Standards Track
+category: ERC
+created: 2024-04-07
+requires: 20, 165
+---
+
+## Abstract
+
+This proposal establishes a protective layer of liquidity within [ERC-20](./eip-20.md), guaranteeing a minimum intrinsic value and countering the risks associated with liquidity withdrawal.
+This proposal standard is a protocol that extends the [ERC-20] token standard to integrate a foundational liquidity pool, serving as a value floor for each token. This innovation ensures that tokens have a base value, which is protected from total loss in scenarios where liquidity is entirely removed. The protocol mandates a minimum inherent value for tokens by embedding a base amount of Ether within the smart contract, calculated and represented as a 'solid value' floor. This system also enables the direct extraction of this underlying value by token holders, providing a fail-safe mechanism and enhanced stability. Additionally, the proposal supports the dynamic enhancement of token value through community contributions to the liquidity pool and includes protective measures against value dilution during token transfer and burning processes.
+
+## Motivation
+
+The primary motivation behind this proposal is to address the vulnerability of token value in traditional ERC-20 tokens, which often relies on third-party liquidity pools. These pools are susceptible to sudden and significant value depletion, often resulting in tokens being rendered valueless, particularly in the event of liquidity withdrawal by pool creators, colloquially known as 'rug pulls'. Such events can undermine investor confidence and destabilize the token ecosystem. By ensuring that each proposal token maintains an intrinsic base value, the standard aims to protect token holders, enhance market stability, and promote trust in the tokenization model on the Ethereum blockchain. This innovation is especially critical in a landscape where decentralized finance is becoming increasingly prevalent, and the assurance of token value integrity is paramount.
+
+## 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.
+
-
+
+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.
+
+The standard is designed to introduce a new layer of liquidity enhancement for ERC-20 compatible tokens. This specification details the required functionality for implementing the standard, which allows for competing and interoperable implementations across different Ethereum platforms, such as Besu, Erigon, EthereumJS, Go-Ethereum, Nethermind, among others.
-The standard is designed to introduce a new layer of liquidity enhancement for ERC-20 compatible tokens. This specification details the required functionality for implementing the standard, which allows for competing and interoperable implementations across different Ethereum platforms, such as Besu, Erigon, EthereumJS, Go-Ethereum, Nethermind, among others.
-The standard is designed to introduce a new layer of liquidity enhancement for ERC-20 compatible tokens. This specification details the required functionality for implementing the standard, which allows for competing and interoperable implementations across different Ethereum platforms, such as Besu, Erigon, EthereumJS, Go-Ethereum, Nethermind, among others.
+
+The specification includes a set of interfaces for the base liquidity pool, mechanisms for increasing and extracting token value, and the processes for token minting and burning in response to liquidity changes.
+
+### Interfaces
+
+#### Token Interface
+A contract that is compliant with proposal shall implement the following interface:
+
+```solidity
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+
+interface IERC2510 is IERC20Metadata {
+    // Returns the total locked value in the base liquidity pool.
+    function solidValue() external view returns (uint256);
+
+    // Allows the enhancement of token's value by contributing to the base liquidity pool.
+    function enhanceTokenValue() external payable;
+
+    // Enables token holders to extract the intrinsic value of their tokens from the base liquidity pool.
+    function retrieveTokenValue(uint256 _amount) external;
+
+    // Calculates the amount of tokens for a given input value, indicating buy or sell operation.
+    function getAmountOut(uint256 value, bool _buy) external view returns(uint256);
+}
+```
+
+#### Solid Value Keeper for more independent execution
+In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
-In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
+In the implementation contract, the Keeper private `_keeper` attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
-In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
+In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities.
-In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
+In the implementation contract, the Keeper private `_keeper` attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
-In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities. This architectural decision underpins the robustness of the token's value support mechanism, by safeguarding the foundational eth reserves that back the intrinsic value of the token, and thereby, fortifying investor confidence in the token's stability and reliability.
+In the implementation contract, the Keeper private _keeper attribute plays a pivotal role in enhancing the protocol's security and stability features by segregating the eth held in the base liquidity pool from the standard liquidity pool integrated within the token contract. The Keeper contract is a dedicated entity designed to manage the eth specifically allocated for the base liquidity pool, ensuring a clear distinction and protection of these funds from the operational mechanics of the standard liquidity pool activities.
+
+```solidity
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/utils/Address.sol";
+
+contract ERC2510Keeper {
+    // The address that has the exclusive right to execute critical functions.
+    address private _keeper;
+
+    /**
+     * @dev Ensures that only the keeper can call the function modified by this.
+     */
+    modifier keepOp {
+        require(msg.sender == _keeper, "Only keeper can execute");
+        _;
+    }
+
+    /**
+     * @notice Allows the keeper to send value from the contract to a specified address.
+     * This function is critical for managing the liquidity pool's funds.
+     * @param _to The address to which the funds will be sent.
+     * @param _amount The amount of funds to send.
+     */
+    function retrieveValue(address _to, uint256 _amount) external keepOp;
+
+    /**
+     * @dev Allows the contract to receive ether directly to its balance.
+     * This is necessary for the contract to accumulate liquidity.
+     */
+    receive() payable external {}
+}
+```
+
+#### Liquidity Interface
+
+```solidity
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+/**
+ * @title ERC-2510 Liquidity Provision
+ * @dev Abstract contract for managing liquidity provision in ERC-2510 tokens.
+ * Provides mechanisms for adding, removing, and extending liquidity in a secure manner.
+ * Designed to be extended by ERC-2510 token contracts for integrated liquidity management.
+ */
+abstract contract ERC2510Liquidity is ReentrancyGuard {
+
+    // Events for tracking liquidity-related actions.
+    event AddLiquidity(address indexed provider, uint256 blockToUnlockLiquidity, uint256 value);
+    event RemoveLiquidity(address indexed remover, uint256 value);
+
+    // Block number when liquidity can be unlocked.
+    uint256 public blockToUnlockLiquidity;
+
+    /**
+     * @dev Adds liquidity to the contract with a lock-up period.
+     * Only callable by the contract owner or designated liquidity provider role.
+     * Emits an {AddLiquidity} event on successful addition of liquidity.
+     * @param _blockToUnlockLiquidity The future block number when liquidity can be removed.
+     */
+    function addLiquidity(uint256 _blockToUnlockLiquidity) external virtual payable;
+
+    /**
+     * @dev Removes liquidity from the contract.
+     * Can only be called internally, typically through a public function with access control.
+     * Emits a {RemoveLiquidity} event on successful removal of liquidity.
+     * Uses ReentrancyGuard to prevent reentrancy attacks during the withdrawal process.
+     */
+    function removeLiquidity() internal virtual nonReentrant;
+
+    /**
+     * @dev Extends the lock-up period for the liquidity in the contract.
+     * Can only be called internally, typically through a public function with access control.
+     * The new lock-up period must be greater than the current one.
+     * @param _blockToUnlockLiquidity The new block number to unlock the liquidity.
+     */
+    function extendLiquidityLock(uint256 _blockToUnlockLiquidity) internal virtual;
+}
+```
+
+### Base Liquidity Pool
+Implementation tokens MUST maintain a base liquidity pool that is separate from external liquidity providers like DEXs. This pool serves as the foundational layer of value for the tokens and is managed by the token contract itself.
-Implementation tokens MUST maintain a base liquidity pool that is separate from external liquidity providers like DEXs. This pool serves as the foundational layer of value for the tokens and is managed by the token contract itself.
+Implementation tokens MUST maintain a base liquidity pool that is separate from external liquidity providers like decentralized exchanges (DEXs). This pool serves as the foundational layer of value for the tokens and is managed by the token contract itself.
-Implementation tokens MUST maintain a base liquidity pool that is separate from external liquidity providers like DEXs. This pool serves as the foundational layer of value for the tokens and is managed by the token contract itself.
+Implementation tokens MUST maintain a base liquidity pool that is separate from external liquidity providers like decentralized exchanges (DEXs). This pool serves as the foundational layer of value for the tokens and is managed by the token contract itself.
+
+### Value Enhancement and Retrieval
+Token holders MAY contribute ETH to enhance the token's value, and MAY retrieve the equivalent value in ETH based on their token holdings, as per the enhanceTokenValue and retrieveTokenValue methods, respectively.
-Token holders MAY contribute ETH to enhance the token's value, and MAY retrieve the equivalent value in ETH based on their token holdings, as per the enhanceTokenValue and retrieveTokenValue methods, respectively.
+Token holders MAY contribute ETH to enhance the token's value, and MAY retrieve the equivalent value in ETH based on their token holdings, as per the `enhanceTokenValue` and `retrieveTokenValue` functions, respectively.
-Token holders MAY contribute ETH to enhance the token's value, and MAY retrieve the equivalent value in ETH based on their token holdings, as per the enhanceTokenValue and retrieveTokenValue methods, respectively.
+Token holders MAY contribute ETH to enhance the token's value, and MAY retrieve the equivalent value in ETH based on their token holdings, as per the `enhanceTokenValue` and `retrieveTokenValue` functions, respectively.
+
+### Liquidity Lock and Unlock Mechanism
+The standard MUST define a clear mechanism for liquidity locking and unlocking, which safeguards against premature withdrawals from the base liquidity pool and ensures long-term value stability for the token.
+
+### Events
+Proposal compliant contracts MUST emit events for significant liquidity and value-related operations, providing transparency and traceability for these actions on the blockchain.
+
+### Compliance with ERC-20
+Contracts implementing proposal protocol MUST remain fully compliant with ERC-20, including all standard functions and events, to ensure backward compatibility and integration with existing infrastructure.
+
+This specification ensures that proposal tokens can be integrated seamlessly into the Ethereum ecosystem, leveraging the established ERC-20 standard while introducing an innovative mechanism for maintaining and enhancing token value.
+
+
+## Rationale
+
+The standard was motivated by the desire to create a more stable and transparent token economy within the Ethereum ecosystem. In traditional ERC-20 tokens, value is often only as stable as the liquidity provided by third-party decentralized exchanges (DEXs). This standard aims to mitigate the risks of market manipulation and the potential for rapid devaluation due to liquidity withdrawal by introducing an inherent base liquidity pool within the token contract itself.
-The standard was motivated by the desire to create a more stable and transparent token economy within the Ethereum ecosystem. In traditional ERC-20 tokens, value is often only as stable as the liquidity provided by third-party decentralized exchanges (DEXs). This standard aims to mitigate the risks of market manipulation and the potential for rapid devaluation due to liquidity withdrawal by introducing an inherent base liquidity pool within the token contract itself.
+The standard was motivated by the desire to create a more stable and transparent token economy within the Ethereum ecosystem. In traditional ERC-20 tokens, value is often only as stable as the liquidity provided by third-party DEXs. This standard aims to mitigate the risks of market manipulation and the potential for rapid devaluation due to liquidity withdrawal by introducing an inherent base liquidity pool within the token contract itself.
-The standard was motivated by the desire to create a more stable and transparent token economy within the Ethereum ecosystem. In traditional ERC-20 tokens, value is often only as stable as the liquidity provided by third-party decentralized exchanges (DEXs). This standard aims to mitigate the risks of market manipulation and the potential for rapid devaluation due to liquidity withdrawal by introducing an inherent base liquidity pool within the token contract itself.
+The standard was motivated by the desire to create a more stable and transparent token economy within the Ethereum ecosystem. In traditional ERC-20 tokens, value is often only as stable as the liquidity provided by third-party DEXs. This standard aims to mitigate the risks of market manipulation and the potential for rapid devaluation due to liquidity withdrawal by introducing an inherent base liquidity pool within the token contract itself.
+
+Several design decisions were made to achieve this goal:
+
+1. **Base Liquidity Pool**: The concept of a base liquidity pool was introduced as a foundational layer for the token's value. This differs from the reliance on external liquidity providers and aims to provide a buffer against market volatility.
+
+2. **Value Enhancement and Retrieval**: Token holders are given the ability to directly influence the token's value through the `enhanceTokenValue` function. They can also extract value from the token through the `retrieveTokenValue` function. These features offer a degree of control and security to token holders not present in traditional ERC-20 tokens.
+
+3. **Lock and Unlock Mechanism**: A liquidity lock and unlock mechanism ensures that the liquidity cannot be withdrawn on a whim, which provides a level of security and trust that can encourage long-term investment and token holding.
+
+Alternative designs were considered, such as using bonding curves or algorithmic approaches to manage liquidity and token value. However, these were deemed to introduce additional complexity and potential attack vectors. The chosen design is intended to be simple to understand and implement while providing the necessary functionality to support a more stable token economy.
+
+The standard draws inspiration from existing financial instruments and stability mechanisms in other languages and systems, applying these concepts within the Ethereum framework to leverage the benefits of blockchain technology and smart contracts.
+
+
+## Backwards Compatibility
+
+No backward compatibility issues found.
+
+## Test Cases
+
+### Test Case 1: Enhance Token Value
+
+```solidity
+pragma solidity ^0.8.20;
+
+contract TestEnhanceTokenValue {
+    function testEnhanceTokenValue() public {
+        ERC2510 erc2510 = new ERC2510();
+        erc2510.enhanceTokenValue{value: 1 ether}();
+
+        // Assume the initial solid value is 0
+        uint expectedSolidValue = 1 ether;
+        Assert.equal(erc2510.solidValue(), expectedSolidValue, "Solid value should be increased by 1 ether after enhancement");
+    }
+}
+```
+
+### Test Case 2: Retrieve Token Value
+
+```solidity
+pragma solidity ^0.8.20;
+
+contract TestRetrieveTokenValue {
+    function testRetrieveTokenValue() public {
+        ERC2510 erc2510 = new ERC2510();
+        erc2510.enhanceTokenValue{value: 1 ether}();
+        // Assume msg.sender has enough tokens for the test
+        erc2510.retrieveTokenValue(100);
+
+        // Test needs to validate the actual transfer of ETH back to the msg.sender
+        // This will depend on the implementation details of retrieveTokenValue
+    }
+}
+```
+
+## Reference Implementation
+
+A reference implementation are available at GIT Repo.
+
+## Security Considerations
+
+The standard introduces several new concepts and mechanisms, particularly around the base liquidity pool and the enhancement of token value. While these features aim to provide stability and intrinsic value to the token, they also introduce potential security considerations that need to be addressed.
+
+### Smart Contract Vulnerabilities
+The implementation requires careful attention to common smart contract vulnerabilities, such as reentrancy attacks, overflow and underflow errors, and improper access control. It's crucial that standard security practices are followed:
+
+- Use the latest version of Solidity that includes safety features and checks.
+- Employ well-established smart contract security tools and audits to identify and mitigate potential vulnerabilities.
+- Implement checks-effects-interactions patterns to prevent reentrancy attacks, especially in functions that interact with the base liquidity pool.
+
+### Liquidity Pool Manipulation
+The base liquidity pool mechanism could be a target for manipulation by malicious actors looking to destabilize the token's value. To mitigate this risk:
+
+- Ensure transparent and fair mechanisms for enhancing the token's value and retrieving value from the base liquidity pool.
+- Implement rate limiting and other controls to prevent large, sudden contributions or withdrawals that could lead to manipulation or destabilization of the token's value.
+- Consider mechanisms for community governance or oversight of significant changes to the liquidity pool.
+
+### Keeper Contract Security
+The separation of the base liquidity pool into a Keeper contract isolates the funds and reduces the attack surface. However, this also means ensuring the security of the Keeper contract is paramount:
+
+- Strictly control the permissions and functions that can interact with the Keeper contract, especially those that can transfer or withdraw the pooled funds.
+- Ensure that the link between the main contract and the Keeper contract is securely established and immutable once set.
+- Regularly monitor and audit the Keeper contract, along with the main contract, for any potential security issues.
+
+
+### Front-Running and Transaction Ordering Dependence
+Actions that involve token value changes or liquidity pool adjustments may be susceptible to front-running, where an attacker sees a pending transaction and tries to exploit it by getting their transaction mined first.
+
+- Consider implementing transaction ordering protections, such as using commit-reveal schemes or ensuring that transactions do not rely on specific block states that can be predicted and exploited.
+- Evaluate the impact of transaction gas prices on the execution order and consider mechanisms to mitigate any potential adverse effects.
+
+### Governance and Administrative Functions
+If the implementation includes governance or administrative functions that can alter critical components of the token or liquidity pool:
+
+- Implement multi-signature or decentralized governance mechanisms to ensure that no single party has unilateral control over critical functions.
+- Clearly document and communicate the purpose and limitations of any administrative functions to the community to maintain transparency and trust.
+
+Overall, the security of tokens depends on thorough testing, community review, and adherence to best practices in smart contract development and security. Engaging with the Ethereum security community and conducting regular audits are essential steps in ensuring the safety and integrity of implementations.
+
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).