Loot Box

In this guide we'll teach you what are loot boxes, where you can use them and how they work.

Straight to the code!

Check out the in-depth guide here to see the workflow of the loot box contract.

Deploy

sdk.lootBox.deploy(opts)

Deploy a loot box smart contract

opts.wallet (Wallet)(required) - wallet to sign the transaction with
opts.protocol (string) (required) - EVMs only.
opts.name (string) (required) - name of the loot box token.
opts.symbol (string) (required) - symbol of the loot box token.
opts.contractURI (string) - URI pointing to the loot box token metadata (PS: it uses the same standard as ERC-1155).
opts.trustedForwarders (string[]) - array of addresses to be set as trusted forwarders (custom gasless trusted forwarder addresses).
opts.royaltyRecipient (string) - address to receive the royalties (if any).
opts.royaltyBps (string) - Royalty basis points (e.g: 250 equals 2.5% and 10000 means 100%).

Examples:

let { hash } = await sdk.lootBox.deploy({
    protocol: 'BSC', // Only EVM protocols are supported at the moment
    wallet,
    name: 'My Lootbox!',
    symbol: 'ML'
  });

Approve

sdk.lootBox.approve(opts)

Approve the loot box contract to use your tokens as rewards.

opts.wallet (Wallet)(required) - wallet to sign the transaction with
opts.protocol (string) (required) - EVMs only.
opts.lootBoxAddress (string) (required) - address of the loot box contract.
opts.tokenAddress (string) (required) - address of the token to be used as a prize.
opts.tokenType ("ERC721" | "ERC1155" | "ERC20") - type of the token that is being added as a prize.
opts.tokenId (string) - tokenId of the content (if content is an ERC-721 token).
opts.amount (string) - amount of tokens to be approved (if content is an ERC20 token).

Examples:

await sdk.lootBox.approve({
    wallet,
    lootBoxAddress:'0xa75b...15d8',
    protocol: 'BSC',
    tokenAddress: '0xa4...E17', // Address of the token or collection
    tokenType: 'ERC1155', // 'ERC20','ERC721' or 'ERC1155'
    tokenId, // Only for 'ERC721'
    amount // Only for 'ERC20'
  });

Create

sdk.lootBox.create(opts)

Creates the loot boxes

opts.wallet (Wallet)(required) - wallet to sign the transaction with
opts.protocol (string) (required) - EVMs only.
opts.lootBoxAddress (string) (required) - address of the loot box contract.
opts.openStartTimestamp (string) (required)- start time from which loot boxes can be opened (PS: Unix timestamp).
opts.recipient (string) (required)- recipient address that will receive the boxes once they're minted.
opts.rewardUnits (string) - array that denotes the amount of units of each reward. (e.g: If one of the rewards is 10 ERC-20 tokens, rewardUnits for that content should be 10. For NFTs this will probably be 1)
opts.amountDistributedPerOpen (string) - amount of rewards to be selected as prizes for each winner.
opts.lootBoxURI (string) - loot box URI.
opts.contents (LootBoxContent[]) (required) - array of contents to be added as prizes.
- LootBoxContent.tokenAddress (string) - address of the token to be included as a prize
- LootBoxContent.tokenId (string) - tokenId of the token to be included as a prize (if the prize is an NFT)
- LootBoxContent.tokenType ("ERC721" | "ERC1155" | "ERC20") - type of the token that is being added as a prize.
- LootBoxContent.amount (string) - amount of tokens to be approved (if content is an ERC20 or ERC1155)

Examples:

const { hash: creationHash } = await sdk.lootBox.createLootBox({
    wallet,
    contents: [{ tokenAddress, tokenId: '0', tokenType: 'ERC1155', amount: '100' }],
    lootBoxAddress:'0xa75b...15d8',
    openStartTimestamp: '0',
    protocol:'BSC',
    recipient: wallet.address
})

Open

sdk.lootBox.open(opts)

Opens a loot box.

opts.wallet (Wallet)(required) - wallet to sign the transaction with
opts.protocol (string) (required) - EVMs only.
opts.lootBoxId (string) - (required) - ID of the loot box to be opened
opts.lootBoxAddress (string) (required) - address of the loot box contract.

Examples:

const { hash: openingHash } = await sdk.lootBox.openLootBox({
    lootBoxAddress:'0xa75b...15d8',
    wallet,
    protocol: 'BSC',
    lootBoxId: '0'
})

Get Contents

sdk.lootBox.getLootBoxContent(opts)

Gets the possible contents of a loot box.

