|
| 1 | +--- |
| 2 | +title: "How to Configure a ERC1155Pack Contract in Sequence Builder" |
| 3 | +description: Learn how ERC1155Pack works in Builder, including commit-reveal mechanics, and publishing pack contents. |
| 4 | +sidebarTitle: Using a ERC1155Pack Contract |
| 5 | +--- |
| 6 | + |
| 7 | +Use this guide to configure packs in your ERC1155Pack contract in Sequence Builder. The `ERC1155Pack` contract extends ERC1155Items to add a pack-opening flow powered by a commit-reveal scheme. |
| 8 | + |
| 9 | +<Warning> |
| 10 | +Prerequisite: Deploy Contracts and Items |
| 11 | + |
| 12 | +Make sure you have [created a project](/solutions/builder/getting-started), deployed your ERC1155Pack contract, and deployed the ERC1155 or ERC721 contracts/collections whose items you want inside each pack. |
| 13 | +</Warning> |
| 14 | + |
| 15 | +## Step 1: Open your ERC1155Pack contract |
| 16 | + |
| 17 | +From your project dashboard, select the PACK contract you want to configure, then open the `Pack` tab to manage its contents. Confirm you are on the correct network and linked collection before editing. |
| 18 | +<Frame> |
| 19 | + |
| 20 | +</Frame> |
| 21 | + |
| 22 | +## Step 2: Choose or add a pack to edit |
| 23 | + |
| 24 | +Use the pack selector to pick the pack you want to update, or click `Add new pack` to create another pack entry. The table lists each pack's underlying token address, type, IDs, and amounts that will be included when a pack is opened. |
| 25 | +<Frame> |
| 26 | + |
| 27 | +</Frame> |
| 28 | + |
| 29 | +## Step 3: Upload pack contents via CSV |
| 30 | + |
| 31 | +Click `Add New Pack` or `Update Pack Contents` to open the CSV uploader. Enter the `Pack ID` you want to modify, set the `Supply` for how many packs can be opened, and upload a CSV with one row per pack content. |
| 32 | + |
| 33 | +Each row must include: |
| 34 | + |
| 35 | +- `Pack Content ID` |
| 36 | +- For each item: `Token Address`, `Token Type` (1155/721), `Token IDs`, and `Amounts` |
| 37 | + |
| 38 | +e.g. |
| 39 | +``` |
| 40 | +Pack Content ID, Item 1 Token Addr, Item 1 Token Type, Item 1 Token IDs, Item 1 Amounts, Item 2 Token Addr, Item 2 Token Type, Item 2 Token IDs, Item 2 Amounts |
| 41 | +1,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1200","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"5,6","7,3" |
| 42 | +2,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1201","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9,10","7,9" |
| 43 | +3,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1202","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"7,8","4,8" |
| 44 | +4,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1203","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9","7" |
| 45 | +5,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1204","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9,10","5,4" |
| 46 | +
|
| 47 | +``` |
| 48 | + |
| 49 | +<Frame> |
| 50 | + |
| 51 | +</Frame> |
| 52 | + |
| 53 | +<Warning> |
| 54 | +The CSV replaces all existing contents for the selected Pack ID, and resets pack distribution tracking. |
| 55 | + |
| 56 | +If you have already distributed packs for a specific ID, we recommend you do not change the CSV, as this resets which packs have been opened. |
| 57 | + |
| 58 | +If a 721 item was already distributed in a previous pack, and it is in a new pack CSV, it will fail to mint when a user opens that pack. |
| 59 | +</Warning> |
| 60 | + |
| 61 | + |
| 62 | +## Step 4: Give the pack contract a Minter role on your item collection |
| 63 | + |
| 64 | +For packs to mint items when opened, grant the ERC1155Pack contract address the `Minter` role on the ERC1155 collection you're using for pack contents. Open that item contract’s `Settings > Permissions`, add the pack contract address, and assign `Minter`, then sign the transaction. |
| 65 | + |
| 66 | +## Step 5: Review and publish |
| 67 | + |
| 68 | +After the CSV is processed you will see a preview of the parsed Pack Content rows. Verify the token addresses, IDs, amounts, and totals, then click `Create Pack Contents` to save. Your pack is now ready to be opened by players. |
| 69 | +<Frame> |
| 70 | + |
| 71 | +</Frame> |
| 72 | + |
| 73 | +Looking for a frontend to open packs? Check out our react boilerplate at https://github.com/0xsequence-demos/pack-opening-boilerplate/. |
| 74 | + |
| 75 | + |
| 76 | +## How ERC1155Pack works |
| 77 | + |
| 78 | +Pack contents are managed by addresses with `PACK_ADMIN_ROLE` using `setPacksContent(bytes32 _merkleRoot, uint256 _supply, uint256 packId)`. The merkle root encodes every possible pack content, and `supply` defines how many packs can be opened for that ID. Builder handles the root creation from your CSV so you can focus on content. |
| 79 | + |
| 80 | +Flow (on-chain): |
| 81 | + |
| 82 | +- User calls `commit(packId)` to burn their pack and create a commitment. |
| 83 | +- After at least one block, anyone can call `reveal(user, packContent, proof, packId)` with a merkle proof for the selected content; the contract verifies and mints the items. The Sequence API will do this automatically. |
| 84 | +- If reveal is not called before the commitment block hash expires (30 minutes), `refundPack(user, packId)` returns the pack. |
| 85 | + |
| 86 | +Randomization: |
| 87 | + |
| 88 | +- Commitment records `block.number + 1` for randomness. |
| 89 | +- Reveal derives `randomSeed = keccak256(abi.encode(blockHash, user))`. |
| 90 | +- The contract picks `randomSeed % remainingSupply[packId]`, using a Fisher–Yates-style `_availableIndices` map so each content can only be revealed once and stays uniformly random. |
| 91 | +- The merkle leaf is `keccak256(abi.encode(revealIdx, packContent))`, matched by the supplied proof. |
| 92 | + |
| 93 | +<Warning> |
| 94 | +Validators or miners controlling sequential blocks could bias block hashes. Allowing anyone to call `reveal` helps ensure committed packs are revealed before block hashes expire. |
| 95 | +</Warning> |
0 commit comments