Merge pull request #196 from 0xsequence/packs-guide

Author: bunnybones1

docs.json

@@ -1004,7 +1004,8 @@
                       "guides/using-unity-iap-to-sell-nfts",
                       "guides/unity-primary-sales",
                       "guides/unity-webgl-telegram",
-                      "guides/telegram-integration"
+                      "guides/telegram-integration",
+                      "guides/packs"
                     ]
                   }
                 ]

es/guides/guide-cards.json

@@ -1 +1 @@
-{"lastUpdated":"2025-09-03T12:15:39.593Z","totalCards":6,"sections":[{"title":"Desarrolladores de videojuegos","cards":[{"title":"Cree un juego móvil con Unity + Sequence","img":"/images/unity/jellyforest-iphone.jpg","href":"/guias/jelly-forest-unity-guia","description":"Aprenda a crear un juego atractivo para iOS y Android que utiliza Sequence Embedded Wallets en segundo plano para habilitar un marketplace integrado y una moneda dentro del juego."},{"title":"Cómo crear un juego con Unreal Engine","img":"/images/guides/overview/unreal-ew-guide.th.png","href":"/guias/unreal-ew-guia","description":"Utilice el SDK de Unreal de Sequence para mostrar información de Embedded Wallet, firmar mensajes y enviar transacciones."},{"title":"Cree un juego Dungeon Crawler con recompensas generadas por IA","img":"/images/guides/treasure-chest/dungeonMinter.th.png","href":"/guias/tesoro-guia","description":"Con este tutorial, cree un laberinto web donde los objetos de caja de recompensas (lootbox) se generan usando IA y se mintean dinámicamente en el wallet universal del jugador."},{"title":"Cree un juego WebGL en Typescript","img":"/images/aviator.th.jpg","href":"/guias/webgl-guia","description":"Siga una guía paso a paso para crear una demo de juego web que utiliza Sequence Embedded Wallet y tokens de logros personalizados dentro del juego."},{"title":"Venda objetos del juego a través de una tienda web","img":"/images/guides/overview/primary-sales.th.jpg","href":"/guias/ventas-primarias","description":"Impulse el crecimiento de su juego vendiendo objetos directamente a sus jugadores. En esta guía, le mostraremos cómo desplegar un contrato de Primary Sale paso a paso usando cualquier moneda personalizada o existente para una tienda web que utiliza objetos del juego de un contrato ERC1155."},{"title":"Compre artículos on-chain en Unity","img":"/images/guides/overview/unity-primary-sales.th.jpg","href":"/guias/unity-ventas-primarias","description":"Esta guía cubre la creación de una Primary Sale con el SDK de Unity de Sequence."}]}]}
+{"lastUpdated":"2025-09-03T12:15:39.593Z","totalCards":"6","sections":[{"title":"Desarrolladores de videojuegos","cards":[{"title":"Cree un juego móvil con Unity + Sequence","img":"/images/unity/jellyforest-iphone.jpg","href":"/guias/jelly-forest-unity-guia","description":"Aprenda a crear un juego atractivo para iOS y Android que utiliza Sequence Embedded Wallets en segundo plano para habilitar un marketplace integrado y una moneda dentro del juego."},{"title":"Cómo crear un juego con Unreal Engine","img":"/images/guides/overview/unreal-ew-guide.th.png","href":"/guias/unreal-ew-guia","description":"Utilice el SDK de Unreal de Sequence para mostrar información de Embedded Wallet, firmar mensajes y enviar transacciones."},{"title":"Cree un juego Dungeon Crawler con recompensas generadas por IA","img":"/images/guides/treasure-chest/dungeonMinter.th.png","href":"/guias/tesoro-guia","description":"Con este tutorial, cree un laberinto web donde los objetos de caja de recompensas (lootbox) se generan usando IA y se mintean dinámicamente en el wallet universal del jugador."},{"title":"Cree un juego WebGL en Typescript","img":"/images/aviator.th.jpg","href":"/guias/webgl-guia","description":"Siga una guía paso a paso para crear una demo de juego web que utiliza Sequence Embedded Wallet y tokens de logros personalizados dentro del juego."},{"title":"Venda objetos del juego a través de una tienda web","img":"/images/guides/overview/primary-sales.th.jpg","href":"/guias/ventas-primarias","description":"Impulse el crecimiento de su juego vendiendo objetos directamente a sus jugadores. En esta guía, le mostraremos cómo desplegar un contrato de Primary Sale paso a paso usando cualquier moneda personalizada o existente para una tienda web que utiliza objetos del juego de un contrato ERC1155."},{"title":"Compre artículos on-chain en Unity","img":"/images/guides/overview/unity-primary-sales.th.jpg","href":"/guias/unity-ventas-primarias","description":"Esta guía cubre la creación de una Primary Sale con el SDK de Unity de Sequence."},{"title":"Configurar un contrato ERC1155Pack","img":"/images/guides/overview/packs.th.jpg","href":"/guides/packs","description":"Esta guía explica cómo configurar un contrato ERC1155Pack usando Sequence Builder."}]}]}

