Skip to main content

Solana Toolbelt for Unity

The Solana Toolbelt for Unity is developer-facing infrastructure, not a protocol and not a wallet replacement.

Its purpose is simple and opinionated:

  • Make OGAL usable in real Unity projects
  • Compress integration cost without taking control
  • Surface blockchain complexity in a way that is explicit, debuggable, and player-safe

The Toolbelt layers runtime orchestration, OGAL-aware services, storage automation, and UI contracts on top of the Solana Unity SDK. It does not replace the SDK. It makes it practical.

Reference​

Core Mental Model​

  • OGAL defines truth.
  • The Solana Unity SDK provides primitives.
  • The Toolbelt turns those primitives into gameplay-ready infrastructure.

If OGAL is the protocol and the SDK is the engine, the Toolbelt is the wiring harness.

What the Toolbelt Is​

  • A Unity-first runtime and service layer
  • A set of OGAL-aware helpers and workflows
  • A configuration-driven orchestration system
  • A UI-agnostic bridge between gameplay and Web3 flows

It is designed to be consumed, not studied.

What the Toolbelt Is Not​

The Toolbelt deliberately does not:

  • Replace the Solana Unity SDK’s RPC stack or wallet clients
  • Hide transaction submission behavior behind opaque retry loops
  • Guarantee “always-on” network success
  • Enforce monetization or business rules
  • Make protocol decisions on behalf of the application

Error handling is explicit. Control stays with the developer.

Runtime and Configuration​

ToolbeltRuntime​

ToolbeltRuntime is the entry point that wires everything together at application startup.

It:

  • Discovers the project’s SolanaConfiguration asset
  • Selects the primary RPC endpoint from an ordered list
  • Applies configured RPC rate limits
  • Sets Web3’s custom RPC and WebSocket endpoints
  • Initializes domain services before gameplay scripts run

Runtime checklist:

  • Place Web3.prefab in a scene so Toolbelt startup components are available.
  • Ensure ToolbeltRuntime can auto-discover SolanaConfiguration (asset is created and either referenced directly or discoverable via Resources).
  • Rely on default component resolution for core dependencies (for example: WalletManager, SolanaNftAccessManager, uploaders, and the storage service).

Failover logic does not live here. That responsibility belongs to the endpoint manager.

RPC Endpoint Management​

RpcEndpointManager​

RpcEndpointManager is responsible for:

  • Managing ordered RPC endpoint lists
  • Retrying across endpoints for retryable failures
  • Surfacing structured failure results

The Toolbelt does not override SDK request semantics. It coordinates when and where requests are issued, not how they are executed.

Service Provider Pattern​

The Toolbelt uses a service provider pattern to keep dependencies clean and swappable.

Service registration​

SolanaConfiguration.InitializeToolbeltServices registers:

  • Wallet services
  • Inventory services
  • Metadata query services
  • Pricing services
  • Storage services
  • Access control services

Scenes consume Toolbelt interfaces, not raw SDK types.

OGAL service lifecycle​

OGAL is intentionally not registered via IToolbeltServiceProvider.

Instead:

  • OGAL helpers are built in SolanaConfiguration.RebuildRuntimeServicesAsync
  • The service is created via BuildOwnerGovernedAssetLedgerServiceAsync
  • Accessed through SolanaConfiguration.ownerGovernedAssetLedgerService

This separation reinforces that OGAL is protocol-facing infrastructure, not just another gameplay service.

Wallet System​

WalletManager​

WalletManager is the orchestration layer for wallet state and session wiring. It:

  • Auto-restores known sessions on startup
  • Coordinates wallet selection and connection lifecycles
  • Surfaces explicit errors instead of masking failures

WalletSessionService​

WalletSessionService owns session persistence and rehydration, ensuring:

  • Session state is cached and reloaded deterministically
  • Wallet reconnection is transparent but not hidden behind implicit retries

WalletVerificationService​

WalletVerificationService handles wallet proof flows with:

  • Message signing for verification challenges
  • Verification persistence for predictable re-use
  • Explicit, caller-visible failure results

WalletTransactionService​

WalletTransactionService wraps transaction submission details:

  • Memo support is included as a first-class option
  • RPC failover is coordinated through endpoint management
  • Failures are surfaced immediately with no global implicit retry loop

Across all wallet services, error handling is explicit and control stays with the application.

OGAL Account Helpers​

OwnerGovernedAssetLedgerService​

This service wraps all OGAL interactions required by Unity projects.

It handles:

  • OGAL mint flows
  • Manifest updates
  • Authority rotation
  • Pause and namespace migration
  • PDA derivation
  • Runtime validation
  • Anchor error translation into actionable messages

It validates collection metadata and master edition authority before minting, ensuring:

  • Update authority matches expectations
  • Master editions are unique and valid
  • Misconfigured collections fail early and clearly

Creator verification​

Mint requests sanitize creator lists and enforce verified creator signatures.

If signatures are missing:

  • Creators are downgraded explicitly
  • Errors are surfaced clearly to the caller

Nothing is silently corrected.

Creator Tooling for UGC​

LevelEditorMintService​

This service is designed for in-game creation workflows.

It:

  • Serializes level or asset data
  • Produces metadata payloads
  • Emits OGAL-compatible mint requests
  • Leaves UI decisions to the host application

