From 0230f73bb3997c624c17d621f67fe65bd1c576ec Mon Sep 17 00:00:00 2001 From: Aether Cycle Date: Tue, 22 Jul 2025 21:11:33 +0700 Subject: [PATCH 1/8] EIP: ERC-vTOKEN: Virtual Token Standard (Draft proposal) --- ERCS/erc-9999.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 ERCS/erc-9999.md diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md new file mode 100644 index 00000000000..0e016e4bc67 --- /dev/null +++ b/ERCS/erc-9999.md @@ -0,0 +1,107 @@ +--- +erc: 9999 +title: "ERC-vTOKEN" +description: "ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs." +author: Fukuhi (@aethercycle) +discussions-to: https://ethereum-magicians.org/t/your-topic-slug/12345 +status: Draft +type: Standards Track +category: Interface +created: 2025-07-22 +requires: 20 +--- + +## Abstract + +The ERC-vTOKEN introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining ERC-20 interface compatibility. + +## Motivation + +DeFi protocols suffer from fragile liquidity mechanisms: + +- Liquidity can be withdrawn, breaking price floors +- Rug pulls by developers or LP owners +- Yield farming models that collapse post-incentives +- Users needing trust in human-controlled admin functions + +ERC-vTOKEN addresses these problems by: + +- Prohibiting user custody of vTOKENs +- Enabling seamless, automatic conversion to native tokens +- Locking liquidity in contracts permanently +- Enforcing economic sustainability mathematically + +## Specification + +### Core Features + +1. **Non-transferable to EOAs**: vTOKENs revert when transferred to EOAs. +2. **Automatic Conversion**: Transfers to EOAs trigger conversion to native tokens. +3. **Whitelist System**: Only approved smart contracts can hold vTOKENs. +4. **ERC-20 Compatible**: Fully compliant with ERC-20 interface. + +### Interface + +``` +interface IERCvTOKEN is IERC20 { + event VirtualConversion(address indexed recipient, uint256 vTokenAmount, uint256 nativeTokenAmount); + event WhitelistUpdated(address indexed account, bool status); + + function isWhitelisted(address account) external view returns (bool); + function calculateNativeEquivalent(uint256 vTokenAmount) external view returns (uint256); + function nativeToken() external view returns (address); +} +``` + +### Behavior + +- Transfers to EOAs trigger a conversion: vTOKENs are burned, and native tokens sent. +- Transfers between whitelisted contracts proceed normally. +- Any unauthorized recipient address causes a revert. + +## Rationale + +- **Transfer Override** ensures all transfer logic paths enforce virtual conversion. +- **Whitelist Enforcement** allows strict protocol-defined behavior. +- **Burn-on-convert** model prevents supply inflation and ensures conservation. +- **Deterministic Conversion Logic** avoids manipulation; rate may be fixed or oracle-based. + +## Backwards Compatibility + +ERC-vTOKEN maintains: + +- Compatibility with ERC-20 tools (balanceOf, transferFrom, etc.) +- Event and metadata consistency + +It is **not compatible** with: + +- Wallets expecting transferable tokens +- DEX aggregators without vTOKEN support + +## Test Cases + +Covered in repository: + +- Transfer to EOA → converts +- Transfer to whitelisted contract → allowed +- Transfer to unknown → reverts +- Conversion with insufficient balance → reverts + +## Reference Implementation + +Reference implementation available in the [ERC-vTOKEN repository](../ERC-vTOKEN). + +## Security Considerations + +- **Reentrancy**: Conversion logic should use standard protections (e.g. nonReentrant). +- **Whitelist management** must be immutable or governance-controlled post-deployment. +- **Conversion failure**: Contracts should revert gracefully if native token balance insufficient. +- **Admin privileges**: Strongly recommended to renounce ownership post-deployment. + +## Copyright + +Copyright and related rights waived via CC BY-SA 4.0. + +--- + +*This draft EIP proposes a new ERC standard for virtual tokens. Feedback and implementations are welcomed via the GitHub repository.* From cd6c4776e2d950eee54336a84257a86fcf6245a1 Mon Sep 17 00:00:00 2001 From: Aether Cycle Date: Tue, 22 Jul 2025 21:44:22 +0700 Subject: [PATCH 2/8] fix: assign official EIP number (1129) --- ERCS/erc-9999.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index 0e016e4bc67..a779c1ac410 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,14 +1,15 @@ --- -erc: 9999 -title: "ERC-vTOKEN" -description: "ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs." -author: Fukuhi (@aethercycle) -discussions-to: https://ethereum-magicians.org/t/your-topic-slug/12345 +eip: 1129 +title: ERC-vTOKEN: Virtual Token Standard +description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. +author: Fukuhi (@aethercycle) +discussions-to: https://ethereum-magicians.org/t/erc-vtoken-virtual-token-standard/12345 status: Draft type: Standards Track -category: Interface +category: ERC created: 2025-07-22 requires: 20 +license: CC-BY-SA-4.0 --- ## Abstract From 3f87fa365b1fe54846c74a3e46ea24c46359c390 Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Thu, 24 Jul 2025 17:49:05 +0700 Subject: [PATCH 3/8] Update erc-9999.md --- ERCS/erc-9999.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index a779c1ac410..1685013383a 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,15 +1,14 @@ --- -eip: 1129 -title: ERC-vTOKEN: Virtual Token Standard -description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. -author: Fukuhi (@aethercycle) -discussions-to: https://ethereum-magicians.org/t/erc-vtoken-virtual-token-standard/12345 +eip: 9999 +title: "ERC-vTOKEN" +description: "ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs." +author: Fukuhi (@aethercycle) +discussions-to: https://ethereum-magicians.org/t/your-topic-slug/12345 status: Draft type: Standards Track -category: ERC +category: Interface created: 2025-07-22 requires: 20 -license: CC-BY-SA-4.0 --- ## Abstract @@ -47,7 +46,6 @@ ERC-vTOKEN addresses these problems by: interface IERCvTOKEN is IERC20 { event VirtualConversion(address indexed recipient, uint256 vTokenAmount, uint256 nativeTokenAmount); event WhitelistUpdated(address indexed account, bool status); - function isWhitelisted(address account) external view returns (bool); function calculateNativeEquivalent(uint256 vTokenAmount) external view returns (uint256); function nativeToken() external view returns (address); @@ -90,7 +88,7 @@ Covered in repository: ## Reference Implementation -Reference implementation available in the [ERC-vTOKEN repository](../ERC-vTOKEN). +Reference implementation available in the [ERC-vTOKEN repository](https://github.com/aethercycle/ERC-vTOKEN). ## Security Considerations From 65b4f10731c29581df784fe40164cb378cb2cc44 Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Thu, 24 Jul 2025 18:13:19 +0700 Subject: [PATCH 4/8] Update erc-9999.md --- ERCS/erc-9999.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index 1685013383a..550c5db81e1 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,19 +1,20 @@ --- eip: 9999 -title: "ERC-vTOKEN" -description: "ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs." -author: Fukuhi (@aethercycle) -discussions-to: https://ethereum-magicians.org/t/your-topic-slug/12345 +title: ERC-vTOKEN: Virtual Token Standard +description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. +author: Fukuhi (@aethercycle) +discussions-to: https://ethereum-magicians.org/t/erc-vtoken-virtual-token-standard/12345 status: Draft type: Standards Track -category: Interface +category: ERC created: 2025-07-22 requires: 20 +license: CC-BY-SA-4.0 --- ## Abstract -The ERC-vTOKEN introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining ERC-20 interface compatibility. +[ERC-9999] introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20] interface compatibility. ## Motivation @@ -38,14 +39,15 @@ ERC-vTOKEN addresses these problems by: 1. **Non-transferable to EOAs**: vTOKENs revert when transferred to EOAs. 2. **Automatic Conversion**: Transfers to EOAs trigger conversion to native tokens. 3. **Whitelist System**: Only approved smart contracts can hold vTOKENs. -4. **ERC-20 Compatible**: Fully compliant with ERC-20 interface. +4. **[ERC-20] Compatible**: Fully compliant with standard ERC-20 interface. ### Interface -``` +```solidity interface IERCvTOKEN is IERC20 { event VirtualConversion(address indexed recipient, uint256 vTokenAmount, uint256 nativeTokenAmount); event WhitelistUpdated(address indexed account, bool status); + function isWhitelisted(address account) external view returns (bool); function calculateNativeEquivalent(uint256 vTokenAmount) external view returns (uint256); function nativeToken() external view returns (address); @@ -69,7 +71,7 @@ interface IERCvTOKEN is IERC20 { ERC-vTOKEN maintains: -- Compatibility with ERC-20 tools (balanceOf, transferFrom, etc.) +- Compatibility with [ERC-20] tools (`balanceOf`, `transferFrom`, etc.) - Event and metadata consistency It is **not compatible** with: @@ -88,19 +90,20 @@ Covered in repository: ## Reference Implementation -Reference implementation available in the [ERC-vTOKEN repository](https://github.com/aethercycle/ERC-vTOKEN). +Reference implementation available in the repository: [../ERC-vTOKEN](../ERC-vTOKEN) ## Security Considerations -- **Reentrancy**: Conversion logic should use standard protections (e.g. nonReentrant). -- **Whitelist management** must be immutable or governance-controlled post-deployment. -- **Conversion failure**: Contracts should revert gracefully if native token balance insufficient. -- **Admin privileges**: Strongly recommended to renounce ownership post-deployment. +- **Reentrancy**: Conversion logic should use standard protections (e.g. `nonReentrant`) +- **Whitelist management** must be immutable or governance-controlled post-deployment +- **Conversion failure**: Contracts should revert gracefully if native token balance insufficient +- **Admin privileges**: Strongly recommended to renounce ownership post-deployment ## Copyright -Copyright and related rights waived via CC BY-SA 4.0. +Copyright and related rights waived via [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). --- *This draft EIP proposes a new ERC standard for virtual tokens. Feedback and implementations are welcomed via the GitHub repository.* + From 74754193054765587ae8dbe3982da4c28ca15724 Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Thu, 24 Jul 2025 18:24:47 +0700 Subject: [PATCH 5/8] fix: assign --- ERCS/erc-9999.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index 550c5db81e1..09f628c2d00 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,20 +1,19 @@ --- eip: 9999 -title: ERC-vTOKEN: Virtual Token Standard +title: ERC-vTOKEN description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. -author: Fukuhi (@aethercycle) +author: Fukuhi (@aethercycle) discussions-to: https://ethereum-magicians.org/t/erc-vtoken-virtual-token-standard/12345 status: Draft type: Standards Track category: ERC created: 2025-07-22 requires: 20 -license: CC-BY-SA-4.0 --- ## Abstract -[ERC-9999] introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20] interface compatibility. +[ERC-9999] introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20](./eip-20.md) interface compatibility. ## Motivation @@ -39,7 +38,7 @@ ERC-vTOKEN addresses these problems by: 1. **Non-transferable to EOAs**: vTOKENs revert when transferred to EOAs. 2. **Automatic Conversion**: Transfers to EOAs trigger conversion to native tokens. 3. **Whitelist System**: Only approved smart contracts can hold vTOKENs. -4. **[ERC-20] Compatible**: Fully compliant with standard ERC-20 interface. +4. **ERC-20 Compatible**: Fully compliant with standard ERC-20 interface. ### Interface @@ -71,7 +70,7 @@ interface IERCvTOKEN is IERC20 { ERC-vTOKEN maintains: -- Compatibility with [ERC-20] tools (`balanceOf`, `transferFrom`, etc.) +- Compatibility with [ERC-20](./eip-20.md) tools (`balanceOf`, `transferFrom`, etc.) - Event and metadata consistency It is **not compatible** with: @@ -90,7 +89,7 @@ Covered in repository: ## Reference Implementation -Reference implementation available in the repository: [../ERC-vTOKEN](../ERC-vTOKEN) +Reference implementation available in the repository: [`ERC-vTOKEN`](../ERC-vTOKEN) ## Security Considerations @@ -101,9 +100,8 @@ Reference implementation available in the repository: [../ERC-vTOKEN](../ERC-vTO ## Copyright -Copyright and related rights waived via [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). +Copyright and related rights waived via [CC BY-SA 4.0](../LICENSE-CC-BY-SA-4.0.md). --- *This draft EIP proposes a new ERC standard for virtual tokens. Feedback and implementations are welcomed via the GitHub repository.* - From 189fcddfe102b99bf819c20b3c3405a99ee97608 Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Thu, 24 Jul 2025 18:32:04 +0700 Subject: [PATCH 6/8] Update erc-9999.md --- ERCS/erc-9999.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index 09f628c2d00..1d3e1ddb88a 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -13,7 +13,7 @@ requires: 20 ## Abstract -[ERC-9999] introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20](./eip-20.md) interface compatibility. +This EIP introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20](./eip-20.md) interface compatibility. ## Motivation From d6e8485ed504f2f743858613a1087774e7e4d9ba Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Tue, 29 Jul 2025 17:06:18 +0700 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Andrew B Coathup <28278242+abcoathup@users.noreply.github.com> --- ERCS/erc-9999.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index 1d3e1ddb88a..fc112f11877 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,6 +1,6 @@ --- -eip: 9999 -title: ERC-vTOKEN +eip: 7991 +title: Non-transferable to EOA ERC20 description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. author: Fukuhi (@aethercycle) discussions-to: https://ethereum-magicians.org/t/erc-vtoken-virtual-token-standard/12345 From 77388be5660af42731b0c9b090e814d072d170df Mon Sep 17 00:00:00 2001 From: AetherCycle Date: Tue, 29 Jul 2025 17:25:17 +0700 Subject: [PATCH 8/8] Refactor: Apply RFC 2119/8174 keywords and abstract refinement This commit incorporates feedback to enhance the EIP's clarity and adherence to EIP standards. Key changes include: - Added RFC 2119/8174 disclaimer for keyword interpretation. - Applied consistent use of 'MUST', 'SHOULD', 'MAY', etc., throughout the Specification and Security Considerations sections. - Revised the Abstract to focus purely on describing the ERC's functionality, moving benefits to the Motivation section. --- ERCS/erc-9999.md | 107 +++++++++++++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 40 deletions(-) diff --git a/ERCS/erc-9999.md b/ERCS/erc-9999.md index fc112f11877..7749a6c47a6 100644 --- a/ERCS/erc-9999.md +++ b/ERCS/erc-9999.md @@ -1,4 +1,3 @@ ---- eip: 7991 title: Non-transferable to EOA ERC20 description: ERC-20-compatible token that only exists in contracts and auto-converts to native tokens for EOAs. @@ -11,97 +10,125 @@ created: 2025-07-22 requires: 20 --- +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] when, and only when, they appear in all capitals, as defined in RFC 8174. + ## Abstract -This EIP introduces a new token architecture where tokens are non-transferable to externally owned accounts (EOAs), enabling mathematically permanent liquidity. vTOKENs exist only within smart contracts and convert automatically into native tokens when sent to EOAs. This model prevents rug pulls, liquidity extraction, and ensures immutable liquidity depth, while maintaining [ERC-20](./eip-20.md) interface compatibility. +This EIP introduces a novel token architecture where tokens are non-transferable to Externally Owned Accounts (EOAs). vTOKENs **MUST** exist solely within smart contracts and **MUST** automatically convert into their paired native tokens when an attempt is made to send them to an EOA. This standard defines an ERC-20 compatible interface for these virtual tokens. ## Motivation -DeFi protocols suffer from fragile liquidity mechanisms: +DeFi protocols currently face fundamental challenges that compromise long-term stability and user trust: -- Liquidity can be withdrawn, breaking price floors -- Rug pulls by developers or LP owners -- Yield farming models that collapse post-incentives -- Users needing trust in human-controlled admin functions +* Liquidity can be withdrawn by liquidity providers, leading to sudden price drops and breaking established price floors. +* The risk of "rug pulls" exists, where developers or large token holders can drain liquidity pools, causing significant financial loss to participants. +* Many yield farming and liquidity mining models offer only temporary solutions, often collapsing once incentives diminish. +* Users are frequently required to place trust in human-controlled admin functions, which can be exploited or misused. -ERC-vTOKEN addresses these problems by: +The ERC-vTOKEN standard addresses these problems by introducing a design that: -- Prohibiting user custody of vTOKENs -- Enabling seamless, automatic conversion to native tokens -- Locking liquidity in contracts permanently -- Enforcing economic sustainability mathematically +* Prohibits the custody of vTOKENs by individual user wallets (EOAs). +* Enables seamless, automatic conversion of vTOKENs to their native token counterparts upon attempted transfer to an EOA. +* Ensures liquidity, once provided, is permanently locked within designated contracts. +* Enforces economic sustainability and prevents liquidity extraction through mathematical design. ## Specification ### Core Features -1. **Non-transferable to EOAs**: vTOKENs revert when transferred to EOAs. -2. **Automatic Conversion**: Transfers to EOAs trigger conversion to native tokens. -3. **Whitelist System**: Only approved smart contracts can hold vTOKENs. -4. **ERC-20 Compatible**: Fully compliant with standard ERC-20 interface. +1. **Non-transferable to EOAs**: vTOKENs **MUST NOT** be transferable to Externally Owned Accounts (EOAs). Attempts to transfer vTOKENs to an EOA **MUST** trigger an automatic conversion to the paired native token. +2. **Automatic Conversion**: Transfers to EOAs **MUST** trigger a conversion where the vTOKENs are burned from the sender and an equivalent amount of native tokens are transferred to the recipient EOA. +3. **Whitelist System**: Only approved smart contracts **MAY** hold vTOKENs. Implementations **SHOULD** include a mechanism to manage this whitelist. +4. **ERC-20 Compatible**: Implementations **MUST** be fully compliant with the standard [ERC-20](https://www.google.com/search?q=./eip-20.md) interface, allowing for seamless integration with existing DeFi protocols. ### Interface ```solidity interface IERCvTOKEN is IERC20 { + /** + * @dev Emitted when vTOKEN is virtually converted to native token. + * @param recipient The address receiving native tokens. + * @param vTokenAmount Amount of vTOKEN attempted to transfer. + * @param nativeTokenAmount Amount of native token received. + */ event VirtualConversion(address indexed recipient, uint256 vTokenAmount, uint256 nativeTokenAmount); + + /** + * @dev Emitted when whitelist status changes. + * @param account The address whose status changed. + * @param status New whitelist status. + */ event WhitelistUpdated(address indexed account, bool status); + /** + * @dev Returns whether an address can receive vTOKEN. + * @param account Address to check. + * @return bool True if whitelisted. + */ function isWhitelisted(address account) external view returns (bool); + + /** + * @dev Calculates the native token equivalent for a given vTOKEN amount. + * @param vTokenAmount Amount of vTOKEN. + * @return uint256 Equivalent native token amount. + */ function calculateNativeEquivalent(uint256 vTokenAmount) external view returns (uint256); + + /** + * @dev Returns the address of the paired native token. + * @return address Native token contract. + */ function nativeToken() external view returns (address); } ``` ### Behavior -- Transfers to EOAs trigger a conversion: vTOKENs are burned, and native tokens sent. -- Transfers between whitelisted contracts proceed normally. -- Any unauthorized recipient address causes a revert. +* Transfers to EOAs **MUST** trigger a conversion: vTOKENs are burned from the sender, and the calculated native token equivalent is transferred to the EOA. +* Transfers between whitelisted contracts **MUST** proceed as standard ERC-20 transfers. +* Any transfer attempt to an unauthorized recipient address (i.e., not an EOA triggering conversion, and not a whitelisted contract) **MUST** cause a revert. ## Rationale -- **Transfer Override** ensures all transfer logic paths enforce virtual conversion. -- **Whitelist Enforcement** allows strict protocol-defined behavior. -- **Burn-on-convert** model prevents supply inflation and ensures conservation. -- **Deterministic Conversion Logic** avoids manipulation; rate may be fixed or oracle-based. +* **Transfer Override**: Overriding the standard `_transfer` function **MUST** be implemented to ensure all transfer logic paths correctly enforce the virtual conversion and whitelist rules. This maintains ERC-20 compatibility while adding the unique vTOKEN behavior. +* **Whitelist Enforcement**: An explicit whitelist **SHOULD** be used to prevent unauthorized contract interactions and allow precise control over vTOKEN circulation. Typical whitelisted addresses include liquidity pool contracts, routers, and protocol treasuries. +* **Burn-on-convert Model**: vTOKENs **MUST** be burned during conversion to prevent supply inflation and ensure the conservation of value. This mechanism maintains accurate supply metrics. +* **Deterministic Conversion Logic**: The `calculateNativeEquivalent` function **SHOULD** implement deterministic or oracle-based conversion rates to avoid manipulation. The rate **MAY** be fixed (e.g., 1:1) or dynamically derived (e.g., from an AMM or TWAP oracle). ## Backwards Compatibility ERC-vTOKEN maintains: -- Compatibility with [ERC-20](./eip-20.md) tools (`balanceOf`, `transferFrom`, etc.) -- Event and metadata consistency +* Compatibility with existing [ERC-20](https://www.google.com/search?q=./eip-20.md) tools and functions, such as `balanceOf`, `allowance`, and `transferFrom` (when interacting with whitelisted contracts). +* Consistency in event emissions and metadata (e.g., `name()`, `symbol()`, `decimals()`). It is **not compatible** with: -- Wallets expecting transferable tokens -- DEX aggregators without vTOKEN support +* Standard cryptocurrency wallets that expect to hold and directly transfer tokens from an EOA. +* Decentralized Exchange (DEX) aggregators or other protocols that do not explicitly integrate or understand the vTOKEN conversion mechanism. ## Test Cases -Covered in repository: +Comprehensive test cases **SHOULD** be provided in the reference repository to cover critical scenarios, including: -- Transfer to EOA → converts -- Transfer to whitelisted contract → allowed -- Transfer to unknown → reverts -- Conversion with insufficient balance → reverts +* Transfer to an EOA **MUST** trigger conversion to native tokens. +* Transfer to a whitelisted contract **MUST** be allowed and behave as a standard ERC-20 transfer. +* Transfer to an unknown (non-whitelisted, non-EOA) address **MUST** revert. +* Conversion with insufficient native token balance in the vTOKEN contract **MUST** revert. ## Reference Implementation -Reference implementation available in the repository: [`ERC-vTOKEN`](../ERC-vTOKEN) +A reference implementation **SHOULD** be available in the repository: [https://github.com/aethercycle/ERC-vTOKEN](https://github.com/aethercycle/ERC-vTOKEN) ## Security Considerations -- **Reentrancy**: Conversion logic should use standard protections (e.g. `nonReentrant`) -- **Whitelist management** must be immutable or governance-controlled post-deployment -- **Conversion failure**: Contracts should revert gracefully if native token balance insufficient -- **Admin privileges**: Strongly recommended to renounce ownership post-deployment +* **Reentrancy**: The `_transfer` function and any logic involving external calls (e.g., native token transfer during conversion) **MUST** be protected against reentrancy attacks, ideally using a `nonReentrant` modifier or following the checks-effects-interactions pattern. +* **Whitelist Management**: The management of the whitelist **SHOULD** be restricted to authorized entities (e.g., `Ownable` or a DAO). For maximum security, the whitelist **MAY** be made immutable or fully governance-controlled post-deployment. +* **Conversion Failure**: The contract **MUST** gracefully revert if it lacks sufficient native token balance to perform a required conversion. Automated refill mechanisms **SHOULD** be considered. +* **Admin Privileges**: It is **STRONGLY RECOMMENDED** to renounce ownership or transfer admin privileges to a time-locked contract or DAO post-deployment to minimize central points of failure and potential for abuse. ## Copyright -Copyright and related rights waived via [CC BY-SA 4.0](../LICENSE-CC-BY-SA-4.0.md). - ---- +Copyright and related rights waived via [CC BY-SA 4.0](https://www.google.com/search?q=../LICENSE-CC-BY-SA-4.0.md). *This draft EIP proposes a new ERC standard for virtual tokens. Feedback and implementations are welcomed via the GitHub repository.*