es/guides/guide-overview.mdx

@@ -0,0 +1,60 @@
+---
+title: Guías
+description: Siga nuestras guías paso a paso y utilice plantillas de código abierto para acelerar su salida al mercado.
+mode: wide
+sidebarTitle: Descripción general
+---
+
+<CardGroup cols={2}>
+  <Card title="Cree un servicio escalable de minteo de NFT" img="/images/guides/overview/sword.th.jpg" href="/guides/mint-collectibles-serverless">
+    Aprovechando la Transaction API de Sequence y un entorno serverless, creará un servicio de minteo escalable para NFTs u otras transacciones que maneja automáticamente las complejidades de blockchain como reorganizaciones, gestión de nonce y paralelización de transacciones.
+  </Card>
+
+  <Card title="Use Privy con Sequence" img="/images/guides/overview/privy.th.png" href="/guides/use-with-privy">
+    Aprenda cómo conectar Privy con Sequence, permitiendo que sus usuarios inicien sesión e interactúen con su aplicación a través de un Sequence Smart Wallet. Esto implica crear un Sequence wallet controlado por un EOA gestionado por Privy del usuario, y luego usar ese Sequence wallet para enviar transacciones sin gas.
+  </Card>
+
+  <Card title="Cree un marketplace personalizado" img="/images/guides/overview/marketplace.th.jpg" href="/guides/custom-marketplace">
+    Cree un marketplace impulsado por API donde los jugadores pueden mintear, vender o comprar objetos usando una interfaz web personalizada que utiliza las APIs de Orderbook de Sequence.
+  </Card>
+
+  <Card title="API de Sequence Analytics en Dune" img="/images/guides/analytics/dune-analytics.th.png" href="/guides/analytics-guide">
+    Guía para consultar información sobre el uso de sus usuarios para su proyecto específico utilizando un Cloudflare Worker serverless.
+  </Card>
+
+  <Card title="Gestión de metadatos de coleccionables" img="/images/guides/overview/storage.th.jpg" href="/guides/metadata-guide">
+    Utilizando la Metadata API de Sequence, puede crear, gestionar y almacenar metadatos asociados a sus NFTs desde casi cualquier entorno. Le mostraremos cómo utilizar estas REST-APIs para organizar las colecciones de su juego o experiencia.
+  </Card>
+</CardGroup>
+
+## Desarrolladores de videojuegos
+
+<CardGroup cols={2}>
+  <Card title="Cree un juego móvil con Unity + Sequence" img="/images/unity/jellyforest-iphone.jpg" href="/guides/jelly-forest-unity-guide">
+    Aprenda a crear un juego atractivo para iOS y Android que utiliza Sequence Embedded Wallets en segundo plano para habilitar un marketplace integrado y una moneda dentro del juego.
+  </Card>
+
+  <Card title="Cómo crear un juego con Unreal Engine" img="/images/guides/overview/unreal-ew-guide.th.png" href="/guides/unreal-ew-guide">
+    Utilice el SDK de Unreal de Sequence para mostrar información de Embedded Wallet, firmar mensajes y enviar transacciones.
+  </Card>
+
+  <Card title="Cree un juego Dungeon Crawler con recompensas generadas por IA" img="/images/guides/treasure-chest/dungeonMinter.th.png" href="/guides/treasure-chest-guide">
+    Con este tutorial, cree un laberinto web donde los objetos de caja de recompensas (lootbox) se generan usando IA y se mintean dinámicamente en el wallet universal del jugador.
+  </Card>
+
+  <Card title="Cree un juego WebGL en Typescript" img="/images/aviator.th.jpg" href="/guides/webgl-guide">
+    Siga una guía paso a paso para crear una demo de juego web que utiliza Sequence Embedded Wallet y tokens de logros personalizados dentro del juego.
+  </Card>
+
+  <Card title="Venda objetos del juego a través de una tienda web" img="/images/guides/overview/primary-sales.th.jpg" href="/guides/primary-sales">
+    Impulse el crecimiento de su juego vendiendo objetos directamente a sus jugadores. En esta guía, le mostraremos cómo desplegar un contrato de Primary Sale paso a paso usando cualquier moneda personalizada o existente para una tienda web que utiliza objetos del juego de un contrato ERC1155.
+  </Card>
+
+  <Card title="Compre artículos on-chain en Unity" img="/images/guides/overview/unity-primary-sales.th.jpg" href="/guides/unity-primary-sales">
+    Esta guía cubre la creación de una Primary Sale con el SDK de Unity de Sequence.
+  </Card>
+
+  <Card title="Configurar un contrato ERC1155Pack" img="/images/guides/overview/packs.th.jpg" href="/guides/packs">
+    Esta guía explica cómo configurar un contrato ERC1155Pack usando Sequence Builder.
+  </Card>
+</CardGroup>