Integration with UI happens through IToolbeltUiBridge or custom game UI, not hardcoded Toolbelt dialogs.

SolanaNFTMintService​

This service handles NFT minting mechanics.

Key behaviors:

  • One transaction per mint
  • Rent is fetched once per data length and cached for subsequent mints
  • Memo support is included
  • If a submission fails, the service:
    • Forces a fresh blockhash for subsequent mints in the same call
    • Does not retry the failed mint automatically

There is no implicit retry loop. Failure is surfaced immediately.

Storage and Metadata Robustness​

The Toolbelt includes storage automation that goes well beyond basic SDK helpers.

Capabilities include:

  • Bundlr balance snapshotting
  • Automatic funding of the uploader wallet
  • Deposit enqueueing and top-ups
  • JSON upload orchestration for NFT metadata and level data

Metadata fetching is hardened via:

  • On-chain metadata account queries
  • Off-chain JSON loading with IPFS gateway fallback
  • Content hash validation to detect corrupted or stale payloads

Uploaders and when to use them​

The Toolbelt ships multiple uploaders so Unity projects can match storage behavior to the product’s needs. Each uploader is intentionally narrow in scope, so configuration stays explicit.

BundlrUploader​

Use when you need permanent Arweave persistence and want the Toolbelt to manage Bundlr funding and upload orchestration.

Best for:

  • Long-lived NFT metadata or player-created content
  • Workflows that already rely on Bundlr funding thresholds and balance snapshots

Unity configuration:

  • Bundlr endpoint and currency (via the Bundlr configuration asset)
  • Funding threshold and top-up policy for the uploader wallet

HttpJsonUploader​

Use when you want to send raw JSON to a custom HTTP endpoint you control (game backend, CDN ingestion, custom IPFS pinning service).

Best for:

  • Internal tools or private test environments
  • Storage stacks that are not Bundlr/Arweave

Unity configuration (via HttpUploaderProfile):

  • Endpoint: full URL to POST JSON to.
  • Headers: auth keys or API tokens required by your service.
  • Retry policy: max attempts and backoff for transient failures.
  • JSON response path: dot-path to the URL or CID returned by the service (for example data.url or result.cid).

HttpUploaderProfile​

This profile is the shared configuration asset for HTTP-based uploaders. It defines how the Toolbelt should call your service and how to parse the response.

Configure:

  • Endpoint
  • Headers
  • Retry policy
  • JSON response path for extracting the final URI that will be stored on-chain

Keep profiles environment-specific (dev/staging/prod) so Unity builds can switch endpoints without code changes.

HttpNftStorageUploader​

Use when you want to target hosted NFT storage services that return a URL or CID in a JSON payload (for example IPFS-backed storage with an HTTP API).

Best for:

  • Teams who want a managed storage provider instead of Bundlr
  • Pipelines that already produce metadata JSON and just need an HTTP upload

Unity configuration:

  • Assign an HttpUploaderProfile with the service’s endpoint, headers, retry policy, and JSON response path.
  • Ensure the JSON response path resolves to a usable URL or CID for metadata links.

Wallet Lifecycle Orchestration​

WalletManager and WalletSessionService​

These services manage:

  • Login providers
  • Editor testing keys
  • Verification state
  • Streaming health
  • Balance updates

They expose:

  • High-level async tasks
  • Unity events suitable for gameplay hooks

Memo support is surfaced through mint and transfer flows or via the TransactionMemoChecker utility. It is not emitted as a continuous event stream.

Access Control and Persistence​

SolanaNftAccessManager​

This service:

  • Watches NFT ownership
  • Caches unlock flags
  • Polls RPC state
  • Emits Unity events when access state changes

It enables token-gated gameplay and features without embedding blockchain logic directly into scenes.

Retry and Failure Semantics​

What the Toolbelt does not guarantee​

  • Automatic retries for every RPC or transaction
  • Guaranteed success on transient network failures

Most workflows intentionally avoid implicit retries to keep behavior deterministic and user-visible.

Where retries do exist​

Some flows opt into targeted retry behavior:

  • OGAL minting supports configurable transport retries
    • Optional secondary RPC failover
    • Creator-signature downgrade retries
    • See OwnerGovernedAssetLedgerService and MintTransportRetryDecision
  • RpcEndpointManager.ExecuteAsync retries across endpoints for retryable errors

Retry behavior is scoped, explicit, and configurable.

Design Principles​

  • Compress cost, not control
  • Prefer explicit failure over silent retries
  • Keep protocol truth separate from runtime convenience
  • Let applications own UX, recovery, and policy decisions

When to Use the Toolbelt​

Use the Toolbelt when you want:

  • OGAL integration without rewriting infrastructure
  • Unity-native workflows
  • Clear error surfaces for players and creators
  • Protocol correctness without protocol expertise

Do not use the Toolbelt if you want a black box.

Summary​

The Solana Toolbelt for Unity is not scaffolding.

It is:

  • Opinionated glue code developers actually want
  • Production-oriented infrastructure already backing live flows
  • A cost-compression layer that accelerates adoption without introducing lock-in

OGAL can exist without the Toolbelt.

OGAL can scale because of the Toolbelt.