Multiwrap design document.
This is a live document that explains what the thirdweb
Multiwrap smart contract is, how it works and can be used, and why it is designed the way it is.
The document is written for technical and non-technical readers. To ask further questions about thirdweb's
Multiwrap contract, please join the thirdweb discord or create a github issue.
The thirdweb Multiwrap contract lets you wrap arbitrary ERC20, ERC721 and ERC1155 tokens you own into a single wrapped token / NFT.
Multiwrap contract is meant to be used for bundling up multiple assets (ERC20 / ERC721 / ERC1155) into a single wrapped token, which can then be unwrapped in exchange for the underlying tokens.
The single wrapped token received on bundling up multiple assets, as mentioned above, is an ERC721 NFT. It can be transferred, sold on any NFT Marketplace, and generate royalties just like any other NFTs.
Multiwrap product should work
A token owner should be able to wrap any combination of n ERC20, ERC721 or ERC1155 tokens as a wrapped NFT. When wrapping, the token owner should be able to specify a recipient for the wrapped NFT. At the time of wrapping, the token owner should be able to set the metadata of the wrapped NFT that will be minted.
The wrapped NFT owner should be able to unwrap the NFT to retrieve the underlying tokens of the wrapped NFT. At the time of unwrapping, the wrapped NFT owner should be able to specify a recipient for the underlying tokens of the wrapped NFT.
Multiwrap contract creator should be able to apply the following role-based restrictions:
- Restrict what assets can be wrapped on the contract.
- Restrict which wallets can wrap tokens on the contract.
- Restrict what wallets can unwrap owned wrapped NFTs.
Core parts of the
- A token owner should be able to wrap any combination of n ERC20, ERC721 or ERC1155 tokens as a wrapped token.
- A wrapped token owner should be able to unwrap the token to retrieve the underlying contents of the wrapped token.
Why we're building
Multiwrap for cases where an application wishes to bundle up / distribute / transact over n independent tokens all at once, as a single asset. This opens up several novel NFT use cases.
For example, consider a lending service where people can take out a loan while putting up an NFT as a collateral. Using
Multiwrap, a borrower can wrap their NFT with some ether, and put up the resultant wrapped ERC721 NFT as collateral on the lending service. Now, the borrower's NFT, as collateral, has a floor value.
Multiwrapcontract itself is an ERC721 contract.
It lets you wrap arbitrary ERC20, ERC721 or ERC1155 tokens you own into a single wrapped token / NFT. This means escrowing the relevant ERC20, ERC721 and ERC1155 tokens into the
Multiwrap contract, and receiving the wrapped NFT in exchange.
This wrapped NFT can later be 'unwrapped' i.e. burned in exchange for the underlying tokens.
To wrap multiple ERC20, ERC721 or ERC1155 tokens as a single wrapped NFT, a token owner must:
- approve the relevant tokens to be transferred by the
- specify the tokens to be wrapped into a single wrapped NFT. The following is the format in which each token to be wrapped must be specified:
Each token in the bundle of tokens to be wrapped as a single wrapped NFT must be specified to the
Multiwrap contract in the form of the
Token struct. The contract handles the respective token based on the value of
tokenType provided. Any incorrect values passed (e.g. the
totalAmount specified to be wrapped exceeds the token owner's token balance) will cause the wrapping transaction to revert.
Multiple tokens can be wrapped as a single wrapped NFT by calling the following function:
Unwrapping the wrapped NFT
The single wrapped NFT, received on wrapping multiple assets as explained in the previous section, can be unwrapped in exchange for the underlying assets.
A wrapped NFT can be unwrapped either by the owner, or a wallet approved by the owner to transfer the NFT via
approve ERC721 functions.
When unwrapping the wrapped NFT, the wrapped NFT is burned.****
A wrapped NFT can be unwrapped by calling the following function:
What does Type (Switch / !Switch) mean?
- Switch: If
ROLE, then the
ROLErestrictions don't apply.
ROLErestrictions always apply.