es/guides/packs.mdx

@@ -0,0 +1,88 @@
+---
+title: Cómo configurar un contrato ERC1155Pack en Sequence Builder
+description: Aprenda cómo funciona ERC1155Pack en Builder, incluyendo la mecánica de commit-reveal y la publicación del contenido de los packs.
+sidebarTitle: Uso de un contrato ERC1155Pack
+---
+
+Utilice esta guía para configurar packs en su contrato ERC1155Pack dentro de Sequence Builder. El contrato `ERC1155Pack` amplía ERC1155Items para agregar un flujo de apertura de packs basado en un esquema de commit-reveal.
+
+<Warning>
+  Requisito previo: desplegar contratos y colecciones
+
+  Asegúrese de haber [creado un proyecto](/solutions/builder/getting-started), desplegado su contrato ERC1155Pack y también los contratos/colecciones ERC1155 o ERC721 cuyos ítems desea incluir en cada pack.
+</Warning>
+
+## Paso 1: Abra su contrato ERC1155Pack
+Desde el panel de su proyecto, seleccione el contrato PACK que desea configurar y luego abra la pestaña `Pack` para gestionar su contenido. Confirme que está en la red y colección correctas antes de editar.
+
+<Frame>
+  ![Resumen del contrato Pack](/images/builder/builder-packs-1.png)
+</Frame>
+
+## Paso 2: Elija o agregue un pack para editar
+Use el selector de packs para elegir el pack que desea actualizar, o haga clic en `Add new pack` para crear una nueva entrada. La tabla muestra la dirección del token, tipo, IDs y cantidades que se incluirán al abrir un pack.
+
+<Frame>
+  ![Seleccione el pack y revise el contenido](/images/builder/builder-packs-2.png)
+</Frame>
+
+## Paso 3: Suba el contenido del pack mediante CSV
+Haga clic en `Add New Pack` o `Update Pack Contents` para abrir el cargador de CSV. Ingrese el `Pack ID` que desea modificar, defina el `Supply` para indicar cuántos packs pueden abrirse y suba un archivo CSV con una fila por cada contenido del pack.
+
+Cada fila debe incluir:
+- `Pack Content ID`
+- Para cada ítem: `Token Address`, `Token Type` (1155/721), `Token IDs` y `Amounts`
+
+p. ej.
+
+```
+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
+1,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1200","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"5,6","7,3"
+2,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1201","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9,10","7,9"
+3,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1202","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"7,8","4,8"
+4,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1203","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9","7"
+5,0x3a6a8f4091b705fe1241c47e2532d45a6dff5a85,721,"1204","1",0xa558419686308ce836c36a5c44eeeb4b0916ca7b,1155,"9,10","5,4"
+
+```
+
+<Frame>
+  ![Suba el CSV con el contenido del pack](/images/builder/builder-packs-3.png)
+</Frame>
+
+<Warning>
+  El CSV reemplaza todo el contenido existente para el Pack ID seleccionado y reinicia el seguimiento de distribución de packs.
+
+  Si ya ha distribuido packs para un ID específico, le recomendamos no cambiar el CSV, ya que esto reinicia el registro de packs abiertos.
+
+  Si un ítem 721 ya fue distribuido en un pack anterior y aparece en un nuevo CSV de pack, fallará al mintear cuando un usuario abra ese pack.
+</Warning>
+
+## Paso 4: Asigne el rol de Minter al contrato de pack en su colección de ítems
+Para que los packs puedan mintear ítems al abrirse, otorgue al contrato ERC1155Pack la función de `Minter` en la colección ERC1155 que utiliza para el contenido del pack. Abra la sección `Settings > Permissions` de ese contrato, agregue la dirección del contrato de pack y asigne `Minter`, luego firme la transacción.
+
+## Paso 5: Revise y publique
+Después de procesar el CSV, verá una vista previa de las filas de contenido del pack analizadas. Verifique las direcciones de los tokens, IDs, cantidades y totales, luego haga clic en `Create Pack Contents` para guardar. Su pack ya está listo para que los jugadores lo abran.
+
+<Frame>
+  ![Vista previa del contenido procesado y publicación](/images/builder/builder-packs-4.png)
+</Frame>
+
+¿Busca un frontend para abrir packs? Vea nuestro boilerplate en React en [https://github.com/0xsequence-demos/pack-opening-boilerplate/](https://github.com/0xsequence-demos/pack-opening-boilerplate/).
+
+## Cómo funciona ERC1155Pack
+El contenido de los packs es gestionado por direcciones con `PACK_ADMIN_ROLE` usando `setPacksContent(bytes32 _merkleRoot, uint256 _supply, uint256 packId)`. El merkle root codifica todas las posibles combinaciones de contenido y `supply` define cuántos packs pueden abrirse para ese ID. Builder se encarga de crear el root a partir de su CSV para que usted solo se enfoque en el contenido.
+
+Flujo (on-chain):
+- El usuario llama a `commit(packId)` para quemar su pack y crear un compromiso.
+- Después de al menos un bloque, cualquier persona puede llamar a `reveal(user, packContent, proof, packId)` con una prueba de merkle para el contenido seleccionado; el contrato verifica y mintea los ítems. La API de Sequence lo hará automáticamente.
+- Si no se llama a reveal antes de que expire el hash del bloque de compromiso (30 minutos), `refundPack(user, packId)` devuelve el pack.
+
+Aleatorización:
+- El compromiso registra `block.number + 1` para la aleatoriedad.
+- Reveal deriva `randomSeed = keccak256(abi.encode(blockHash, user))`.
+- El contrato elige `randomSeed % remainingSupply[packId]`, usando un mapa `_availableIndices` al estilo Fisher–Yates para que cada contenido solo pueda revelarse una vez y se mantenga la aleatoriedad.
+- La hoja de merkle es `keccak256(abi.encode(revealIdx, packContent))`, que se valida con la prueba proporcionada.
+
+<Warning>
+  Los validadores o mineros que controlan bloques secuenciales podrían sesgar los hashes de bloque. Permitir que cualquiera llame a `reveal` ayuda a asegurar que los packs comprometidos se revelen antes de que expiren los hashes de bloque.
+</Warning>

guides/guide-cards.json

@@ -40,6 +40,12 @@
           "img": "/images/guides/overview/unity-primary-sales.th.jpg",
           "href": "/guides/unity-primary-sales",
           "description": "This guide covers the creation of a Primary Sale with Sequence's Unity SDK."
+        },
+        {
+          "title": "Configure a ERC1155Pack Contract",
+          "img": "/images/guides/overview/packs.th.jpg",
+          "href": "/guides/packs",
+          "description": "This guide covers the configuration of a ERC1155Pack Contract via Sequence Builder."
         }
       ]
     }

guides/guide-overview.mdx

@@ -96,4 +96,11 @@ sidebarTitle: Overview
   >
     This guide covers the creation of a Primary Sale with Sequence's Unity SDK.
   </Card>
+  <Card 
+    title="Configure a ERC1155Pack Contract" 
+    img="/images/guides/overview/packs.th.jpg" 
+    href="/guides/packs"
+  >
+    This guide covers the configuration of a ERC1155Pack Contract via Sequence Builder.
+  </Card>
 </CardGroup>