opts.protocol (string) (required) - EVMs only.
opts.lootBoxId (string) - (required) - ID of the loot box to be opened
opts.lootBoxAddress (string) (required) - address of the loot box contract.

const contents = await sdk.lootBox.getLootBoxContent({
    lootBoxAddress:'0xa75b...15d8',
    protocol: 'BSC',
    lootBoxId: '0'
})

What are loot boxes?

Loot Boxes are a structure designed to bundle several tokens into a single "box" that can be opened in order to retrieve a random reward. For example, you can store many different NFTs in a loot box and randomize the distribution for the users who open these boxes.

How can I use loot boxes in my business?

There are many different use cases for loot boxes. The concept of randomized rewards is prevalent in the gaming industry, where the loot box is a virtual item that can be redeemed in order to receive other randomly selected virtual goods. It is also highly applicable in any area that features collectibles, where instead of directly giving the user a certain collectible item, they have to roll their chance of getting the item they wanted. Yet another popular use case of loot boxes is as a reward mechanism.

How do loot boxes work?

The high-level workings of the loot box mechanism are very simple:

The owner of the system must deploy the smart contract that manages the boxes;
The owner gives the smart contract access to transfer all the possible prizes;
The owner creates the loot boxes;
Loot boxes are sold or distributed to users;
Users open their boxes and receive a random reward;

Technical guide

Step 1

The first prerequisite you will need is the creation of an account and a Project (API Key) on the Cryptum Dashboard.

Step 2

With a valid Cryptum API Key, you can then instantiate the SDK as follows:

const CryptumSdk = require('cryptum-sdk')

const sdk = new CryptumSdk({
  environment: 'testnet',  // 'testnet', 'mainnet'
  apiKey: "YOUR-API-KEY-HERE",
})

Step 3

Now you must instantiate the wallet that will be used throughout the application:

const wallet = await sdk.wallet.generateWallet({
    protocol: 'BSC', // Or any other protocol ('ETHEREUM','CELO','POLYGON'...)
    mnemonic: 'lorem ipsum dolor sit amet consectetur adipiscing.....',
    derivation: { account: 0, address: 0 }
})

Make sure the wallet has sufficient funds to pay for the transactions.

Step 4

Now that our environment is ready, we can start the workflow described in the "How Loot Boxes Work" section. The first step is to deploy the loot box smart contract:

let { hash } = await sdk.lootBox.deploy({
    protocol: 'BSC', // Only EVM protocols are supported at the moment
    wallet,
    name: 'My Lootbox!',
    symbol: 'ML'
  });

Step 5

Right now our contract has been deployed, but we don't know its address just yet - only the address of the transaction that created the contract. In order to fetch the contract's address (and not just the transaction address) we must do the following:

const { address: lootBoxAddress } = await sdk.transaction.getProxyAddressByHash({
    hash,
    protocol
});

Step 6

The next step is to approve the contract to use all the tokens that will be used as rewards.

await sdk.lootBox.approve({
    wallet,
    lootBoxAddress, // This variable was created in the previous step
    protocol: 'BSC',
    tokenAddress: '0xa4...E17', // Address of the token or collection
    tokenType: 'ERC1155', // 'ERC20','ERC721' or 'ERC1155'
    tokenId, // Only for 'ERC721'
    amount // Only for 'ERC20'
  });

Step 7

Now we can finally create our loot boxes:

const { hash: creationHash } = await sdk.lootBox.createLootBox({
    wallet,
    contents: [{ tokenAddress, tokenId: '0', tokenType: 'ERC1155', amount: '100' }],
    lootBoxAddress,
    openStartTimestamp: '0',
    protocol,
    recipient: wallet.address
})

Note that the resulting packs are ERC-1155 NFTs themselves.

The "contents" variable is an array of all the prizes. They can include all types of tokens (ERC-20/721/1155) simultaneously.

Step 8

Right now the loot boxes are created and ready to be opened, however, it's important to note that the original wallet currently holds all the boxes. Usually, this is where you'd distribute the boxes (or sell them). Since the boxes are NFTs, see how you can transfer them in our NFTs section.

Step 9

To open the boxes, the following function should be used:

const { hash: openingHash } = await sdk.lootBox.openLootBox({
    lootBoxAddress,
    wallet,
    protocol: 'BSC',
    lootBoxId: '0' // ID of the loot box to be opened
})

The full loot box documentation is available at:

https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/lootbox.mdgithub.com

PreviousDeploy custom Smart Contracts NextFeatures and credits

Last updated 10 months ago