# Loot Box

<details>

<summary><mark style="color:purple;">Straight to the code!</mark></summary>

Check out the in-depth guide [here](https://doc.cryptum.io/main/for-developers/sdk-integration-guides/loot-boxes) 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](https://github.com/blockforce-official/cryptum-sdk/blob/master/protocols.md#ethereum-based-blockchains-evms).
* `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:

```javascript
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](https://github.com/blockforce-official/cryptum-sdk/blob/master/protocols.md#ethereum-based-blockchains-evms).
* `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:

```javascript
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](https://github.com/blockforce-official/cryptum-sdk/blob/master/protocols.md#ethereum-based-blockchains-evms).
* `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:

```javascript
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](https://github.com/blockforce-official/cryptum-sdk/blob/master/protocols.md#ethereum-based-blockchains-evms).
* `opts.lootBoxId` (string) - (**required**) - ID of the loot box to be opened
* `opts.lootBoxAddress` (string) (**required**) - address of the loot box contract.

Examples:

```javascript
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](https://github.com/blockforce-official/cryptum-sdk/blob/master/protocols.md#ethereum-based-blockchains-evms).
* `opts.lootBoxId` (string) - (**required**) - ID of the loot box to be opened
* `opts.lootBoxAddress` (string) (**required**) - address of the loot box contract.

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

</details>

### **What are loot boxes?** <a href="#what-is-a-nft-and-what-can-i-do-with-that" id="what-is-a-nft-and-what-can-i-do-with-that"></a>

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?** <a href="#how-can-i-use-nfts-into-my-business" id="how-can-i-use-nfts-into-my-business"></a>

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?** <a href="#how-can-i-use-nfts-into-my-business" id="how-can-i-use-nfts-into-my-business"></a>

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

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

### **Technical guide** <a href="#how-can-i-use-nfts-into-my-business" id="how-can-i-use-nfts-into-my-business"></a>

<mark style="color:purple;">**Step 1**</mark>

The first prerequisite you will need is the creation of an **account** and a **Project (API Key**) on the [Cryptum Dashboard](https://dashboard.cryptum.io).

<mark style="color:purple;">**Step 2**</mark>

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

```javascript
const CryptumSdk = require('cryptum-sdk')

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

<mark style="color:purple;">**Step 3**</mark>

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

```javascript
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 }
})
```

{% hint style="info" %}
*Make sure the wallet has sufficient funds to pay for the transactions.*
{% endhint %}

<mark style="color:purple;">**Step 4**</mark>

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:

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

<mark style="color:purple;">**Step 5**</mark>

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:

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

<mark style="color:purple;">**Step 6**</mark>

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

```javascript
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'
  });
```

<mark style="color:purple;">**Step 7**</mark>

Now we can finally create our loot boxes:

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

{% hint style="info" %}
*Note that the resulting packs are ERC-1155 NFTs themselves.*
{% endhint %}

{% hint style="info" %}
*The "contents" variable is an array of all the prizes. They can include all types of tokens (ERC-20/721/1155)* simultaneousl&#x79;*.*
{% endhint %}

<mark style="color:purple;">**Step 8**</mark>

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](/english/community-edition/sdk-guides/nfts/evm-nfts-ethereum-polygon-and-others.md#transferring-nfts).

<mark style="color:purple;">**Step 9**</mark>

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

```javascript
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:

{% embed url="<https://github.com/blockforce-official/cryptum-sdk/blob/master/docs/lootbox.md>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cryptum.io/english/community-edition/sdk-guides/smart-contracts/loot-box.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.