From b9acba9042f6ca3d9e19982fbb6b655e6cbe7d1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andy=20Gru=CC=88ning?= Date: Tue, 15 Oct 2024 08:51:15 +0200 Subject: [PATCH 1/2] added unity primary sales guide --- docs/pages/guides/primary-sales.mdx | 2 +- docs/pages/guides/unity-primary-sales.mdx | 134 ++++++++++++++++++++++ nav.ts | 5 + 3 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 docs/pages/guides/unity-primary-sales.mdx diff --git a/docs/pages/guides/primary-sales.mdx b/docs/pages/guides/primary-sales.mdx index 40bb17328f5..3b59b00cb27 100644 --- a/docs/pages/guides/primary-sales.mdx +++ b/docs/pages/guides/primary-sales.mdx @@ -85,7 +85,7 @@ When you're ready, replace the contents of `.env` with your project's informatio ## Configure your own Primary Sales Contracts in the repository -We provide a few example contracts and variables in order to get you started. However, you will likely wnat to use your own contracts. In order to configure this simply following the steps below: +We provide a few example contracts and variables in order to get you started. However, you will likely want to use your own contracts. In order to configure this simply following the steps below: ::::steps ### Deploy a Primary Sales Contract in Sequence Builder. diff --git a/docs/pages/guides/unity-primary-sales.mdx b/docs/pages/guides/unity-primary-sales.mdx new file mode 100644 index 00000000000..88786efe39c --- /dev/null +++ b/docs/pages/guides/unity-primary-sales.mdx @@ -0,0 +1,134 @@ +--- +title: How to sell On-Chain Items in your Game Client +description: Intro to Jelly Forest - Unity Game Guide introduces a 2D runner game with blockchain features like social sign-in, upgrades, and cosmetic items stored in a smart contract wallet. +--- + +# How to sell On-Chain Items in Unity + +Accelerate your game growth by selling items directly to your players. In this guide, we will go over the steps how +to deploy a Primary Sale contract using any custom or existing currency for an In-Game Shop that utilizes game items +from a ERC1155 contract. We will use the following technologies from the Sequence platform: + +- [Primary Sales Contract](/solutions/collectibles/contracts/deploy-primary-sales-contract/): How to set up and deploy contracts for launching a primary sale — suitable for an Web Shop, NFT Drop, and more. +- [Embedded Wallet](/solutions/wallets/embedded-wallet/overview): Use Sequence Kit and Sequence Embedded Wallet to authenticate a user. +- [Sequence Indexer](solutions/builder/indexer): Leveraging the Sequence Indexer to query NFT metadata and user's wallet assets. + +## 1. Deploy your own Token- and Sale Contract in Sequence Builder + +In the builder you have to create your own token contract and a sale contract specific to your +We first need a Primary Sales Contract along with an ERC1155 contract that will contain our game items we want to sell. +To do that, please follow the [guide](/solutions/collectibles/contracts/deploy-primary-sales-contract) here. + +## 2. Use the Primary Sales Demo inside Sequence's Unity SDK + +To get started, import [Sequence's Unity SDK](https://github.com/0xsequence/sequence-unity/releases) into your project. +Then, navigate to the `Demo.unity` scene located `Sequence Embedded Wallet SDK/Sequence/Samples/DemoScene`. +In this scene, you’ll find the `PrimarySalePage` object, which serves as a useful reference. + +## 3. Set your Sale Configurations in your Project + +To configure your sale, use the `PrimarySalePage` object to input your sale information. +In the Configuration section, you’ll find the following options: + +- Chain: Select the chain where your contract is deployed. +- Token & Sale Contract Address: Enter the contract addresses provided by Sequence's Builder. +- Items For Sale: List all the Token IDs you wish to sell. + +## 4. Implement Custom Code to Interact with the SDK + +Let's create a custom class to manage the state for our sale. This class will gather all the necessary data, +allowing us to display this information to users effectively. +In the PrimarySalePage.cs demo, the data is sourced from the Configuration section. + +```csharp +class ERC1155SaleState +{ + public ERC1155SaleState(IWallet wallet, string tokenContractAddress, string saleContractAddress, Chain chain, int[] itemsForSale) + { + _tokenContractAddress = tokenContractAddress; + _saleContract = new ERC1155Sale(saleContractAddress); + _client = new SequenceEthClient(chain); + _wallet = wallet; + _chain = chain; + _itemsForSale = itemsForSale; + } +} +``` + +## 5. Retrieve Your Primary Sale Details + +Next, use the `ERC1155Sale.cs` reference to obtain sale details and the payment token from the contract. +This information can be used, for instance, to locally verify if the user has sufficient balance for the specified payment token. + +```csharp +public async Task UpdateSaleDetailsAsync() +{ + string paymentToken = await _saleContract.GetPaymentTokenAsync(_client); + + ERC1155Sale.SaleDetails globalSaleDetails = await _saleContract.GetGlobalSaleDetailsAsync(_client); + BigInteger cost = globalSaleDetails.Cost; + BigInteger supplyCap = globalSaleDetails.SupplyCap; + int startTime = globalSaleDetails.StartTime; + int endTime = globalSaleDetails.EndTime; +} +``` + +## 6. Fetching Token Metadata to Display Items to Users + +We’ll use the Indexer API to retrieve token supplies for the specified token contract address. +Be sure to use the address of the ERC1155 contract, not the sales contract. + +```csharp +public async Task UpdateTokenSuppliesAsync() +{ + Dictionary tokenSupplies = new Dictionary(); + GetTokenSuppliesArgs supplyArgs = new GetTokenSuppliesArgs(_tokenContractAddress, true); + GetTokenSuppliesReturn suppliesReturn = await Indexer.GetTokenSupplies((int) _chain, supplyArgs); + + foreach (int tokenId in _itemsForSale) + { + TokenSupply supply = Array.Find(suppliesReturn.tokenIDs, t => t.tokenID == tokenId); + if (supply == null) + continue; + + tokenSupplies.Add(supply.tokenID, supply); + } +} +``` + +For example, you can use the `supply.tokenMetadata.image` variable from the token supplies mentioned above +to display your items to the user. + +```csharp +[SerializeField] private Image _image; + +public async void RenderTokenImage(TokenSupply supply) +{ + _image.sprite = await AssetHandler.GetSpriteAsync(supply.tokenMetadata.image); +} +``` + +:::warning +Ensure that you implement your own `AssetHandler` class to handle image downloads from remote URLs. +::: + +## 7. Purchase an Item from the Store + +This will call the mint function from the Sales Contract. By specifying the user’s wallet address as the `to` parameter, +the contract will mint the item to that user. You can use the `ERC1155Sale.cs` class to create a `CallContractFunction` +reference, which allows you to send a transaction to your sales contract using the user's wallet. + +```csharp +public async Task PurchaseAsync(BigInteger tokenId, int amount) +{ + string to = _wallet.GetWalletAddress(); + byte[] defaultProof = Array.Empty(); + + CallContractFunction contractCall = _saleContract.Mint(to, new[] {tokenId}, + new[] {new BigInteger(amount)}, null, PaymentToken, new BigInteger(1), defaultProof); + + Transaction[] transactions = new Transaction[] { new RawTransaction(contractCall) }; + TransactionReturn result = await _wallet.SendTransaction(_chain, transactions); + return result is SuccessfulTransactionReturn; +} +``` diff --git a/nav.ts b/nav.ts index 7b86de097ff..462465fd0af 100644 --- a/nav.ts +++ b/nav.ts @@ -489,6 +489,11 @@ export const sidebar = { collapsed: true, link: '/guides/building-transaction-heavy-games-with-unity', }, + { + text: 'How to sell On-Chain Items in Unity', + collapsed: true, + link: '/guides/unity-primary-sales', + }, { text: 'Build a Collectible Minting Service', collapsed: true, From 68ac2ca6fff7c16e7b9c264689cd341277ad68bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andy=20Gru=CC=88ning?= Date: Sat, 19 Oct 2024 00:58:41 +0200 Subject: [PATCH 2/2] added to guide section, changed from pr review --- docs/components/GuidesOverview.tsx | 7 +++ docs/pages/guides/unity-primary-sales.mdx | 51 +++++++++++++------ .../guides/overview/unity-primary-sales.png | 3 ++ nav.ts | 2 +- 4 files changed, 47 insertions(+), 16 deletions(-) create mode 100644 docs/public/img/guides/overview/unity-primary-sales.png diff --git a/docs/components/GuidesOverview.tsx b/docs/components/GuidesOverview.tsx index 25cf19f91fa..e22c63bd89c 100644 --- a/docs/components/GuidesOverview.tsx +++ b/docs/components/GuidesOverview.tsx @@ -42,6 +42,13 @@ export const GuidesOverview = () => ( image="/img/guides/overview/primary-sales.png" demoLink="https://primary-drop-sale-1155-boilerplate.pages.dev/" /> +
diff --git a/docs/pages/guides/unity-primary-sales.mdx b/docs/pages/guides/unity-primary-sales.mdx index 88786efe39c..75935e70976 100644 --- a/docs/pages/guides/unity-primary-sales.mdx +++ b/docs/pages/guides/unity-primary-sales.mdx @@ -1,21 +1,19 @@ --- -title: How to sell On-Chain Items in your Game Client -description: Intro to Jelly Forest - Unity Game Guide introduces a 2D runner game with blockchain features like social sign-in, upgrades, and cosmetic items stored in a smart contract wallet. +title: How to do Primary Sales for On-Chain Items in Unity +description: This guide covers the creation of a Primary Sale with Sequence's Unity SDK. --- -# How to sell On-Chain Items in Unity +# How to do Primary Sales for On-Chain Items in Unity Accelerate your game growth by selling items directly to your players. In this guide, we will go over the steps how to deploy a Primary Sale contract using any custom or existing currency for an In-Game Shop that utilizes game items from a ERC1155 contract. We will use the following technologies from the Sequence platform: - [Primary Sales Contract](/solutions/collectibles/contracts/deploy-primary-sales-contract/): How to set up and deploy contracts for launching a primary sale — suitable for an Web Shop, NFT Drop, and more. -- [Embedded Wallet](/solutions/wallets/embedded-wallet/overview): Use Sequence Kit and Sequence Embedded Wallet to authenticate a user. - [Sequence Indexer](solutions/builder/indexer): Leveraging the Sequence Indexer to query NFT metadata and user's wallet assets. ## 1. Deploy your own Token- and Sale Contract in Sequence Builder -In the builder you have to create your own token contract and a sale contract specific to your We first need a Primary Sales Contract along with an ERC1155 contract that will contain our game items we want to sell. To do that, please follow the [guide](/solutions/collectibles/contracts/deploy-primary-sales-contract) here. @@ -41,17 +39,16 @@ allowing us to display this information to users effectively. In the PrimarySalePage.cs demo, the data is sourced from the Configuration section. ```csharp -class ERC1155SaleState +class ERC1155SaleState; + +public ERC1155SaleState(IWallet wallet, string tokenContractAddress, string saleContractAddress, Chain chain, int[] itemsForSale) { - public ERC1155SaleState(IWallet wallet, string tokenContractAddress, string saleContractAddress, Chain chain, int[] itemsForSale) - { - _tokenContractAddress = tokenContractAddress; - _saleContract = new ERC1155Sale(saleContractAddress); - _client = new SequenceEthClient(chain); - _wallet = wallet; - _chain = chain; - _itemsForSale = itemsForSale; - } + _tokenContractAddress = tokenContractAddress; + _saleContract = new ERC1155Sale(saleContractAddress); + _client = new SequenceEthClient(chain); + _wallet = wallet; + _chain = chain; + _itemsForSale = itemsForSale; } ``` @@ -119,6 +116,8 @@ the contract will mint the item to that user. You can use the `ERC1155Sale.cs` c reference, which allows you to send a transaction to your sales contract using the user's wallet. ```csharp +class ERC1155SaleState; + public async Task PurchaseAsync(BigInteger tokenId, int amount) { string to = _wallet.GetWalletAddress(); @@ -132,3 +131,25 @@ public async Task PurchaseAsync(BigInteger tokenId, int amount) return result is SuccessfulTransactionReturn; } ``` + +When the user clicks the purchase button in the game UI, we call and await the PurchaseAsync function from the sale state class. +If the purchase is successful, we show a notification and update the UI. +If it fails, we display a QR code for the user to add more funds to their wallet. + +```csharp +class GameWindowUI; + +private ERC1155SaleState _saleState; + +public async void OnPurchaseClicked(BigInteger tokenId, int amount) +{ + bool success = await _saleState.PurchaseAsync(tokenId, amount); + if (!success) { + OpenQrCodeView(); + return; + } + + ShowNotification("Purchase succeeded."); + RenderState(); +} +``` diff --git a/docs/public/img/guides/overview/unity-primary-sales.png b/docs/public/img/guides/overview/unity-primary-sales.png new file mode 100644 index 00000000000..dc38f5450ef --- /dev/null +++ b/docs/public/img/guides/overview/unity-primary-sales.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:76234e4a2e225074bcc53901fdcc1668360b275a6caae731f66a0de9c73cd66e +size 174868 diff --git a/nav.ts b/nav.ts index 3d7a39f4be2..2ba5c3e45e6 100644 --- a/nav.ts +++ b/nav.ts @@ -495,7 +495,7 @@ export const sidebar = { link: '/guides/building-transaction-heavy-games-with-unity', }, { - text: 'How to sell On-Chain Items in Unity', + text: 'How to do Primary Sales for On-Chain Items in Unity', collapsed: true, link: '/guides/unity-primary-sales', },