From 16a3acbfdde6c98c631590fd3977794840f7d548 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Mon, 5 Feb 2024 03:39:09 -0500 Subject: [PATCH 1/9] Update erc-7425.md --- ERCS/erc-7425.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index 1b407a37bc..af6fadc2e0 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -13,29 +13,36 @@ requires: 20, 4626 ## Abstract -A proposal for a tokenized reserve mechanism. The reserve allows an audit of on-chain actions of the owner. Using [ERC-4626](../EIPS/eip-4626.md), stakeholders can create shares to show support for actions in the reserve. +This specification explains an implementation of a tokenized reserve mechanism. The reserve allows users to audit of on-chain actions of stakeholders. Using [ERC-4626](../ERCS/erc-4626.md), stakeholders can create shares to show support for actions in the reserve. ## Motivation -Tokenized reserves are an extension of tokenized vaults. The goal is to create a reserve similar to a real world reserve an entity has as a backup in case regular funds run low. In the real world, an entity will have to meet certain criteria before accessing reserve funds. In a decentralized environment, an entity can incorporate stakeholders into their criteria. This will help entities who participate in decentralized environments to be transparent with stakeholders. +Tokenized vaults store ERC-20 tokens within vaults that are represented by shares. Implemenations can follow the [ERC-4626](../ERCS/erc-4626.md) standard provides basic functionality for depositing and withdrawing. As tokenization becomes popular, applications will be using tokenized vaults that store assest for multiple reasons. + +This specifcation introduces a standard for a on-chain reserve that will use tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension to [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depsoiting and withdrawing from the vault. The record of transactions are made easily accessicble by all stakeholders allowing audits by any party. + +## Background + +In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real world reserve fund used as contingency for an entity. An entity could create a criteria like, when regular funds run low the reserve fund will be utilized. before accessing reserve funds. In a decentralized environment, an entity can incorporate stakeholders into their criteria. This will help entities who participate in decentralized environments to be transparent with stakeholders. + ## 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](https://www.ietf.org/rfc/rfc2119.txt) and RFC [8174](https://www.ietf.org/rfc/rfc8174.txt). ### Definitions: - owner: The creator of the reserve - - user: Stakeholders of specific proposals - - reserve: The tokenized reserve contract - - proposal: Occurs when the owner wants a withdrawal from contract + - user: Stakeholders participating proposals + - reserve: The assets held on the contract other than underlying token + - proposal: Created by owners to encourage stakeholder participation ### Constructor: - name: ERC-20 token name - ticker: ERC-20 ticker - asset: ERC-4626 underlying ERC-20 address - - rAuth: Primary authorized user + - rAuth: Authorized user, for cases utilizing more than one owner - rOwner: Owner of the Reserve ### Interface @@ -162,7 +169,7 @@ interface TokenReserve is ERC4626{ ## Rationale -This proposal is designed to be a basic implementation of a reserve fund interface. Other non specified conditions should be addressed on a case by case basis. Each reserve uses [ERC-20](../EIPS/eip-20.md) standard for shares, and [ERC-4626](../EIPS/eip-4626.md) for the creation of shares. The reserve token can be the underlying token in [ERC-4626](../EIPS/eip-4626.md) or the shares that are created when the underlying token is deposited in the vault. +This proposal is designed to be a basic implementation of a tokenized reserve interface. Other non specified conditions should be addressed on a case by case basis. Each reserve uses [ERC-20](../EIPS/eip-20.md) standard for shares, and [ERC-4626](../EIPS/eip-4626.md) for the creation of shares. The reserve token can be the underlying token in [ERC-4626](../EIPS/eip-4626.md) or the shares that are created when the underlying token is deposited in the vault. [ERC-4626](../EIPS/eip-4626.md) is implemented to the reserve to account for user participation. There needs to be a representation for users participating in a proposal within a reserve. With vaults, the implementor could decide how to treat participation based on users entering the vault. For example, a user could be forced not to use the same tokens in multiple proposals to allow shares to be created fairly. Once the underlying token is deposited into the vault for an open proposal those tokens could not be accessible until the proposal is closed. It is not explicitly enforced that deposited tokens that create shares cannot be withdrawn by the owner of the reserve. On a case by case basis there can be implementions to ensure those tokens are accounted for if needed. @@ -172,6 +179,10 @@ Tokenized reserves are made compatible with [ERC-20](../EIPS/eip-20.md) and [ERC ## Security Considerations +1. Assests are not secured by vaults from owner withdrawal +- Users SHOULD be aware when a reserve can be withdrawn by the owner with no restrictions like requiring an authorized user. Depending on the authorized user implementation, assets MAY still be withdrawn. + +Implementation Needs discussion. ## Copyright From ec26a40d90618631ccf99e6522b9c15edfbef4bb Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 6 Feb 2024 06:58:03 -0500 Subject: [PATCH 2/9] Update erc-7425.md --- ERCS/erc-7425.md | 80 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index af6fadc2e0..d41bd34f5a 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -13,17 +13,17 @@ requires: 20, 4626 ## Abstract -This specification explains an implementation of a tokenized reserve mechanism. The reserve allows users to audit of on-chain actions of stakeholders. Using [ERC-4626](../ERCS/erc-4626.md), stakeholders can create shares to show support for actions in the reserve. +This specification explains a tokenized reserve mechanism standard. Current smart contracts record transactions and are made public. The reserve will implement added functionality allowing stakeholders proactively to audit a contract. Using [ERC-4626](../ERCS/erc-4626.md), stakeholders can create shares to show support for actions in the contract. ## Motivation -Tokenized vaults store ERC-20 tokens within vaults that are represented by shares. Implemenations can follow the [ERC-4626](../ERCS/erc-4626.md) standard provides basic functionality for depositing and withdrawing. As tokenization becomes popular, applications will be using tokenized vaults that store assest for multiple reasons. +Tokenized vaults store [ERC-20](../ERCS/erc-20.md) tokens that are represented by shares within vault contracts. Implemenations can follow the [ERC-4626](../ERCS/erc-4626.md) standard to provide basic functionality for depositing, withdrawing and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assests and allow all parties to track performance. -This specifcation introduces a standard for a on-chain reserve that will use tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension to [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depsoiting and withdrawing from the vault. The record of transactions are made easily accessicble by all stakeholders allowing audits by any party. +This specifcation introduces a standard for a on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depsoiting and withdrawing from the vault. The record of transactions for other [ERC-20](../ERCS/erc-20.md) assests should be easily accessicble to any party for auditing. ## Background -In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real world reserve fund used as contingency for an entity. An entity could create a criteria like, when regular funds run low the reserve fund will be utilized. before accessing reserve funds. In a decentralized environment, an entity can incorporate stakeholders into their criteria. This will help entities who participate in decentralized environments to be transparent with stakeholders. +In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like, running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets accioted with the reserve as well as its orgin will vary in decentralized envirnoments, so transparent auditing is needed. ## Specification @@ -50,10 +50,10 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ```solidity // SPDX-License-Identifier: CC0-1.0 -pragma solidity ^0.8.0; import "./ERC4626.sol"; interface TokenReserve is ERC4626{ + /** * @dev Event emitted after a new proposal is created */ @@ -63,6 +63,7 @@ interface TokenReserve is ERC4626{ uint256 indexed amount, address recipient ); + /** * @dev Event emitted after a new deposit is made by the owner */ @@ -72,46 +73,60 @@ interface TokenReserve is ERC4626{ uint256 indexed time, uint256 count ); + /** - * @dev Get time of a deposit made to reserve with depositReserve() - * @param count Number matching deposit + * @dev Get time of a deposit made to reserve by owner + * @param count Number for deposit count * @return block.timestamp format */ function depositTime(uint256 count) external view returns (uint256); + /** - * @dev Get amount deposited to reserve with depositReserve() - * @param count Number of deposit - * @return uint256 number of any asset that were deposited + * @dev Get amount deposited to reserve by owner + * @param count Number for deposit count + * @return uint256 Amount of an asset that was deposited */ function ownerDeposit(uint256 count) external view returns(uint256); + /** - * @dev Token type deposited to reserve with depositReserve() + * @dev Token type deposited to reserve by owner * - MUST be an address of ERC20 token * @param count Number of deposit + * @return address Address of ERC20 token */ function tokenDeposit(uint256 count) external view returns(address); + /** - * @dev Amount deposited for shares of proposal by the user - * - MUST be an ERC20 address - * @param user address of user - * @param proposal number of the proposal the user deposited + * @dev Amount deposited by the user to a proposal for shares + * - MUST be an ERC20 token + * @param user Address of user + * @param proposal Proposal number the user deposited to + * @return uint256 Amount of ERC20 deposited */ function userDeposit(address user, uint256 proposal) external view returns(uint256); + /** * @dev Token used for given proposal * - MUST be ERC20 address - * @param proposal number for requested token - * @return token address + * @param proposal Proposal number for requested used token + * @return Token address */ function proposalToken(uint256 proposal) external view returns(address); + /** - * @dev Amount withdrawn for given opened proposal + * @dev Amount withdrawn for given opened proposal number + * @param proposal Proposal number + * @return Amount of ERC20 */ function proposalWithdrew(uint256 proposal) external view returns(uint256); + /** - * @dev Amount received for given closed proposal + * @dev Amount received for given proposal number + * @param proposal Proposal number + * @return Amount of ERC20 */ function proposalDeposited(uint256 proposal) external view returns(uint256); + /** * @dev Make a deposit to a proposal creating new shares with deposit function from ERC-4626 * - MUST be opened proposal @@ -120,8 +135,10 @@ interface TokenReserve is ERC4626{ * @param assets Amount being deposited * @param receiver Address of depositor * @param proposal Number associated proposal + * @return Amount of mint shares */ function proposalDeposit(uint256 assets, address receiver, uint256 proposal) external virtual returns(uint256); + /** * @dev Burn shares, receive 1 to 1 value of shares * - MUST have closed proposalNumber @@ -130,20 +147,26 @@ interface TokenReserve is ERC4626{ * @param receiver Address of receiver * @param owner Address of token owner * @param proposal Number associated proposal + * @return Amount of the asset */ function proposalWithdraw(uint256 assets, address receiver, address owner, uint256 proposal)external virtual returns(uint256); + /** * @dev Issue new proposal * - MUST create new proposal number * - MUST account for amount withdrawn + * - MUST be owner * - MUST emit proposals event * @param token Address of ERC-20 token * @param amount Token amount being withdrawn * @param receiver Address of token recipient + * @return Proposal number */ function proposalOpen(address token, uint256 amount, address receiver) external virtual returns (uint256); + /** * @dev Make deposit and/or choose to close an opened proposal + * - MUST be owner * - MUST account for amount received * - MUST be a proposal that is less than or equal to current proposal * - MUST emit proposals event @@ -151,8 +174,10 @@ interface TokenReserve is ERC4626{ * @param proposal Number of desired proposal * @param amount Token amount being deposited to the reserve * @param close Choose to close the proposal + * @return True for closed proposal */ function proposalClose(address token, uint256 proposal, uint256 amount, bool close) external virtual returns (bool); + /** * @dev Optional accounting for tokens deposited by owner * - MUST be reserve owner @@ -160,7 +185,7 @@ interface TokenReserve is ERC4626{ * NOTE: No shares are issued, funds can not be redeemed. Only withdrawn from proposalOpen * @param token Address of ERC-20 token * @param sender Address of where tokens from - * @param amount Token amount being deposited + * @param amount Token amount being deposited */ function depositReserve(address token, address sender, uint256 amount) external virtual; } @@ -169,21 +194,22 @@ interface TokenReserve is ERC4626{ ## Rationale -This proposal is designed to be a basic implementation of a tokenized reserve interface. Other non specified conditions should be addressed on a case by case basis. Each reserve uses [ERC-20](../EIPS/eip-20.md) standard for shares, and [ERC-4626](../EIPS/eip-4626.md) for the creation of shares. The reserve token can be the underlying token in [ERC-4626](../EIPS/eip-4626.md) or the shares that are created when the underlying token is deposited in the vault. -[ERC-4626](../EIPS/eip-4626.md) is implemented to the reserve to account for user participation. There needs to be a representation for users participating in a proposal within a reserve. With vaults, the implementor could decide how to treat participation based on users entering the vault. For example, a user could be forced not to use the same tokens in multiple proposals to allow shares to be created fairly. Once the underlying token is deposited into the vault for an open proposal those tokens could not be accessible until the proposal is closed. -It is not explicitly enforced that deposited tokens that create shares cannot be withdrawn by the owner of the reserve. On a case by case basis there can be implementions to ensure those tokens are accounted for if needed. +This proposal is designed to be a core implementation of a tokenized reserve interface standard. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses [ERC-20](../ERCS/erc-20.md) standard for shares, and [ERC-4626](../ERCS/erc-4626.md) for the creation of shares. The reserve token can be the underlying token in [ERC-4626](../ERCS/erc-4626.md) or the shares that are created when the underlying token is deposited in the vault. The use +[ERC-4626](../ERCS/erc-4626.md) is implemented to the reserve to represent stakeholders. There MUST to be a representation of interseted parties in the reserve. The implementer could decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple proposals to allow shares to be distributed fairly. Once the underlying token is deposited into the vault for an open proposal, tokens cannot be accessible until the proposal is closed. + +It is not explicitly enforced that deposited tokens that create shares cannot be withdrawn by the owner of the reserve. On a case-by-case basis there can be implementions to ensure those tokens are accounted for if needed. ## Backwards Compatibility -Tokenized reserves are made compatible with [ERC-20](../EIPS/eip-20.md) and [ERC-4626](../EIPS/eip-4626.md). +Tokenized reserves are made compatible with [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). ## Security Considerations 1. Assests are not secured by vaults from owner withdrawal -- Users SHOULD be aware when a reserve can be withdrawn by the owner with no restrictions like requiring an authorized user. Depending on the authorized user implementation, assets MAY still be withdrawn. +- Stakeholders SHOULD be aware when the underlying `asset` can be withdrawn by the owner with no restrictions like requiring an `rAuth`. Depending on the authorizing implementation, `asset` could still be withdrawn. -Implementation -Needs discussion. +A RECOMMENDED implementation: +- The `proposalOpen` SHOULD explictly restrict the transfer of the underlying `asset`. ## Copyright From a22ab1b9066a603ebf739ea6da0c3e52bc289c9a Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 6 Feb 2024 07:05:41 -0500 Subject: [PATCH 3/9] Update erc-7425.md --- ERCS/erc-7425.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index d41bd34f5a..6931358e2f 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -21,14 +21,11 @@ Tokenized vaults store [ERC-20](../ERCS/erc-20.md) tokens that are represented b This specifcation introduces a standard for a on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depsoiting and withdrawing from the vault. The record of transactions for other [ERC-20](../ERCS/erc-20.md) assests should be easily accessicble to any party for auditing. -## Background - In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like, running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets accioted with the reserve as well as its orgin will vary in decentralized envirnoments, so transparent auditing is needed. - ## 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](https://www.ietf.org/rfc/rfc2119.txt) and RFC [8174](https://www.ietf.org/rfc/rfc8174.txt). +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: From 56b302b0f76427adfa79fed4b1271e0431deaf3f Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 6 Feb 2024 23:00:42 -0500 Subject: [PATCH 4/9] Update erc-7425.md --- ERCS/erc-7425.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index 6931358e2f..62bc066ee0 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -72,14 +72,14 @@ interface TokenReserve is ERC4626{ ); /** - * @dev Get time of a deposit made to reserve by owner + * @dev Get time a deposit was made to reserve by owner * @param count Number for deposit count * @return block.timestamp format */ function depositTime(uint256 count) external view returns (uint256); /** - * @dev Get amount deposited to reserve by owner + * @dev Get amount deposited to reserve by owner using optional depositreserve() * @param count Number for deposit count * @return uint256 Amount of an asset that was deposited */ @@ -103,7 +103,7 @@ interface TokenReserve is ERC4626{ function userDeposit(address user, uint256 proposal) external view returns(uint256); /** - * @dev Token used for given proposal + * @dev Token withdrawn for a opened proposal number * - MUST be ERC20 address * @param proposal Proposal number for requested used token * @return Token address @@ -115,17 +115,17 @@ interface TokenReserve is ERC4626{ * @param proposal Proposal number * @return Amount of ERC20 */ - function proposalWithdrew(uint256 proposal) external view returns(uint256); + function proposalWithdrawn(uint256 proposal) external view returns(uint256); /** - * @dev Amount received for given proposal number + * @dev Amount received for closed proposal by owner * @param proposal Proposal number * @return Amount of ERC20 */ - function proposalDeposited(uint256 proposal) external view returns(uint256); + function closeDeposited(uint256 proposal) external view returns(uint256); /** - * @dev Make a deposit to a proposal creating new shares with deposit function from ERC-4626 + * @dev Make a deposit to a proposal creating new shares using deposit function from ERC-4626 * - MUST be opened proposal * - MUST NOT be opened proposal that was closed * NOTE: using the deposit() will cause assets to not be accounted for in a proposal From 0b3e460eb650c4fdf24906475c031b27c0c51c3a Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 14 Feb 2024 11:47:33 -0500 Subject: [PATCH 5/9] Update erc-7425.md --- ERCS/erc-7425.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index 62bc066ee0..ba8ba9230b 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -79,11 +79,12 @@ interface TokenReserve is ERC4626{ function depositTime(uint256 count) external view returns (uint256); /** - * @dev Get amount deposited to reserve by owner using optional depositreserve() + * @dev Get amount deposited to reserve by owner using depositReserve function * @param count Number for deposit count + * @param proposal Optional proposal number to deposit to * @return uint256 Amount of an asset that was deposited */ - function ownerDeposit(uint256 count) external view returns(uint256); + function ownerDeposit(uint256 count, uint256 proposal) external view returns(uint256); /** * @dev Token type deposited to reserve by owner @@ -117,13 +118,6 @@ interface TokenReserve is ERC4626{ */ function proposalWithdrawn(uint256 proposal) external view returns(uint256); - /** - * @dev Amount received for closed proposal by owner - * @param proposal Proposal number - * @return Amount of ERC20 - */ - function closeDeposited(uint256 proposal) external view returns(uint256); - /** * @dev Make a deposit to a proposal creating new shares using deposit function from ERC-4626 * - MUST be opened proposal @@ -138,8 +132,8 @@ interface TokenReserve is ERC4626{ /** * @dev Burn shares, receive 1 to 1 value of shares - * - MUST have closed proposalNumber * - MUST have userDeposit greater than or equal to userWithdrawal + * - SHOULD be only method for withdrawing from ERC4626 vault * @param assets Amount being deposited * @param receiver Address of receiver * @param owner Address of token owner @@ -176,10 +170,10 @@ interface TokenReserve is ERC4626{ function proposalClose(address token, uint256 proposal, uint256 amount, bool close) external virtual returns (bool); /** - * @dev Optional accounting for tokens deposited by owner + * @dev Accounting for tokens deposited by owner * - MUST be reserve owner * - MUST emit depositR event - * NOTE: No shares are issued, funds can not be redeemed. Only withdrawn from proposalOpen + * NOTE: No shares are issued, funds can not be redeemed. Only withdrawn with proposalOpen function * @param token Address of ERC-20 token * @param sender Address of where tokens from * @param amount Token amount being deposited From 5823d5ae714b78fe803c4e99f62862db9eef9a51 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 20 Feb 2024 01:02:17 -0500 Subject: [PATCH 6/9] Update erc-7425.md --- ERCS/erc-7425.md | 135 +++++++++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 62 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index ba8ba9230b..435f0318a0 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -17,11 +17,11 @@ This specification explains a tokenized reserve mechanism standard. Current smar ## Motivation -Tokenized vaults store [ERC-20](../ERCS/erc-20.md) tokens that are represented by shares within vault contracts. Implemenations can follow the [ERC-4626](../ERCS/erc-4626.md) standard to provide basic functionality for depositing, withdrawing and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assests and allow all parties to track performance. +Tokenized vaults store [ERC-20](../ERCS/erc-20.md) tokens that are represented by shares within vault contracts. Implementations can follow the [ERC-4626](../ERCS/erc-4626.md) standard to provide basic functionality for depositing, withdrawing, and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assets and allow all parties to track performance. -This specifcation introduces a standard for a on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depsoiting and withdrawing from the vault. The record of transactions for other [ERC-20](../ERCS/erc-20.md) assests should be easily accessicble to any party for auditing. +This specification introduces a standard for an on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depositing and withdrawing from the vault. The record of transactions for other [ERC-20](../ERCS/erc-20.md) assets should be easily accessible to any party for auditing. -In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like, running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets accioted with the reserve as well as its orgin will vary in decentralized envirnoments, so transparent auditing is needed. +In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets associated with the reserve as well as its origin will vary in decentralized environments, so transparent auditing is needed. ## Specification @@ -30,16 +30,16 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S ### Definitions: - owner: The creator of the reserve - - user: Stakeholders participating proposals + - user: Stakeholders participating in policies - reserve: The assets held on the contract other than underlying token - - proposal: Created by owners to encourage stakeholder participation + - policies: Created by reserve owners to encourage stakeholder participation ### Constructor: - name: ERC-20 token name - ticker: ERC-20 ticker - asset: ERC-4626 underlying ERC-20 address - - rAuth: Authorized user, for cases utilizing more than one owner + - rAuth: Authorized user, for cases utilizing more than one owner/ limiting owner withdrawals - rOwner: Owner of the Reserve ### Interface @@ -52,11 +52,11 @@ import "./ERC4626.sol"; interface TokenReserve is ERC4626{ /** - * @dev Event emitted after a new proposal is created + * @dev Event emitted after a new policy is created */ - event proposals( + event policies( address indexed token, - uint256 indexed proposalNum, + uint256 indexed policyNum, uint256 indexed amount, address recipient ); @@ -72,123 +72,130 @@ interface TokenReserve is ERC4626{ ); /** - * @dev Get time a deposit was made to reserve by owner + * @dev Get time a deposit/withdrawal was made by the owner * @param count Number for deposit count * @return block.timestamp format */ - function depositTime(uint256 count) external view returns (uint256); + function ownerTime(uint256 count) external view returns (uint256); /** - * @dev Get amount deposited to reserve by owner using depositReserve function + * @dev Get amount deposited to reserve by owner * @param count Number for deposit count - * @param proposal Optional proposal number to deposit to + * @param policy The policy number to deposit to * @return uint256 Amount of an asset that was deposited */ - function ownerDeposit(uint256 count, uint256 proposal) external view returns(uint256); + function ownerDeposit(uint256 count, uint256 policy) external view returns(uint256); + + /** + * @dev Amount withdrawn for a opened policy by the owner + * @param policy The policy number + * @return Amount of ERC20 + */ + function ownerWithdrawals(uint256 policy) external view returns(uint256) /** * @dev Token type deposited to reserve by owner * - MUST be an address of ERC20 token - * @param count Number of deposit + * @param count Number of deposit count * @return address Address of ERC20 token */ function tokenDeposit(uint256 count) external view returns(address); /** - * @dev Amount deposited by the user to a proposal for shares + * @dev Amount deposited to a policy for shares * - MUST be an ERC20 token * @param user Address of user - * @param proposal Proposal number the user deposited to + * @param policy The policy number the user deposited to * @return uint256 Amount of ERC20 deposited */ - function userDeposit(address user, uint256 proposal) external view returns(uint256); + function userDeposit(address user, uint256 policy) external view returns(uint256) /** - * @dev Token withdrawn for a opened proposal number - * - MUST be ERC20 address - * @param proposal Proposal number for requested used token - * @return Token address - */ - function proposalToken(uint256 proposal) external view returns(address); + * @dev Amount withdrawn from a policy by the user + * @param user The address of user + * @param policy The policy number for user withdrawal + * @param uint256 Amount of ERC20 + */ + function userWithdrawals(address user, uint256 policy) public view returns(uint256) /** - * @dev Amount withdrawn for given opened proposal number - * @param proposal Proposal number - * @return Amount of ERC20 + * @dev Token type withdrawn for an opened policy by the owner + * - MUST be ERC20 address + * @param policy The policy number for the token used + * @return Token ERC20 address */ - function proposalWithdrawn(uint256 proposal) external view returns(uint256); + function policyToken(uint256 policy) external view returns(address) /** - * @dev Make a deposit to a proposal creating new shares using deposit function from ERC-4626 - * - MUST be opened proposal - * - MUST NOT be opened proposal that was closed - * NOTE: using the deposit() will cause assets to not be accounted for in a proposal + * @dev Make a deposit to a policy creating new shares using deposit function from ERC4626 + * - MUST be opened policy + * - MUST NOT be opened policy that was closed + * - SHOULD be only method to deposit to ERC4626 vault + * NOTE: using the deposit() will cause assets to not be accounted for in a policy (see Security Considerations section) * @param assets Amount being deposited * @param receiver Address of depositor - * @param proposal Number associated proposal - * @return Amount of mint shares + * @param policy The number associated policy + * @return Amount of shares minted */ - function proposalDeposit(uint256 assets, address receiver, uint256 proposal) external virtual returns(uint256); + function policyDeposit(uint256 assets, address receiver, uint256 policy) external virtual returns(uint256) /** - * @dev Burn shares, receive 1 to 1 value of shares + * @dev Burn shares, receive 1 to 1 value of shares using withdraw function from ERC4626 * - MUST have userDeposit greater than or equal to userWithdrawal * - SHOULD be only method for withdrawing from ERC4626 vault * @param assets Amount being deposited * @param receiver Address of receiver * @param owner Address of token owner - * @param proposal Number associated proposal + * @param policy Number associated policy * @return Amount of the asset */ - function proposalWithdraw(uint256 assets, address receiver, address owner, uint256 proposal)external virtual returns(uint256); + function withdrawPolicy(uint256 assets, address receiver, address owner, uint256 policy)external virtual returns(uint256) /** - * @dev Issue new proposal - * - MUST create new proposal number + * @dev Issue new policy + * - MUST create new policy number * - MUST account for amount withdrawn + * - MUST be only method to withdraw ERC20 tokens (excluding underlying ERC4626 token) * - MUST be owner - * - MUST emit proposals event + * - SHOULD emit policies event * @param token Address of ERC-20 token * @param amount Token amount being withdrawn * @param receiver Address of token recipient - * @return Proposal number + * @return The policy number */ - function proposalOpen(address token, uint256 amount, address receiver) external virtual returns (uint256); + function openPolicy(address token, uint256 amount, address receiver) external virtual returns (uint256) /** - * @dev Make deposit and/or choose to close an opened proposal + * @dev Make a deposit and/or close an opened policy * - MUST be owner * - MUST account for amount received - * - MUST be a proposal that is less than or equal to current proposal - * - MUST emit proposals event + * - SHOULD emit policies event * @param token Address of ERC-20 token - * @param proposal Number of desired proposal + * @param policy Number of the desired policy * @param amount Token amount being deposited to the reserve - * @param close Choose to close the proposal - * @return True for closed proposal + * @param close Choose to close the policy + * @return True for closed policy */ - function proposalClose(address token, uint256 proposal, uint256 amount, bool close) external virtual returns (bool); + function closePolicy(address token, uint256 policy, uint256 amount, bool close) external virtual returns (bool) /** * @dev Accounting for tokens deposited by owner * - MUST be reserve owner - * - MUST emit depositR event - * NOTE: No shares are issued, funds can not be redeemed. Only withdrawn with proposalOpen function - * @param token Address of ERC-20 token - * @param sender Address of where tokens from + * - SHOULD emit depositR event + * NOTE: No shares are issued, funds can not be redeemed and no policy is opened. Withdrawnal made with openPolicy function. + * @param token Address of ERC-20 token being deposited + * @param sender Address of token sender * @param amount Token amount being deposited */ - function depositReserve(address token, address sender, uint256 amount) external virtual; + function depositReserve(address token, address sender, uint256 amount) external virtual } ``` ## Rationale -This proposal is designed to be a core implementation of a tokenized reserve interface standard. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses [ERC-20](../ERCS/erc-20.md) standard for shares, and [ERC-4626](../ERCS/erc-4626.md) for the creation of shares. The reserve token can be the underlying token in [ERC-4626](../ERCS/erc-4626.md) or the shares that are created when the underlying token is deposited in the vault. The use -[ERC-4626](../ERCS/erc-4626.md) is implemented to the reserve to represent stakeholders. There MUST to be a representation of interseted parties in the reserve. The implementer could decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple proposals to allow shares to be distributed fairly. Once the underlying token is deposited into the vault for an open proposal, tokens cannot be accessible until the proposal is closed. - -It is not explicitly enforced that deposited tokens that create shares cannot be withdrawn by the owner of the reserve. On a case-by-case basis there can be implementions to ensure those tokens are accounted for if needed. +This proposed standard is designed to be a core implementation of a tokenized reserve interface. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses [ERC-20](../ERCS/erc-20.md) standard for shares, and [ERC-4626](../ERCS/erc-4626.md) for the creation of shares. The reserve token SHOULD be considered as either the underlying `asset` for the [ERC-4626](../ERCS/erc-4626.md) vault or the shares that are created when depositing to the vault. +[ERC-4626](../ERCS/erc-4626.md) is used to create a transparent creation of stakeholders of the reserve. There MUST be a representation of interested parties in the reserve. The implementer can decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple policies to allow shares to be distributed fairly. ## Backwards Compatibility @@ -196,11 +203,15 @@ Tokenized reserves are made compatible with [ERC-20](../ERCS/erc-20.md) and [ERC ## Security Considerations -1. Assests are not secured by vaults from owner withdrawal -- Stakeholders SHOULD be aware when the underlying `asset` can be withdrawn by the owner with no restrictions like requiring an `rAuth`. Depending on the authorizing implementation, `asset` could still be withdrawn. +Tokenized reserves share the some security considerations as [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). + +1. Assests withdrawn by owner are not secured by vaults. +- Stakeholders SHOULD be aware that the underlying `asset` can be withdrawn by the owner with no restrictions or authorizing party, like requiring an `rAuth`. Depending on the authorizing implementation, `asset` may still be withdrawn by the owner. A RECOMMENDED implementation: -- The `proposalOpen` SHOULD explictly restrict the transfer of the underlying `asset`. +- The `openPolicy` MUST explictly restrict the transfer of the underlying `asset`. +- If the underlying asset is apart of the reserve and not the vault, +the reserve MUST provide a method to avoid user `asset` loss. ## Copyright From e3594d7cfadac2aad879a412496002dbfcb8120d Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 20 Feb 2024 01:04:26 -0500 Subject: [PATCH 7/9] Update erc-7425.md --- ERCS/erc-7425.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index 435f0318a0..441a1b12a2 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -76,7 +76,7 @@ interface TokenReserve is ERC4626{ * @param count Number for deposit count * @return block.timestamp format */ - function ownerTime(uint256 count) external view returns (uint256); + function ownerTime(uint256 count) external view returns (uint256) /** * @dev Get amount deposited to reserve by owner @@ -84,7 +84,7 @@ interface TokenReserve is ERC4626{ * @param policy The policy number to deposit to * @return uint256 Amount of an asset that was deposited */ - function ownerDeposit(uint256 count, uint256 policy) external view returns(uint256); + function ownerDeposit(uint256 count, uint256 policy) external view returns(uint256) /** * @dev Amount withdrawn for a opened policy by the owner @@ -99,7 +99,7 @@ interface TokenReserve is ERC4626{ * @param count Number of deposit count * @return address Address of ERC20 token */ - function tokenDeposit(uint256 count) external view returns(address); + function tokenDeposit(uint256 count) external view returns(address) /** * @dev Amount deposited to a policy for shares From 6dc54cf2a7245fdd2b5a32f3fe1b75f3a0c8fc77 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 20 Feb 2024 01:06:03 -0500 Subject: [PATCH 8/9] Update erc-7425.md --- ERCS/erc-7425.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index 441a1b12a2..b849d19d65 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -203,7 +203,7 @@ Tokenized reserves are made compatible with [ERC-20](../ERCS/erc-20.md) and [ERC ## Security Considerations -Tokenized reserves share the some security considerations as [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). +Tokenized reserves share the same security considerations as [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). 1. Assests withdrawn by owner are not secured by vaults. - Stakeholders SHOULD be aware that the underlying `asset` can be withdrawn by the owner with no restrictions or authorizing party, like requiring an `rAuth`. Depending on the authorizing implementation, `asset` may still be withdrawn by the owner. From 0bd3397232b192034f4301108cbc9381c0393959 Mon Sep 17 00:00:00 2001 From: Sam Wilson <57262657+SamWilsn@users.noreply.github.com> Date: Tue, 20 Feb 2024 11:20:42 -0500 Subject: [PATCH 9/9] Update erc-7425.md --- ERCS/erc-7425.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ERCS/erc-7425.md b/ERCS/erc-7425.md index b849d19d65..100285622a 100644 --- a/ERCS/erc-7425.md +++ b/ERCS/erc-7425.md @@ -13,13 +13,13 @@ requires: 20, 4626 ## Abstract -This specification explains a tokenized reserve mechanism standard. Current smart contracts record transactions and are made public. The reserve will implement added functionality allowing stakeholders proactively to audit a contract. Using [ERC-4626](../ERCS/erc-4626.md), stakeholders can create shares to show support for actions in the contract. +This specification explains a tokenized reserve mechanism standard. Current smart contracts record transactions and are made public. The reserve will implement added functionality allowing stakeholders proactively to audit a contract. Using [ERC-4626](./eip-4626.md), stakeholders can create shares to show support for actions in the contract. ## Motivation -Tokenized vaults store [ERC-20](../ERCS/erc-20.md) tokens that are represented by shares within vault contracts. Implementations can follow the [ERC-4626](../ERCS/erc-4626.md) standard to provide basic functionality for depositing, withdrawing, and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assets and allow all parties to track performance. +Tokenized vaults store [ERC-20](./eip-20.md) tokens that are represented by shares within vault contracts. Implementations can follow the [ERC-4626](./eip-4626.md) standard to provide basic functionality for depositing, withdrawing, and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assets and allow all parties to track performance. -This specification introduces a standard for an on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](../ERCS/erc-4626.md), will provide stakeholders representation by depositing and withdrawing from the vault. The record of transactions for other [ERC-20](../ERCS/erc-20.md) assets should be easily accessible to any party for auditing. +This specification introduces a standard for an on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of [ERC-4626](./eip-4626.md), will provide stakeholders representation by depositing and withdrawing from the vault. The record of transactions for other [ERC-20](./eip-20.md) assets should be easily accessible to any party for auditing. In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets associated with the reserve as well as its origin will vary in decentralized environments, so transparent auditing is needed. @@ -194,16 +194,16 @@ interface TokenReserve is ERC4626{ ## Rationale -This proposed standard is designed to be a core implementation of a tokenized reserve interface. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses [ERC-20](../ERCS/erc-20.md) standard for shares, and [ERC-4626](../ERCS/erc-4626.md) for the creation of shares. The reserve token SHOULD be considered as either the underlying `asset` for the [ERC-4626](../ERCS/erc-4626.md) vault or the shares that are created when depositing to the vault. -[ERC-4626](../ERCS/erc-4626.md) is used to create a transparent creation of stakeholders of the reserve. There MUST be a representation of interested parties in the reserve. The implementer can decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple policies to allow shares to be distributed fairly. +This proposed standard is designed to be a core implementation of a tokenized reserve interface. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses [ERC-20](./eip-20.md) standard for shares, and [ERC-4626](./eip-4626.md) for the creation of shares. The reserve token SHOULD be considered as either the underlying `asset` for the [ERC-4626](./eip-4626.md) vault or the shares that are created when depositing to the vault. +[ERC-4626](./eip-4626.md) is used to create a transparent creation of stakeholders of the reserve. There MUST be a representation of interested parties in the reserve. The implementer can decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple policies to allow shares to be distributed fairly. ## Backwards Compatibility -Tokenized reserves are made compatible with [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). +Tokenized reserves are made compatible with [ERC-20](./eip-20.md) and [ERC-4626](./eip-4626.md). ## Security Considerations -Tokenized reserves share the same security considerations as [ERC-20](../ERCS/erc-20.md) and [ERC-4626](../ERCS/erc-4626.md). +Tokenized reserves share the same security considerations as [ERC-20](./eip-20.md) and [ERC-4626](./eip-4626.md). 1. Assests withdrawn by owner are not secured by vaults. - Stakeholders SHOULD be aware that the underlying `asset` can be withdrawn by the owner with no restrictions or authorizing party, like requiring an `rAuth`. Depending on the authorizing implementation, `asset` may still be withdrawn by the owner.