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.

The 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.

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.

The 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.

• 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.

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.

The 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 Multiwrap contract.
• 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:

/// @notice The type of assets that can be wrapped.
enum TokenType { ERC20, ERC721, ERC1155 }
 
struct Token {
    address assetContract;
    TokenType tokenType;
    uint256 tokenId;
    uint256 totalAmount;
}

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:

function wrap(
    Token[] memory tokensToWrap,
    string calldata uriForWrappedToken,
    address recipient
) external payable returns (uint256 tokenId);

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 setApprovalForAll or approve ERC721 functions.

When unwrapping the wrapped NFT, the wrapped NFT is burned.****

A wrapped NFT can be unwrapped by calling the following function:

function unwrap(
    uint256 tokenId,
    address recipient
) external;

What does Type (Switch / !Switch) mean?

• Switch: If address(0) has ROLE, then the ROLE restrictions don't apply.
• !Switch: ROLE restrictions always apply.