Quickstart

This guide walks you through the fastest possible way to verify OGAL works inside a Unity project.

The goal is validation, not perfection.

By the end of this guide, you should be able to:

Connect a wallet
Fetch an OGAL asset
Verify ownership and permissions
Load and use the asset at runtime

If you can do that, you are OGAL-enabled.

Prerequisites

Before you begin, you should have:

Unity 2021.3 or newer (2021.3+ supported)
Recommended: Unity 2022 LTS for the best compatibility
See the Compatibility Matrix for supported Unity/SDK versions and tested clusters
A basic Unity project already created
Optional: a Solana wallet (Phantom, Solflare, Backpack, etc.) — only needed to mint/update or verify ownership
At least one OGAL-enabled asset to test against
Familiarity with C# and standard Unity workflows

You do not need:

Deep Solana knowledge
Anchor experience
Custom RPC infrastructure
A marketplace or token economy

Step 1: Install the Solana Toolbelt

The Solana Toolbelt is distributed as a Unity Package Manager (UPM) package.

In Unity, open Package Manager → Add package from Git URL and paste:

https://github.com/NanoRes/Solana-Toolbelt.git

After installation, confirm Unity compiles cleanly and you see:

Toolbelt services
Wallet connectors
RPC and account helpers
Sample prefabs and scripts

If Unity enters Play Mode without errors, continue.

Step 2: Configure the Solana Environment

Create a Toolbelt configuration asset.

This asset defines:

Network (devnet or mainnet-beta)
RPC endpoint
Commitment level
Supported wallet adapters

Typical starting values:

Network: mainnet-beta
Commitment: confirmed
RPC: public or provider-backed endpoint

The Toolbelt manages connection state automatically.

Step 3: Connect a Wallet

This step is only required if you plan to verify ownership or perform writes (mint/update); read-only asset fetches do not need a wallet.

At runtime, prompt the user to connect a wallet using the Toolbelt wallet service.

This gives you:

A verified wallet public key
Transaction signing capability
Disconnect and session events

No on-chain state is written at this stage.

C# example (wallet connect):

using System.Threading.Tasks;
using Solana.Unity.Toolbelt;
using Solana.Unity.Toolbelt.Wallet;

public class WalletConnectExample
{
    public async Task ConnectAsync()
    {
        var walletManager = ToolbeltRuntime.Instance.WalletManager;
        await walletManager.ConnectAsync();

        var wallet = walletManager.Wallet;
        UnityEngine.Debug.Log($"Wallet connected: {wallet.Account.PublicKey}");
    }
}

Step 4: Fetch an OGAL Asset

Every OGAL asset has a canonical on-chain identity.

You will need:

The OGAL AssetAccount public key
The OGAL program ID

Using the Toolbelt:

Fetch the AssetAccount
Deserialize its state
Inspect ownership, mutability flags, and metadata URI

This step verifies truth, not value.

Readers: no wallet required for fetching OGAL asset state.

The Toolbelt exposes OGAL helpers via OwnerGovernedAssetLedgerService. Resolve it from ToolbeltRuntime (or your service provider) and use its account helpers to read OGAL state.

C# example (fetch OGAL account):

using System.Threading.Tasks;
using Solana.Unity.Toolbelt;
using Solana.Unity.Toolbelt.Ogal;

public class OgalFetchExample
{
    public async Task FetchAssetAsync(string assetAccountPubkey)
    {
        var ogalService = ToolbeltRuntime.Instance.OwnerGovernedAssetLedgerService;
        var assetAccount = await ogalService.GetAssetAccountAsync(assetAccountPubkey);

        UnityEngine.Debug.Log($"Asset fetched: {assetAccount.AssetAccountAddress}");
    }
}

Step 5: Verify Ownership and Permissions

Before using the asset, check:

Does the connected wallet own the asset
Is the asset mutable or immutable
Are updates allowed for this caller

These are read-only checks and inexpensive.

Ownership verification requires a connected wallet. Readers: no wallet required; creators/namespace authorities: wallet required to mint/update.

If verification fails:

Do not load the asset
Do not fallback silently
Make the failure explicit in your UX

Trust depends on clarity.

C# example (ownership verification):

using System.Threading.Tasks;
using Solana.Unity.Toolbelt;

