Deck ERC721

Search…
Deck ERC721
The ERC721 Deck contract allows for the wrapping of ERC721s as Items, and for the burning of Deck-items ERC721s to retrieve the original tokens.
​Deck ERC721 contract code - Deck ERC721 address​
Wrap
Before wrapping an ERC721 token as a Deck Item, make sure it is a standard ERC721. To be standard, it must:
integrate the standard IERC721 interface
have 0 decimals
have a transferFrom/safeTransferFrom function that allows for it to be wrapped as a Deck Item
have a transferFrom/safeTransferFrom/transfer function that allows it to be retrieved by wrapping a Deck Item
An ERC721 can be wrapped in two ways:
1.By using the mintItems function (only for ERC721s that have a transferFrom function)
2.By using the safeTransferFrom function to send the token to the ERC721 Deck Wrapper contract, which implements onERC721Received.
When wrapped, all ERC721s of the same token address generate the same shared Deck Item id. So, for example, if you wrap two Bored Apes, 2e18 Bored Ape Deck Items are minted, and they share the same Deck Item id.
mintItems
1
function mintItems(CreateItem[] calldata createItemsInput, bool[] calldata reserveArray) external returns(uint256[] memory itemIds);
Copied!
This function has two inputs:
struct CreateItem -> data for wrapping the ERC721
bool[] reserveArrays -> boolean value that expresses whether the wrap is to be reserved (true) or unreserved (false). More on this below.
The lengths of CreateItem and reserveArrays must be the same; each CreateItem struct must correspond to its sequentially equivalent value in reserveArrays.
For each ERC721 being wrapped, a CreateItem struct must be passed as follows: 
struct Header -> composed of address host, string name, string symbol and string uri. Pass this as empty; these parameters are automatically populated by the contract. See here for more info.
bytes32 collection -> encoded ERC721 address of the token being wrapped.
uint256 id -> id of the original ERC721 token being wrapped.
address[] accounts -> receiver address(es) of the Deck Item. Pass as address(0) to set as msg.sender, or pass as any other address(es).
uint256[] amounts -> 1e18 (i.e. 100000000000000000000000000).
Regarding accounts and amounts, 1e18 can be split to multiple receivers. The sum must be 1e18, and the accounts array and amounts lengths must be equal; each accounts value must correspond to its sequentially equivalent value in amounts.
Example
2 Bored Apes are wrapped as Deck Items; the first reserved, the second unreserved.
CreateItem1 
Header -> - host: 0x00.. , - name: " ", symbol: " ", uri: " " 
collection -> 0x000000000000000000000000bc4ca0eda7647a8ab7c2061c2e118a18a936f13d 
id -> 1630 
accounts -> 0x998093DF3d61dDDae8F4a84e02e12c78b3751cC4 
amounts -> 100000000000000000000000000
CreateItem2: 
Header -> - host: 0x00.. , - name: " ", symbol: " ", uri: " " 
collection -> 0x000000000000000000000000bc4ca0eda7647a8ab7c2061c2e118a18a936f13d 
id -> 6724 
accounts -> 0x82465CB46506563f66285f18da7adD332e813A42 
amounts -> 100000000000000000000000000
reserveArray: [true, false]
Using the mintItems function, multiple ERC721s of different token addresses can be wrapped in a single transaction by passing multiple CreateItem structs at once.
The mintItems function returns the created itemIds.
onERC721Received
An ERC721 can also be wrapped by using the safeTransferFrom function to send it to the ERC721 Deck Wrapper contract, which calls the onERC721Received function. 
The data parameter of safeTransferFrom must contain the following encoded parameters:
Uint256[] values -> represents the amount of Deck Items (in 18 decimals) to send to each receiver address. 
Address[] receivers -> addresses that will receive the Deck Item. 
The lengths of values[] and receivers[]  must be the same; each value in values[] must correspond to its sequentially equivalent value in receivers[].
Bool reserve -> boolean value that expresses whether the token wrap must be reserved (true) or unreserved (false). More on this below.
values and receivers work in the same way as the amounts and accounts parameters of the mintItems function.
Example: 
1 Gods Unchained card (id 81046035) is sent to be wrapped as a Deck Item with a reservation to the ERC721 Deck Wrapper contract, using safeTransferFrom with the following encoded data:
Uint256[] values -> 100000000000000000000000000 
Address[] receivers -> 0x82465CB46506563f66285f18da7adD332e813A42 
Bool reserve -> true
Reserve
When an ERC721 is wrapped as a Deck Item with a reservation, only the address that wrapped it (i.e. the msg.sender of the mintItems/safeTransferFrom function) can unwrap the Deck Item and retrieve it for the following 10 days (in blocks).

A reservation is for a single ERC721 token.
Each reservation (ReserveData) corresponds to a struct:
1
struct ReserveData {
2
    address unwrapper;
3
    uint256 timeout;
4
}
Copied!
address unwrapper -> msg.sender of the mintItems/safeTransferFrom function.
uint256 timeout -> blocks for which the token is reserved. Equal to block.number + reserveTimeInBlocks, where reserveTimeInBlocks is the number of blocks that are estimated to correspond to 10 days.
If, at any time during the reservation period, the unwrapper address transfers the Deck Item to another account, that account will be unable to unwrap it until the end of the 10 day reservation period, at which point it becomes unreserved and can be unwrapped by anyone.
Unlock Reservation

