ERC-7527 Function-oracle AMM token wrapping (Token Bound Function Oracle AMM)
Draft · Vaults & DeFi · created 2023-09-03
A standard for wrapping ERC-20 tokens or ETH into an NFT, and unwrapping an NFT back into tokens. A function-oracle AMM built into the contract automatically sets the mint and burn prices.
Why it is needed
Because each NFT is a unique token, it is hard to find a trading counterparty, and liquidity tends to be scarce. Even if you want to sell, you have to wait until a buyer appears. In the conventional decentralized exchange model, external liquidity providers (LPs) deposit tokens into a pool to supply liquidity, but if they suddenly withdraw, the liquidity available in the market shrinks and causes large volatility. This standard builds a function oracle into the contract that quotes a price using a predetermined mathematical formula, allowing tokens to be converted into an NFT and back at a fixed price without needing a trading counterparty. Liquidity is continuously replenished internally through participants' wraps and unwraps, reducing reliance on external liquidity providers and the volatility risk from their sudden departure.
What to implement
receive() external payable;: Allows an Agency account to receive ETH. Logic can be added to restrict the conditions under which it is received.event Wrap(address indexed to, uint256 indexed tokenId, uint256 premium, uint256 fee);: Records the recipient, token ID, premium, and fee when a token is wrapped into an NFT.event Unwrap(address indexed to, uint256 indexed tokenId, uint256 premium, uint256 fee);: Records the recipient, token ID, premium, and fee when an NFT is unwrapped.function iconstructor() external;: An instance initialization function present on both Agency and App. It initializes and validates configuration parameters and is called automatically when deployed via a factory.function wrap(address to, bytes calldata data) external payable returns (uint256);: Receives the currency and mints a new NFT, sending it to `to`. Returns the identifier of the new NFT.function unwrap(address to, uint256 tokenId, bytes calldata data) external payable;: Burns the NFT with `tokenId` and sends currency to `to` in exchange.function getStrategy() external view returns (address app, Asset memory asset, bytes memory attributeData);: Returns the Agency's strategy, including the bound App address, asset configuration, and attribute data.function getWrapOracle(bytes memory data) external view returns (uint256 premium, uint256 fee);: Calculates and returns the premium and fee for wrapping.function getUnwrapOracle(bytes memory data) external view returns (uint256 premium, uint256 fee);: Calculates and returns the premium and fee for unwrapping.function description() external view returns (string memory);: An optional function. Returns a description of the Agency, such as how the oracle computes prices; other contracts must not assume this value exists.function getMaxSupply() external view returns (uint256);: Returns the maximum supply of NFTs that the App can mint.function getName(uint256 id) external view returns (string memory);: Returns the name of the NFT with identifier `id`.function getAgency() external view returns (address payable);: Returns the address of the Agency bound to this App.function setAgency(address payable agency) external;: Sets the Agency to be bound to this App.function mint(address to, bytes calldata data) external returns (uint256);: Mints an NFT to `to`. Restricted by onlyAgency, so only the bound Agency can call it, and the token ID can be specified via `data`.function burn(uint256 tokenId, bytes calldata data) external;: Burns the NFT with `tokenId`. Likewise, only the bound Agency can call it.function deployWrap(AgencySettings calldata agencySettings, AppSettings calldata appSettings, bytes calldata data) external returns (address, address);: A function of the optional Factory interface that deploys clones of Agency and App together, initializes both, and returns the addresses of the two instances.
In depth
The three interfaces and their mutual binding
The standard consists of three interfaces: Agency, App, and Factory. Agency and App can be implemented as the same contract or as separate contracts, but if implemented separately they must be mutually bound and must not be upgradable after initialization. App must implement the onlyAgency() modifier and apply it to mint and burn, so that minting and burning only take effect when called through the bound Agency. Agency's implementation of onlyApp() is optional. Agency serves as the single entry point for all mint and burn transfers. The Rationale explains that the two contracts should be implemented so that each is the other's sole owner.
Behavior of wrap and mint
When wrap is executed, the pre-set strategy parameters are passed to getWrapOracle to obtain the current premium and fee. The premium is transferred to the Agency instance, and the fee determined by mintFeePercent is transferred to feeRecipient. App then mints the NFT to the user's address. The premium that enters the Agency cannot move except through the unwrap process, and executing wrap is the only trigger that causes a mint. A unique tokenId must be generated for each wrap, and this ID serves as both the verification means at unwrap time and the token's sole proof. The token ID can be specified via the mint function's data parameter.
Behavior of unwrap and burn
Only the NFT's owner or an approved address can unwrap. When unwrap is executed, the strategy parameters are passed to getUnwrapOracle to read the current premium and fee. App burns the NFT, and the premium minus the fee determined by burnFeePercent is sent to the user's address, with the fee going to feeRecipient. Executing unwrap is the only trigger that causes a burn. The reference implementation's wrap function checks that the total supply increased by exactly 1 after minting, to prevent reentrancy.
Function oracles and pricing
getWrapOracle and getUnwrapOracle compute the premium and fee on-chain based on parameters and mathematical formulas defined in the function, and report them. This allows direct trading against the pool without needing to match a counterparty. These functions are not only used during the wrap and unwrap process; other contracts, such as lending contracts, can also call them to obtain a price. Function oracles based on both on-chain and off-chain parameters can be supported, but using only on-chain parameters is recommended for consensus on on-chain reality. The reference implementation computes the premium as basePremium + sale amount x basePremium / 100, and the fee as premium x fee rate / 10000.
The Asset struct and currency types
Agency's configuration is held in the Asset struct. currency is the address of the fungible token, and 0 denotes ETH. basePremium is the base premium, feeRecipient is the fee recipient address, and mintFeePercent and burnFeePercent are the mint and burn fee rates respectively. Within a single system, an Asset can define only one currency as its fungible token, but a wide range of fungible tokens, including ETH and ERC-20, can be supported. Implementers can initialize Agency by freely setting the currency, initial price, fee recipient address, fee rate, and so on.
Factory deployment and initialization procedure
The Factory interface is optional and is useful when Agency and App need to be deployed repeatedly. deployWrap creates clones of both implementations, binds them together, and initializes them. The immutableData in AgencySettings and AppSettings is stored in the code region of the generated proxy contract, and if initData is not empty, the proxy is called with that data. initData is mainly used for calling an initialization function that takes parameters, while iconstructor is used for validating setting parameters and for parameterless initialization. When deployed via Factory, the iconstructor of both contracts is called automatically. Users can combine different Agency implementations and App implementations through Factory to create a variety of products.
Differences from existing mint/burn extensions
ERC-5679 proposed the IERC5679Ext721 interface to consistently extend minting and burning for ERC-721. This standard's IERC7527App uses mint instead of safeMint, for backward compatibility with contracts that do not implement ERC721TokenReceiver. Also, for the safety and uniqueness of the binding, the burn caller must be the contract address of the bound Agency, so unlike IERC5679Ext721 the burn function does not have a _from parameter. Meanwhile, ERC7527App must inherit name from the ERC721Metadata interface.
Proposal status
This proposal is still in Draft status. The specification and interfaces may change, so it is advisable to check the latest source text before implementing.
Things to watch out for
- Checking access control: You should verify that the onlyAgency() and onlyApp() modifiers are correctly implemented and applied.
- Reviewing the function strategy: You should review the function strategy configured in the contract.
- Reentrancy attack: You should check whether the contract is exposed to re-entrancy attacks.
- Ensuring unwrap is possible: You should verify that every NFT can be unwrapped at the premium computed by the FOAMM.