Unity SDK

The Mirage Unity SDK provides an easy way to interact with Web3 and to work with contracts deployed on the blockchain. As a plugin it easily integrates with MetaMask on Android and iOS.
View Demo

Table of Contents

Install SDK
What's in the SDK
Getting Started

Prerequisites
Use Cases

Connect Web3 Wallet

Perform Updates to NFTs

Signing Transactions
Sending Transactions
GetData Method
CallMethod

Current ERC Proposals
View Full Examples

## 🏗 Install SDK We are using UniTask and Newtonsoft.Json as a dependency, so installing through Package Manager is a preferable way. ### Install via git URL Requires a version of unity that supports path query parameter for git packages (Unity >= 2019.3.4f1, Unity >= 2020.1a21). You can add https://github.com/Ankr-network/game-unity-sdk.git?path=Assets/MirageSDK to Package Manager ![image](https://user-images.githubusercontent.com/9112595/185632883-66555321-a6be-4a57-826b-9b28a10f580c.png)

or add "com.mirage.miragesdk": "https://github.com/Ankr-network/game-unity-sdk.git?path=Assets/MirageSDK" to Packages/manifest.json To be able to use "com.mirage.miragesdk" as a dependency remember to add [Scoped Registry](https://docs.unity3d.com/Manual/upm-scoped.html): ``` name: package.openupm.com URL: https://package.openupm.com Scope(s): com.mirage.miragesdk com.cysharp.unitask ``` Our package depends ### Install via OpenUPM The package is available on the [openupm registry](https://openupm.com). It's recommended to install it via [openupm-cli](https://github.com/openupm/openupm-cli). ``` openupm add com.mirage.miragesdk ``` ## 👀 What's in the SDK The SDK is designed to make it super easy to get started with Game development by enabling connection and interaction across different blockchains. * Contains a huge range of classes, plugins and example scripts for a variety of use cases. * Nethereum libraries provide support for web requests using RPC over Http. * Ankr RPC network infrastructure provides fast and easy connection to multiple chains. ## Getting started ### 🧰 Prerequisites 1. Smart Contracts must already be deployed on the blockchain. You have the Smart Contract addresses and ABI. ### 📌 Use Cases This help content focuses on the following use cases. 1. Connecting to a Web3 Wallet (MetaMask) and Authenticating a user 2. Performing Updates to NFTs by interacting with the blockchain and calling smart functions. ## 👝 01 Connect Web3 Wallet Connecting to an Ethereum i.e. MetaMask wallet provides a link between a wallet address and a user's game account. You have to connect your wallet via WalletConnect. There is a number of ways which you can get a session key from your wallet: - Connect with QRCode using **QRCodeImage** component. - Connect using WalletConnect.Instance.OpenMobileWallet. Both of these methods will generate a linking url which will create a request in your wallet to connect. If you accept to connect a session key will be saved in PlayerPrefs for future use. 1. Create an instance of a `MirageSDKWrapper` class via `MirageSDKWrapper.GetMirageSDKInstance(...)` method after successful connection to your wallet ```c# var sdk = MirageSDKWrapper.GetMirageSDKInstance(""); ``` Inside (MirageSDK/Examples/UseCases/LinkingAccountWallet) is an example script demonstrating how to link a crypto wallet (MetaMask) to a player account. ## 🚀 02 Perform Updates to NFTs Making updates to the NFT e.g. adding a red hat to a character requires signing and sending a transaction. ### Signing Transactions All updates are transactions that must be signed via a prompt from MetaMask. #### Sign message Login via WalletConnect is required to sign the message. - Call the `IEthHandler.Sign` to trigger Signing via MetaMask. ```c# string message = "Hi I am a message !" string address = "0x..."; string signature = await sdk.Eth.Sign(message, address); ``` returns the signature of given message. #### Verify the user signed message ```c# MirageSignatureHelper.CheckSignature(message, signature); ``` ### Sending Transactions There are two ways to make update transactions. Using the **GetData** method and the **CallMethod** #### GetData Method Use the `GetData` method to retrieve information from the blockchain. (READ functions do NOT require mining.). Other non-standard `Get` functions are also available These methods require * Contract Address * ABI The following extract is an example usage of the **GetData** method to retrieve information about an NFT: ```c# private async UniTask GetHat(BigInteger tokenID) { var getHatMessage = new GetHatMessage { CharacterId = tokenID.ToString() }; var hatId = await _gameCharacterContract.GetData(getHatMessage); UpdateUILogs($"Hat Id: {hatId}"); return hatId; } ``` #### CallMethod Use the `CallMethod` to write new information to the blockchain. These methods utilize gas. The following extract is an example of how a `CallMethod` is used to update an NFT: ```c# public async void UpdateNFT() { // 1) Request nft parameters and signature for parameters var info = await RequestPreparedParams(0); // 2) Call method that check signature and update nft var receipt = await _contract.CallMethod("updateTokenWithSignedMessage", new object[] { info }); Debug.Log($"Receipt: {receipt}"); } ``` #### Handle transaction events There is a `ITransactionEventHandler` argument which provides an access to keypoints of transaction flow.
Implement `ITransactionEventHanlder` and pass the instance as an argument to be able to intercept those events.
There are pre-crafted implementations:
Allows you to subscribe to events
```c# public class TransactionEventDelegator : ITransactionEventHandler ``` Base class for you to implement, so you don't have to implement each callback.
```c# public class TransactionEventHanlder : ITransactionEventHandler ``` ## SDK Detailed description ### IMirageSDK After you finished connecting your wallet via WalletConnect you can access SDK Functionallity. First of all you should get an sdk Instance: ```c# var sdk = MirageSDKWrapper.GetMirageSDKInstance(""); ``` #### EthHandler You can get EthHandler via get-only property from sdk instance. ```c# _eth = sdk.Eth; ``` #### IContract IContract is a contract handler which gives you an easier access to web3, by handling low-level transformations. ```c# _contract = sdk.GetContract("", ""); ``` After you have IContract instance for your smart-contract you are now eligible to work with your contract deployed on blockchain ##### CallMethodAsync ```c# Task CallMethodAsync(string methodName, object[] arguments = null, string gas = null, string gasPrice = null, string nonce = null); ``` Sends a message via socket-established connection via json-rpc. Method name is "eth_sendTransaction" Input: - methodName: contract method name to call. Contract ABI should contain methodName. - arguments: an array of arguments for contract call. Contract ABI should contain ABIType for passed arguments. - gas: The amount of gas to use for the transaction (unused gas is refunded). - gasPrice: The price of gas for this transaction in wei, - nonce: Integer of the nonce. This allows to overwrite your own pending transactions that use the same nonce. Output: - returns transaction hash Example: ```c# _contract.CallMethodAsync(rentOutMethodName, new object[] { renter, tokenId, expiresAt }) ``` ##### Web3SendMethodAsync ```c# Task Web3SendMethodAsync(string methodName, object[] arguments, string gas = null, string gasPrice = null, string nonce = null, ITransactionEventHandler eventHandler = null); ``` Input: - methodName: contract method name to call. Contract ABI should contain methodName. - arguments: an array of arguments for contract call. Contract ABI should contain ABIType for passed arguments. - gas: The amount of gas to use for the transaction (unused gas is refunded). - gasPrice: The price of gas for this transaction in wei, - nonce: Integer of the nonce. This allows to overwrite your own pending transactions that use the same nonce. - eventHandler: event handler which allows you to track every step of your transaction. Output: - void To get a receipt using **Web3SendMethodAsync** you can subscribe to ITransactionEventHandler ```c# void ReceiptReceived(TransactionReceipt receipt); ``` **ITransactionEventHandler** callback: - Transaction Begin - is called right after transaction input was created - Transaction End - is called after transaction was requested, but still pending - Transaction Hash - is called in case if task was not faulted and hash was received - Transaction Error - is called if there was a error during transaction execution - Transaction Receipt - receipt is requested in case if transaction was successful via EthHandler and is passed to Receipt callback. ##### GetAllChanges ```c# Task>> GetAllChanges(EventFilterData evFilter) where TEvDto : IEventDTO, new() ``` Input: - evFilter:EventFilterData is a simple data holder which allows you to filter events. Output - List of event logs filled with supplied DTO. EventFilterData allows you to filter event by topics (3 max) and "To Block" with "From Block" ##### GetData ```c# Task GetData(TFieldData requestData = null) where TFieldData : FunctionMessage, new() ``` Queries a request to get data from contract ##### EstimateGas Makes a call or transaction, which won't be added to the blockchain and returns the used gas, which can be used for estimating the used gas. ```c# Task EstimateGas(string methodName, object[] arguments = null, string gas = null, string gasPrice = null, string nonce = null) ``` Input: - methodName: contract method name to estimate. Contract ABI should contain methodName. - arguments: an array of arguments for contract call. Contract ABI should contain ABIType for passed arguments. - gas: The amount of gas to use for the transaction (unused gas is refunded). - gasPrice: The price of gas for this transaction in wei, - nonce: Integer of the nonce. This allows to overwrite your own pending transactions that use the same nonce. Output: - estimated gas price for transaction ## Current ERC Proposals We have two ERC proposals. [ERC-4884 Rentable NFT Standard](https://github.com/Ankr-network/game-smart-contract-example/blob/master/ERC/rentable-nft.md) [ERC-4911 Composability Extension For ERC-721 Standard](https://github.com/Ankr-network/game-smart-contract-example/blob/master/ERC/composable-nft.md)

(back to top)

## View Full Examples For full examples: View [ERC20 token example](https://github.com/Ankr-network/game-unity-sdk/raw/master/Assets/MirageSDK/Examples/Scripts/ERC20Example/ERC20Example.cs) and [ERC721 token example](https://github.com/Ankr-network/game-unity-sdk/raw/master/Assets/MirageSDK/Examples/Scripts/ERC721Example/ERC721Example.cs)