A reservation can be ended without having to unwrap the token, by using the unlockReserves function:
1
function unlockReserves(address[] calldata tokenAddresses, uint256[] calldata tokenIds) external;
Copied!
address[] tokenAddress -> address of the original ERC721 to unlock.
uint256[] tokenIds -> id of the original ERC721 to unlock.
unlockReserves can be used to unlock multiple reservations at once.
Unwrap
The unwrapping of Deck Items to retrieve the wrapped ERC721s can be done either in single mode, by using the burn function, or in batch mode, by using the burnBatch function. 
These functions can be called by the Deck Item holder or by an approved operator address.
Burn
1
function burn(address account, uint256 itemId, uint256 amount, bytes memory data) override(Item, ItemProjection) public
Copied!
address account -> address of the Deck Item holder.
uint256 itemId -> id of the Deck Item to burn.
uint256 amount -> amount of the Deck Item to burn. 
bytes data -> data in bytes format that must contain the following encoded parameters:
      - address tokenAddress -> token address of the wrapped ERC721.
      - uint256 tokenId -> id of the wrapped ERC721.
      - address receiver -> address that will receive the wrapped ERC721. Pass as address(0) to set as msg.sender, or pass as another address.
      - bytes payload -> eventual optional data to perform a safeTransferFrom.
      - bool safe -> boolean parameter to perform either a safeTransferFrom (true) or a transferFrom (false).
      - bool withData -> boolean parameter to perform a safeTransferFrom either with data (true) or without data (false). In the first case, the payload is executed as data.
Example:
1 (in 18 decimals) Bored Ape Deck Item is burned to retrieve Bored Ape 1630. 
account -> 0x998093DF3d61dDDae8F4a84e02e12c78b3751cC4
itemId -> id of the Bored Ape Deck Item; for example, 553791398095120659341456634
amount -> 100000000000000000000000000
data -> data = web3.eth.abi.encodeParameters( ["address", "uint256", "address", "bytes", "bool", "bool"], ["0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "1630", "0x998093DF3d61dDDae8F4a84e02e12c78b3751cC4", "0x", false, false] );
burnBatch
1
function burnBatch(address account, uint256[] calldata itemIds, uint256[] calldata amounts, bytes memory data) override(Item, ItemProjection) public
Copied!
Using burnBatch, you can unwrap multiple Deck Items (even if they are of different Decks) at once. burnBatch can be called by the Deck Item holder or by an approved operator address.
The parameters are the same as those of the burn function, but with the following differences:
uint256[] itemId and uint256[] amount-> arrays of values, allowing you to unwrap multiple tokens at once.
bytes data ->the data parameter in bytes format is an encoded value that represents a bytes[] (one for each Item involved in the operation) containing the six parameters explained  above in the burn section (tokenAddress, tokenId, receiver, payload, safe and withData).
Deck Items With a Total Supply <=1
Unwrap
If the total supply of a Deck Item ranges from 0.51 to 1 (in 18 decimals), the ERC721 can be unwrapped by burning an amount of Deck Items between 0.51 and 1 in 18 decimals. 
This is contrast to the typical situation where the total supply >1, in which case 1e18 Deck Items must always be burned for each ERC721 to unwrap.
Examples:
1)
Wrapped ERC721
Bored Ape id 1122 (unreserved)
Bored Ape Deck Items totalSupply
0.9e18
A holder of the token's Deck Item can unwrap the Bored Ape (id 1122) by burning at least 0.51e18 of the Deck Item.
2)
Wrapped ERC721
Bored Ape id1122, Bored Ape id 2233 (unreserved)
Bored Ape Deck Items totalSupply
0.6e18
A holder of the token's Deck Item can unwrap one of the two Bored Apes by burning at least 0.51e18 of the Deck Item.
If the total supply of a Deck Item ranges from 0 to 0.51, no one can unwrap the ERC721, because the Deck Item's totalSupply is <0.51.
Wrap
When an ERC721 is wrapped and the Deck Item totalSupply is <1, 1e18-Deck Item total supply is obtained, and that amount must be passed in the amounts parameter of the mintItems/safeTransferFrom function when the ERC721 is wrapped again.
Examples:
1)
Bored Ape Deck Items totalSupply
0.3e18
When you wrap your Bored Ape, you obtain 0.7e18 of a Bored Ape Deck Item, and must pass 0.7e18 as amounts parameter of mintItems/safeTransferFrom.
2)
Bored Ape Deck Items totalSupply
0.1e18
When you wrap your Bored Ape, you obtain 0.9e18 of a Bored Ape Deck Item, and must pass 0.9e18 as amounts parameter of mintItems/safeTransferFrom.
Why Could a Deck Item's Total Supply Be <=1?
There are two main reasons.
1.An address is either the first to wrap or the last to unwrap an ERC721 as a Deck Item, and as a result the Deck Item's totalSupply is equal to 1e18.
2.Holders of a Deck Item burned some of them using the burn function of the Interoperable Item Interface (ERC20 face of the Item). Recall that an Item has two faces, allowing it to work simultaneously as an ERC1155 (using its Main Interface) and as an ERC20 (using its Interoperable Interface).