public class OgalOwnershipExample
{
    public async Task<bool> VerifyOwnershipAsync(string assetAccountPubkey)
    {
        var ogalService = ToolbeltRuntime.Instance.OwnerGovernedAssetLedgerService;
        var walletManager = ToolbeltRuntime.Instance.WalletManager;

        var assetAccount = await ogalService.GetAssetAccountAsync(assetAccountPubkey);
        var walletPubkey = walletManager.Wallet.Account.PublicKey;

        var isOwner = assetAccount.Owner == walletPubkey;
        UnityEngine.Debug.Log($"Ownership verified: {isOwner}");
        return isOwner;
    }
}

Step 6: Load Metadata and Reconstruct Content

OGAL assets reference off-chain data through a metadata URI.

Typical reconstruction flow:

Fetch metadata JSON from Arweave or IPFS
Optionally verify content hash
Parse asset-specific fields
Reconstruct content at runtime

Examples include:

Loading a level layout
Spawning prefabs
Applying configuration values
Attaching behaviors

OGAL does not define rendering or execution logic.

C# example (metadata URI retrieval):

using System.Threading.Tasks;
using Solana.Unity.Toolbelt;

public class OgalMetadataExample
{
    public async Task<string> GetMetadataUriAsync(string assetAccountPubkey)
    {
        var ogalService = ToolbeltRuntime.Instance.OwnerGovernedAssetLedgerService;
        var assetAccount = await ogalService.GetAssetAccountAsync(assetAccountPubkey);

        var metadataUri = assetAccount.MetadataUri;
        UnityEngine.Debug.Log($"Metadata URI: {metadataUri}");
        return metadataUri;
    }
}

C# example (asset reconstruction):

using System.Net.Http;
using System.Threading.Tasks;
using UnityEngine;

public class OgalReconstructionExample
{
    public async Task ReconstructAsync(string metadataUri)
    {
        using var http = new HttpClient();
        var json = await http.GetStringAsync(metadataUri);

        var metadata = JsonUtility.FromJson<OgalMetadata>(json);
        var prefab = Resources.Load<GameObject>(metadata.prefabPath);
        Object.Instantiate(prefab, metadata.spawnPosition, Quaternion.identity);
        Debug.Log("Asset reconstructed from metadata.");
    }

    [System.Serializable]
    private class OgalMetadata
    {
        public string prefabPath;
        public Vector3 spawnPosition;
    }
}

Step 7: Use the Asset in Your Application

Once reconstructed, the asset behaves like normal application data.

You can:

Render it
Reference it in gameplay
Gate features based on ownership
Allow updates if permissions permit

No additional on-chain interaction is required for reuse.

Unity Scene Setup (Minimal Checklist)

Make sure your scene includes:

Web3.prefab from the Toolbelt samples (ensures runtime bootstrap).
A ToolbeltRuntime component (usually on the Web3 GameObject).
A SolanaConfiguration asset created in the project and discoverable via Resources or assigned directly in the inspector.
Your wallet UI bridge or in-game connect button wired to the WalletManager connect flow.

Expected Output / Logs

When the integration is wired correctly, you should see logs similar to:

ToolbeltRuntime initialized.
Wallet connected: <publicKey>
Asset fetched: <assetAccountPubkey>
Ownership verified: true
Metadata URI: https://...
Asset reconstructed from metadata.

If you do not see these, confirm the scene setup, RPC endpoint, and asset public key are all correct.

What You Have Achieved

You now have:

On-chain ownership verification
Portable, reusable content
No platform lock-in
No required marketplace or monetization

This is the core OGAL integration.

Common Next Steps

After Quickstart, most teams proceed to:

Asset minting flows
Update permission enforcement
Cross-application reuse
OPP packaging
Marketplace discovery

Do not add these unless you need them.

Design Reminder

OGAL should feel simpler than rebuilding UGC infrastructure yourself.

If it does not, pause and reassess.

That feedback is valuable.

Prerequisites​

Step 1: Install the Solana Toolbelt​

Step 2: Configure the Solana Environment​

Step 3: Connect a Wallet​

Step 4: Fetch an OGAL Asset​

Step 5: Verify Ownership and Permissions​

Step 6: Load Metadata and Reconstruct Content​

Step 7: Use the Asset in Your Application​

Unity Scene Setup (Minimal Checklist)​

Expected Output / Logs​

What You Have Achieved​

Common Next Steps​

What to Read Next​

Design Reminder​