Skip to main content

OGAL Integration

This document explains how OGAL works on-chain today, aligned with the current owner_governed_asset_ledger program implementation.
It is written for developers integrating OGAL directly or through the Solana Toolbelt. If you want to learn more about using OGAL, check out the OGAL Guide.

OGAL is intentionally narrow in scope:

  • Defines canonical asset truth
  • Enforces ownership-based update rights
  • Preserves provenance across time and platforms

OGAL does not escrow assets, move funds, define pricing, or enforce monetization.

Reference​

Email protocol analogy​

If it helps, think of OGAL like email infrastructure:

  • Namespace ↔ domain
  • Manifest ↔ message
  • OGAL program ↔ mail server
  • Clients ↔ email clients

Wallet requirements​

End users do not need a wallet to read OGAL assets. Wallets are only required for creators or namespace authorities who mint or update assets (to pay gas).

  • Readers: no wallet required
  • Creators / namespace authorities: wallet required to mint or update (gas fees)

Core Mental Model​

  • Ownership lives in SPL tokens, not inside OGAL.
  • Truth lives in PDAs, not inside a platform database.
  • Updates require proof of ownership, not platform permission.

OGAL observes and enforces state. It does not intermediate custody.

Protocol Identity (mainnet-beta)​

These are the shared live deployment identifiers for the public OGAL deployment on Solana mainnet-beta. If you run a custom deployment, update every client to the new program ID, namespace, PDAs, and collection mint.

ItemValue
Program IDGwMpopxNkDYsnucBRPf47QSEsEzA3rS1o6ioMX78hgqx
Maintainer authoritynanoNv13vp2NetbjudoCZgc2EvWs54JdtDkrmJpTDNJ
Canonical namespace3Bc5ARkDGM2ZdAe8EjwHMmNrXvpSzQVcPug7MSp4Qhbw
Canonical config PDA5bhVoogdhY5VYuLuUuMXaiNrvP4zbmP1wNWstUUvmiF5
Mint-authority PDAG7skWhSjK6oskMKMuCbVuRQSVvrhc1VN1nQYLHR8ewL5
Collection mintEhULHuQtpaKUZSdv1kQR7XwYGRfEaU8b1Y7JkbFGQHxW

The namespace/config PDA/collection mint values above are for the Token Toss UGC Level Data dataset. Other datasets can use the same program ID while pointing at distinct namespaces, derived PDAs, and collection mints.

Namespaces behave like folders for UGC asset sets. Multiple namespaces can exist per experience, and creators must connect a wallet and pay gas/fees to publish. Developers should route assets to an existing namespace whenever possible or create reusable namespaces for new datasets.

PDA seed recipes​

  • Config PDA: ["config", namespace_pubkey]
  • Auth PDA: ["auth", config_pubkey]
  • Object manifest PDA: ["object_manifest", config_pubkey, object_id_le_bytes]
  • Object mint PDA: ["object_mint", object_manifest_pubkey]

These seeds are deterministic and shared across every client pointed at the mainnet-beta deployment. Custom deployments must update clients to match their own namespace and derived PDAs.

Canonical Asset Identity​

Each OGAL asset is anchored by two on-chain accounts:

  1. ObjectManifest PDA
  2. Object mint PDA

Together, these define permanent identity.

ObjectManifest PDA​

The ObjectManifest account is the registry’s source of truth. It stores the stable identity fields plus the mutable manifest fields that are allowed to evolve.

Identity and provenance fields​

  • object_id
    Stable identifier for the asset.

  • config
    Reference to the registry configuration that governs this manifest.

  • mint
    The paired object mint that represents the asset as an NFT.

  • creator
    Original creator recorded in the manifest.

Mutable manifest fields​

  • metadata_uri
    The off-chain metadata pointer referenced by this manifest.

  • manifest_hash
    Integrity hash for the referenced content.

  • is_active
    Availability flag for consumption by platforms.

Determinism and zero-copy storage fields​

The manifest also persists fields that support deterministic PDA verification and safe fixed-size storage layouts:

  • bump
    Manifest PDA bump seed.

  • mint_bump
    Mint PDA bump seed.

  • initialized
    Manifest initialization flag.

  • minted
    Minting completion flag.

  • metadata_uri_length
    Actual URI byte length in the fixed buffer.

  • metadata_uri_padding
    Padding value used to maintain deterministic account layout.

Practical identity rule​

Consumers should treat:

ObjectManifest PDA address plus recorded mint

as the canonical handle for an OGAL asset. Metadata can change, but this identity does not drift.

Transfers and Custody​

OGAL does not manage custody.

  • Ownership transfers happen via standard SPL Token transfers.
  • OGAL never escrows tokens.
  • OGAL never mediates transfers.

OGAL only verifies ownership at the moment a holder attempts an authorized manifest update.

Ownership Verification​

When a holder requests a manifest update, they must provide a token account that:

  • belongs to the signer
  • matches the expected object mint
  • holds a positive balance

If any of these checks fail, the update is rejected.

This is the core enforcement point that keeps update rights aligned with real token ownership.

Mutability and Update Control​

All mutable changes flow through the update object manifest instruction.

This instruction is the only supported path to change:

  • metadata URI
  • manifest hash
  • activation status

The instruction enforces both ownership proofs and Metaplex constraints.

Metaplex validations inside update object manifest​

