Skip to content

Nethereum.Unity

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

Nethereum.Unity

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Contracts
Contracts
 
 
FeeSuggestions
FeeSuggestions
 
 
Rpc
Rpc
 
 
RpcModel
RpcModel
 
 
Util
Util
 
 
IpfsUrlService.cs
IpfsUrlService.cs
 
 
Nethereum.Unity.csproj
Nethereum.Unity.csproj
 
 
README.md
README.md
 
 

README.md

Nethereum.Unity

Unity game engine integration for Nethereum. Provides both async/Task and coroutine-based RPC patterns compatible with Unity's execution model, EIP-1559 fee estimation strategies, typed ERC standard helpers, and IPFS utilities.

Installation

Install via OpenUPM by adding to your Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.nethereum.unity"]
    }
  ],
  "dependencies": {
    "com.nethereum.unity": "5.0.0",
    "com.unity.nuget.newtonsoft-json": "3.2.1"
  }
}

Package source: https://github.com/Nethereum/Nethereum.Unity

For WebGL wallet integration, also add Nethereum.Unity.EIP6963 (recommended) or Nethereum.Unity.Metamask.

Key Components

RPC Clients

Class Purpose
UnityWebRequestRpcTaskClient Preferred. Async Task-based RPC client using UnityWebRequest — use with standard Web3
UnityWebRequestRpcClient Coroutine-based RPC client for yield return patterns
UnityWebRequestRpcClientFactory Factory for creating coroutine RPC clients with shared configuration

Transaction & Transfer (Coroutine)

Class Purpose
EthTransferUnityRequest Send ETH transfers with automatic EIP-1559 or legacy fee handling
TransactionSignedUnityRequest Sign and send any transaction — handles gas estimation, nonce, and fee selection
QueryUnityRequest<TFunc, TResp> Read-only smart contract calls with typed function messages
TransactionReceiptPollingRequest Poll for transaction receipt with configurable interval

EIP-1559 Fee Strategies

Class Purpose
SimpleFeeSuggestionUnityRequestStrategy baseFee * 2 + priorityFee — fast, single RPC call
TimePreferenceFeeSuggestionUnityRequestStrategy Time-preference model using fee history — returns array of suggestions by priority
MedianPriorityFeeHistorySuggestionUnityRequestStrategy Median of recent priority fees from fee history
SuggestTipUnityRequestStrategy Tip calculation from recent blocks

ERC Standard Helpers (Coroutine)

Class Purpose
ERC20ContractRequestFactory Create typed ERC-20 requests: BalanceOfQueryRequest, TransferTransactionRequest, ApproveTransactionRequest, etc.
ERC721ContractRequestFactory Create typed ERC-721 requests: OwnerOfQueryRequest, TokenURIQueryRequest, SafeTransferFromTransactionRequest, etc.
ERC1155ContractRequestFactory Create typed ERC-1155 requests: BalanceOfQueryRequest, SafeBatchTransferFromTransactionRequest, MintTransactionRequest, etc.

Utilities

Class Purpose
IpfsUrlService Converts ipfs:// URIs to HTTP gateway URLs for fetching NFT metadata

Async/Task Pattern (Preferred)

Use UnityWebRequestRpcTaskClient with the standard Nethereum Web3 API. This is the recommended approach for new projects.

using Nethereum.Web3;
using Nethereum.Unity.Rpc;

public class GetBlockNumber : MonoBehaviour
{
    public string Url = "https://ethereum-rpc.publicnode.com";

    async void Start()
    {
        var web3 = new Web3(new UnityWebRequestRpcTaskClient(new Uri(Url)));
        var blockNumber = await web3.Eth.Blocks.GetBlockNumber.SendRequestAsync();
        Debug.Log($"Block: {blockNumber.Value}");
    }
}

UnityWebRequestRpcTaskClient supports custom request headers for authenticated RPC endpoints:

var client = new UnityWebRequestRpcTaskClient(new Uri(url));
client.RequestHeaders["Authorization"] = "Bearer YOUR_API_KEY";
var web3 = new Web3(client);

With the async pattern, you have access to the full Web3 API including web3.Eth.ERC20, web3.Eth.ERC721, web3.Eth.GetEtherTransferService(), and all standard Nethereum services.

Coroutine Pattern

For Unity's traditional coroutine model, use the dedicated request classes with yield return:

Query Block Number

using Nethereum.Unity.Rpc;

IEnumerator GetBlockNumber()
{
    var blockNumberRequest = new EthBlockNumberUnityRequest(url);
    yield return blockNumberRequest.SendRequest();

    if (blockNumberRequest.Exception == null)
        Debug.Log($"Block: {blockNumberRequest.Result.Value}");
    else
        Debug.LogError(blockNumberRequest.Exception.Message);
}

Transfer ETH

var ethTransfer = new EthTransferUnityRequest(url, privateKey, chainId);

// EIP-1559 (default) — fees estimated automatically
yield return ethTransfer.TransferEther(toAddress, 0.1m);

// Or with explicit EIP-1559 fees
yield return ethTransfer.TransferEther(toAddress, 0.1m,
    maxPriorityFeePerGas, maxFeePerGas);

// Or legacy gas price
ethTransfer.UseLegacyAsDefault = true;
yield return ethTransfer.TransferEther(toAddress, 0.1m, gasPriceGwei: 20);

Query Smart Contract

var queryRequest = new QueryUnityRequest<BalanceOfFunction, BalanceOfOutputDTO>(
    url, defaultAccount);
yield return queryRequest.Query(
    new BalanceOfFunction { Owner = ownerAddress },
    contractAddress);

if (queryRequest.Exception == null)
    Debug.Log($"Balance: {queryRequest.Result.Balance}");

Send Contract Transaction

var transactionRequest = new TransactionSignedUnityRequest(url, privateKey, chainId);

var transferFunction = new TransferFunction
{
    To = recipientAddress,
    Value = Web3.Convert.ToWei(100)
};

yield return transactionRequest.SignAndSendTransaction(transferFunction, contractAddress);
string txHash = transactionRequest.Result;

Wait for Receipt

var receiptPolling = new TransactionReceiptPollingRequest(url);
yield return receiptPolling.PollForReceipt(txHash, 2); // poll every 2 seconds

if (receiptPolling.Exception == null)
    Debug.Log($"Status: {receiptPolling.Result.Status.Value}");

Fee Estimation Strategies

TransactionSignedUnityRequest uses SimpleFeeSuggestionUnityRequestStrategy by default. You can swap it:

var txRequest = new TransactionSignedUnityRequest(url, privateKey, chainId);

// Use time-preference strategy (returns multiple suggestions by priority)
var timePreference = new TimePreferenceFeeSuggestionUnityRequestStrategy(url);
yield return timePreference.SuggestFees();
var fee = timePreference.Result[0]; // highest priority
yield return ethTransfer.TransferEther(toAddress, 0.1m,
    fee.MaxPriorityFeePerGas.Value, fee.MaxFeePerGas.Value);

// Or use median fee history strategy
var median = new MedianPriorityFeeHistorySuggestionUnityRequestStrategy(url);
yield return median.SuggestFee();
var medianFee = median.Result;

IPFS URL Resolution

Convert ipfs:// URIs to HTTP gateway URLs for NFT metadata:

var httpUrl = IpfsUrlService.ResolveIpfsUrlGateway("ipfs://QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG");
// Returns: ipfs.infura.io/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

// Change the default gateway
IpfsUrlService.DefaultIpfsGateway = "https://gateway.pinata.cloud/ipfs/";

Platform Notes

  • WebGL + async/await: Requires WebGLThreadingPatcher for Task support in WebGL builds
  • IL2CPP/AOT: Set IL2CPP Code Generation to Faster (smaller) builds in Player Settings (Edit > Project Settings > Player > Other Settings)
  • Desktop HTTPS: Newer Unity versions require https:// for desktop builds — http:// may be rejected
  • AOT builds: The OpenUPM package uses AOT-compatible compiled libraries with Unity's custom Newtonsoft Json.NET

Relationship to Other Packages

  • Nethereum.Unity.EIP6963 — EIP-6963 multi-wallet discovery for Unity WebGL (recommended)
  • Nethereum.Unity.Metamask — MetaMask integration for Unity WebGL
  • Nethereum.Web3 — Core Ethereum interaction (used with UnityWebRequestRpcTaskClient)

Additional Resources