In the update object manifest instruction (programs/owner_governed_asset_ledger/src/lib.rs), the program validates:

  • metadata_program must match the Metaplex Token Metadata program id
    metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s

  • object_metadata must be the correct Metaplex metadata PDA derived from the object mint
    Derived from: ["metadata", TOKEN_METADATA_PROGRAM_ID, mint]

Callers must pass the metadata PDA derived from the mint and the Metaplex program account. If either is incorrect, the instruction fails before any state changes occur.

Auth PDA requirement and how it is used​

The instruction requires an auth PDA derived from:

["auth", config_pubkey]

OGAL uses this auth PDA as the Metaplex update authority when CPIing into Metaplex. This is a deliberate design choice that:

  • prevents arbitrary signers from updating token metadata directly
  • ensures updates only occur through OGAL rules
  • keeps Metaplex metadata aligned with OGAL manifest truth

CPI metadata updates​

OGAL does not overwrite token metadata wholesale.

During an update:

  1. OGAL reads the existing Metaplex metadata account.
  2. OGAL constructs a DataV2 payload by copying all existing fields:
    • name
    • symbol
    • creators
    • collection
    • seller fee basis points
    • any other metadata fields present
  3. OGAL overwrites only the uri field.
  4. OGAL issues an UpdateMetadataAccountV2 CPI call using the auth PDA as update authority.

This preserves all important metadata attributes while still allowing the owner to update the metadata URI referenced by the manifest.

Manifest updates performed by OGAL​

After successful validation and CPI:

  • metadata_uri is updated in the manifest
  • manifest_hash is updated in the manifest
  • is_active may be updated
  • the same manifest PDA and object_id remain stable

This makes provenance tracking and downstream references durable.

Instruction Map, Limits, and Invariants​

Instruction map​

  • Admin: initialize, set_authority, set_paused, migrate_config_namespace, rotate_collection_authority
  • Content flow: mint_object_nft, update_object_manifest

Hard limits​

  • Metadata URI length: 200 bytes
  • Metaplex name length: 32 bytes max
  • Metaplex symbol length: 10 bytes max
  • Creators: max 5 entries; shares must sum to 100
  • Seller fee basis points: 0–10,000

Invariants​

  • Paused config blocks mint_object_nft
  • Auth PDA must be the Metaplex update authority
  • update_object_manifest only changes manifest_hash, metadata_uri, and is_active

Required Sysvars​

rent (mandatory)​

  • The rent sysvar must always be included.
  • OGAL validates that it matches sysvar::rent::id().

instructions (optional)​

  • The instructions sysvar is optional.
  • OGAL validates it only if it is present.
  • If supplied, it must match sysvar::instructions::id().

Treat the on-chain account struct for the update instruction as the authoritative source of required accounts. Do not guess the sysvar list.

Collection sizing (sized vs unsized)​

OGAL can mint into either sized or unsized Metaplex collections. Make sure your collection configuration matches the instruction inputs.

  • Sized collections: include the sysvar instructions account so the program can validate collection sizing behavior.
  • Unsized collections: ensure the collection has a unique master edition and still pass the sysvar instructions account when required by your client.

Events & observability​

OGAL emits events you can subscribe to over WebSocket using the program IDL:

  • ObjectMinted
  • ManifestUpdated
  • PauseStatusUpdated

To read logs, connect to a Solana WebSocket endpoint and decode program logs with the OGAL IDL (e.g., Anchor event parsing) for the program ID in this doc.

Troubleshooting​

Common failures and quick checks:

  • Collection update authority mismatch: the collection update authority must match the configured authority/PDAs for the deployment.
  • Missing sysvars: always include the rent sysvar and include the instructions sysvar when your client expects it.

Unity (base64) transaction simulation:

solana simulate --encoding base64 <BASE64_TRANSACTION>

Off-Chain Metadata and Integrity​

OGAL uses a metadata URI that typically points to Arweave, IPFS, or similar permanent storage.

The program stores:

  • metadata_uri for retrieval
  • manifest_hash for integrity validation

Clients should:

  • fetch the URI
  • validate contents against manifest_hash (when applicable)
  • treat OGAL state as the truth source, not the remote JSON alone

What OGAL Guarantees​

  • Canonical identity anchored in PDAs
  • Ownership-based update control enforced on-chain
  • Stable provenance through a persistent manifest PDA and object_id
  • Safe, minimal metadata mutations that preserve Metaplex fields
  • Platform-agnostic reuse without lock-in

What OGAL Intentionally Does Not Do​

  • Escrow or custody assets
  • Retry failed transactions
  • Enforce monetization or payouts
  • Provide marketplaces or discovery layers

Those belong to platforms, markets, and higher-layer tooling.

Integration Guidance​

  • Verify assets using the ObjectManifest PDA, not off-chain metadata alone.
  • Treat the mint as representation, not the truth source.
  • Expect metadata URI to change without identity changing.
  • When calling update operations, always pass:
    • the correct Metaplex metadata PDA derived from the mint
    • the Metaplex metadata program id account
    • the OGAL auth PDA for the relevant config
    • rent sysvar (always)
    • instructions sysvar only if your invocation includes it

Final Framing​

OGAL defines what is true.

Token ownership is proven via SPL Token accounts.
Metadata evolves safely through OGAL-governed CPI.
Identity never drifts because the manifest PDA remains the anchor.

Everything else builds above these guarantees.