godot-solana-sdk

name

godot-solana-sdk

description

Use this skill when building Solana-enabled games or apps in Godot 4 with the Godot Solana SDK. Triggers include: Solana transactions in GDScript, SPL tokens or NFTs in a Godot project, connecting browser or mobile wallets (Phantom, Solflare, Backpack) in a Godot game, calling Anchor smart contracts from GDScript, working with Candy Machine in Godot, or any mention of SolanaClient, Transaction, Pubkey, Keypair, WalletAdapter, or AnchorProgram in a Godot context. Do NOT use for non-Godot Solana SDKs (solana-py, solana-go, solana-web3.js).

Godot Solana SDK

A GDExtension (C++) plugin for Godot 4 that brings full Solana blockchain support to game development. Write GDScript to send transactions, manage wallets, mint NFTs, and interact with Anchor programs — on Windows, Linux, macOS, Web, Android, and iOS.

• Repo: https://github.com/Virus-Axel/godot-solana-sdk
• Docs: https://zenwiki.gitbook.io/solana-godot-sdk-docs
• Demo: https://zenrepublic.github.io/GodotSolanaSDKDemos/
• Asset Library: https://godotengine.org/asset-library/asset/3232
• Discord: https://discord.gg/9aFDCvqPgt

Security: Mainnet use is not yet security-audited. Crypto can be stolen. Use with care.

---

Installation

Via Godot Asset Library (recommended)

1. Search for "Solana" in the Godot Asset Library and install.
2. Install must go into the addons/ folder at the project root.
3. Go to Project → Project Settings → Plugins and enable SolanaSDK.
4. Verify SolanaService appears under Project Settings → Autoload.

Via GitHub Releases (manual) Download binaries from the Releases page, place them under res://bin/, and reload the project.

---

Configuration

After enabling the plugin, SolanaService is automatically added as an autoload singleton.

• RPC cluster: Select Mainnet or Devnet in the SolanaService inspector. Provide a custom RPC URL (e.g. from Helius) for better performance. The URL is also read from Project Settings → solana_sdk/client/default_url.
• Wallet: The WalletService child node handles auth.
  • Use Generated — deterministic wallet seeded from your machine ID (testing only).
  • Custom Wallet — path to a JSON file with the private key as a 64-byte array.

---

Core Nodes

Node	Inherits	Purpose
SolanaClient	Node	Low-level RPC calls to the Solana network
Transaction	SolanaClient	Build, sign, and send transactions
WalletAdapter	Node	Browser / mobile wallet integration
Account	Node	Mirror of an on-chain account, auto-syncs
AccountFetcher	SolanaClient	Bulk-fetch a list of Account nodes
SystemProgram	Node	SOL transfers and account creation
TokenProgram	Node	SPL Token instructions
AssociatedTokenAccountProgram	Node	Create Associated Token Accounts
ComputeBudget	Node	Set compute unit limits and priority fees
MplCandyMachine	Node	Candy Machine v3 minting
MplCandyGuard	Node	Candy Guard configuration
MplTokenMetadata	Node	Metaplex token metadata
AnchorProgram	Node	Generic interface for any Anchor program
SolanaUtils	Node	Base58/Base64 encoding, hashing utilities

Core Resources

Resource	Purpose
Pubkey	32-byte Solana public key / address
Keypair	ed25519 keypair for signing
Instruction	A single transaction instruction
AccountMeta	Account metadata entry in an instruction
CandyMachineData	Candy Machine configuration

---

Pubkey

# Create from base58 string
var pk: Pubkey = Pubkey.new_from_string("78GVwUb8ojcJVrEVkwCU5tfUKTfJuiazRrysGwgjqsif")

# Create from bytes
var pk: Pubkey = Pubkey.new_from_bytes(some_packed_byte_array)

# Derive a PDA (searches for valid bump, returns null on failure)
var program_key := Pubkey.new_from_string("CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR")
var pda: Pubkey = Pubkey.new_pda(["Level1"], program_key)

# Derive a PDA from raw byte seeds
var pda: Pubkey = Pubkey.new_pda_bytes([some_pubkey.to_bytes()], program_key)

# Derive Associated Token Address
var ata: Pubkey = Pubkey.new_associated_token_address(owner, mint, TokenProgram.get_pid())

# Random pubkey (for testing)
var pk: Pubkey = Pubkey.new_random()

# Convert
pk.to_string()           # base58 String
pk.to_bytes()            # PackedByteArray (32 bytes)

Pubkey.new_pda finds the canonical valid PDA (searches for bump). Pubkey.new_program_address does not search — it constructs from exact seeds. Use new_pda for normal PDA derivation.

---

Keypair

# Generate random keypair
var kp: Keypair = Keypair.new_random()

# From a deterministic seed
var seed = PackedByteArray(); seed.resize(32)
var kp: Keypair = Keypair.new_from_seed(seed)

# From Phantom private key (base58 string of 64 bytes)
var kp: Keypair = Keypair.new_from_bytes("3wUbDHMtMVQ...")

# From CLI-style JSON file
var kp: Keypair = Keypair.new_from_file("res://payer.json")

# Save to JSON file
kp.save_to_file("keypair.json")

# Inspect keys
kp.get_public_string()   # base58 String
kp.get_public_bytes()    # PackedByteArray (32 bytes)
kp.get_private_bytes()   # PackedByteArray (64 bytes)
kp.to_pubkey()           # Pubkey resource

# Sign and verify
var sig: PackedByteArray = kp.sign_message("hello".to_ascii_buffer())
var ok: bool = kp.verify_signature(sig, "hello".to_ascii_buffer())

---

SolanaClient (RPC)

Important: SolanaClient must be added as a child node (add_child(client)) for async HTTP requests to work. Remove and free it when done.

Signals:

http_request_completed(error: Error, response: Dictionary)
socket_response_received

var client: SolanaClient = SolanaClient.new()
add_child(client)

# Configure (optional — reads from Project Settings by default)
client.set_url_override("https://api.devnet.solana.com")
client.set_commitment("confirmed")   # "confirmed" | "finalized" | "processed"

# Make an RPC call, then await the signal
client.get_account_info("4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZAMdL4VZHirAn")
var response: Dictionary = (await client.http_request_completed)[1]
if response.has("result"):
    print(response["result"])

remove_child(client)
client.queue_free()

RPC methods (all void — listen to http_request_completed):

get_account_info(account)
get_balance(account)
get_latest_blockhash()
get_minimum_balance_for_rent_extemption(data_size)
get_transaction(signature)
get_signature_statuses(signatures, search_history)
get_signature_for_address(address, before, until)
get_token_account_balance(token_account)
get_token_accounts_by_owner(owner, mint, program_id)
get_token_supply(token_mint)
get_program_accounts(program_address, filters, with_context)
get_multiple_accounts(accounts)
request_airdrop(address, lamports)
send_transaction(encoded_transaction, max_retries, skip_preflight)
simulate_transaction(encoded_transaction, sig_verify, replace_blockhash, ...)

DAS (Digital Asset Standard) methods:

get_asset(asset_id)
get_asset_proof(asset_id)
get_assets_by_owner(owner, page, limit, show_fungible)
get_assets_by_authority(authority, page, limit)
get_assets_by_creator_address(creator, only_verified, page, limit)
get_assets_by_group(group_key, group_value, page, limit)

WebSocket subscriptions:

client.account_subscribe(account_key, Callable(self, "_on_account_changed"))
client.signature_subscribe(signature, Callable(self, "_on_confirmed"), "finalized")
client.program_subscribe(program_id, Callable(self, "_on_program_change"))
client.unsubscribe_all(callback)   # call when done; keep client in tree while subscribed

---

Transaction

Workflow: set_payer → add_instruction → update_latest_blockhash → sign_and_send

Signals:

transaction_response_received(response: Dictionary)
transaction_simulation_failed(message_and_data: Array)
processed
confirmed
finalized
fully_signed
blockhash_updated

var payer: Keypair = Keypair.new_from_file("res://payer.json")
var receiver: Pubkey = Pubkey.new_from_string("78GVwUb8ojcJVrEVkwCU5tfUKTfJuiazRrysGwgjqsif")

var tx = Transaction.new()
add_child(tx)   # must be in scene tree

tx.set_payer(payer)
tx.add_instruction(SystemProgram.transfer(payer, receiver, 500_000))   # 0.0005 SOL
tx.update_latest_blockhash()
tx.sign_and_send()

var response = await tx.transaction_response_received
if response.has("result"):
    print("Signature:", response["result"])

# Await confirmation stages
await tx.confirmed
await tx.finalized

Other useful methods:

tx.set_instructions(instructions_array)
tx.set_signers([payer, another_keypair])
tx.sign()                        # signs without sending
tx.send()                        # sends without signing
tx.serialize() -> PackedByteArray
tx.get_message_hash() -> String

# Reconstruct from bytes (e.g. after passing serialized tx to wallet)
var new_tx = Transaction.new_from_bytes(tx.serialize())
new_tx.set_signers([payer])      # signers are not stored in bytes
new_tx.update_latest_blockhash()
new_tx.sign()
new_tx.send()

Handle simulation failures:

var data = await tx.transaction_simulation_failed
push_error("Simulation failed: " + data[0])
print("Logs:", data[1].get("logs", []))

---

SystemProgram

# Transfer SOL
SystemProgram.transfer(sender, receiver, lamports) -> Instruction

# Create a new on-chain account
SystemProgram.create_account(from_keypair, new_account_keypair, lamports, space_bytes, owner_program) -> Instruction

# Create account with seed
SystemProgram.create_account_with_seed(from, base, seed, lamports, space, owner) -> Instruction

# Well-known pubkeys
SystemProgram.get_pid()
SystemProgram.get_sysvar_clock_pubkey()
SystemProgram.get_sysvar_rent_pubkey()
# ... and all other sysvar pubkeys

---

TokenProgram (SPL Token)

Use transfer_checked (requires mint + decimals), not transfer.

# Initialize a new mint (MINT_SIZE = 82 bytes)
TokenProgram.initialize_mint(mint_keypair, mint_authority, freeze_authority, decimals) -> Instruction

# Initialize a token account (MINT_ACCOUNT_SIZE = 165 bytes)
TokenProgram.initialize_account(account_keypair, mint_keypair, owner) -> Instruction

# Mint tokens
TokenProgram.mint_to(mint, account, owner, mint_authority, amount) -> Instruction

# Transfer with decimals verification
TokenProgram.transfer_checked(source, mint, destination, source_authority, amount, decimals) -> Instruction

# Freeze a token account
TokenProgram.freeze_account(account, mint, freeze_authority) -> Instruction

# Change authority
TokenProgram.set_authority(mint, current_authority, new_authority, authority_type) -> Instruction
# authority_type: 1=MintTokens, 2=FreezeAccount, 3=AccountOwner, 4=CloseAccount

TokenProgram.get_pid() -> Pubkey

Create Mint + Initialize (full example)

const MINT_SIZE := 82

func create_token_mint(payer: Keypair) -> Keypair:
    var client = SolanaClient.new()
    add_child(client)
    client.get_minimum_balance_for_rent_extemption(MINT_SIZE)
    var lamports = (await client.http_request_completed)[1]["result"]
    remove_child(client); client.queue_free()

    var mint_kp: Keypair = Keypair.new_random()
    var tx := Transaction.new()
    add_child(tx)

    tx.add_instruction(SystemProgram.create_account(payer, mint_kp, lamports, MINT_SIZE, TokenProgram.get_pid()))
    tx.add_instruction(TokenProgram.initialize_mint(mint_kp, payer, payer, 0))
    tx.set_payer(payer)
    tx.update_latest_blockhash()
    tx.sign_and_send()
    await tx.transaction_response_received
    await tx.confirmed
    return mint_kp

---

AssociatedTokenAccountProgram

# Derive the ATA address (does not create it)
var ata: Pubkey = Pubkey.new_associated_token_address(owner, mint, TokenProgram.get_pid())

# Create the ATA (instruction — add to transaction)
AssociatedTokenAccountProgram.create_associated_token_account(payer, owner, mint, TokenProgram.get_pid()) -> Instruction

AssociatedTokenAccountProgram.get_pid() -> Pubkey

AssociatedTokenAccountProgram does not have get_associated_token_address. Use Pubkey.new_associated_token_address to derive the address.

---

ComputeBudget

# Add to transaction before other instructions
tx.add_instruction(ComputeBudget.set_compute_unit_price(50_000))  # micro-lamports
tx.add_instruction(ComputeBudget.set_compute_unit_limit(200_000))

Transactions already have default unit_limit = 800000 and unit_price = 8000 built in. Use ComputeBudget instructions when you need explicit control over priority fees.

---

WalletAdapter (Browser / Mobile)

Primarily intended for web/browser platform exports. Desktop and mobile require tweaking.

# WalletAdapter node must be in the scene tree.
$WalletAdapter.set_wallet_type(WalletAdapter.PHANTOM)  # PHANTOM, SOLFLARE, BACKPACK, LEDGER, ...
$WalletAdapter.connect_wallet()
await $WalletAdapter.connection_established

var pubkey: Pubkey = $WalletAdapter.get_connected_key()

# Use WalletAdapter as payer — triggers wallet popup on sign
$Transaction.set_payer($WalletAdapter)
$Transaction.add_instruction(SystemProgram.transfer($WalletAdapter, Pubkey.new_random(), 1_000_000))
$Transaction.update_latest_blockhash()
$Transaction.sign()
await $Transaction.fully_signed
$Transaction.send()
var response = await $Transaction.transaction_response_received

Sign a text message:

$WalletAdapter.sign_text_message("Hello Godot")
var signature: PackedByteArray = await $WalletAdapter.message_signed  # 64 bytes

Supported wallets (enum values): PHANTOM, SOLFLARE, BACKPACK, LEDGER, TREZOR, TRUST, WALLETCONNECT, COINBASE, NIGHTLY, COIN98, ALPHA, AVANA, BITKEEP, BITPIE, CLOVER, COINHUB, FRACTAL, HUOBI, HYPERPAY, KEYSTONE, KRYSTAL, MATH, NEKO, NUFI, ONTO, PARTICLE, SAFEPAL, SAIFU, SALMON, SKY, SOLONG, SPOT, TOKENARY, TOKENPOCKET, TORUS, UNSAFEBURNER, XDEFI

---

AnchorProgram

Interact with any Anchor smart contract by loading its IDL.

Setup (prefer inspector over code):

• Add an AnchorProgram node to your scene.
• Set pid to the program's base58 address.
• Assign the IDL JSON resource to json_file and set try_from_json_file = true, or fetch it from the chain with try_from_pid = true.

Signals:

idl_fetched
account_fetched(account_data: Dictionary)
all_account_fetched

Call an instruction:

# Inspect anchor_program.idl in the Godot inspector to verify account order and arg types.
var program_key := Pubkey.new_from_string(PROGRAM_ID)
var level_pda := Pubkey.new_pda(["Level1"], program_key)
var vault_pda := Pubkey.new_pda(["Vault1"], program_key)

var ix: Instruction = $AnchorProgram.build_instruction(
    "restartLevel",           # exact instruction name from IDL
    [
        level_pda,            # accounts in IDL order
        vault_pda,
        SolanaService.wallet.get_kp(),   # signer
        SystemProgram.get_pid()          # system program
    ],
    AnchorProgram.u64(int(prize_sol * pow(10, 9)))
)

var tx := Transaction.new()
add_child(tx)
tx.set_payer(SolanaService.wallet.get_kp())
tx.add_instruction(ix)
tx.update_latest_blockhash()
tx.sign_and_send()
var result = await tx.transaction_response_received

Typed argument helpers:

AnchorProgram.u8(val)   AnchorProgram.u16(val)  AnchorProgram.u32(val)  AnchorProgram.u64(val)
AnchorProgram.s8(val)   AnchorProgram.s16(val)  AnchorProgram.s32(val)  AnchorProgram.s64(val)
AnchorProgram.f32(val)  AnchorProgram.f64(val)  AnchorProgram.option(val)

Fetch an account:

$AnchorProgram.fetch_account("CandyMachine", "2kJKEGhqGXJJtoWPfxnKq1Y2bN4eF9GQ39SAcGu8TDZn")
var data: Dictionary = await $AnchorProgram.account_fetched

---

MplCandyMachine

# Initialize a Candy Machine account (InitializeV2 in Metaplex program)
MplCandyMachine.initialize(authority, candy_machine_account, collection_mint, candy_machine_data, pnft) -> Instruction

# Mint an NFT (MintV2 in Metaplex program)
MplCandyMachine.mint(payer, receiver, mint, collection_mint, collection_update_authority, candy_machine_key) -> Instruction

# Add config lines to hidden data section
MplCandyMachine.add_config_lines(candy_machine_key, authority, config_lines, index) -> Instruction

# Derive the candy machine authority PDA
MplCandyMachine.new_candy_machine_authority_pda(candy_machine_key) -> Pubkey

# Fetch candy machine account data (listens to http_request_completed)
candy_machine_node.get_candy_machine_info(candy_machine_key)

MplCandyMachine.get_pid() -> Pubkey

---

SolanaUtils

SolanaUtils.bs58_decode(str: String) -> PackedByteArray
SolanaUtils.bs58_encode(bytes: PackedByteArray) -> String
SolanaUtils.bs64_encode(bytes: PackedByteArray) -> String
SolanaUtils.bs64_decode(str: String) -> PackedByteArray
SolanaUtils.sha256_hash_array(contents: PackedStringArray) -> PackedByteArray

---

SolanaService (Helper Layer)

SolanaService is the autoload singleton added by the plugin. Its wallet child node is a WalletService that abstracts keypair vs. wallet adapter login.

# Get the connected wallet's pubkey (works for both keypair and adapter)
var pubkey: Pubkey = SolanaService.wallet.get_pubkey()

# Get the keypair or WalletAdapter as a signer
var signer = SolanaService.wallet.get_kp()   # Keypair or WalletAdapter

# Check login state
var logged_in: bool = SolanaService.wallet.is_logged_in()

# Request an airdrop via SolanaService helper
var balance = await SolanaService.get_balance(pubkey.to_string())

---

Error Handling

# HTTP request pattern
var params = await client.http_request_completed
var error: Error = params[0]
var response: Dictionary = params[1]

if error != OK:
    push_error("Connection error: %d" % error)
    return
if response.is_empty() or response.has("error"):
    push_error("RPC error: " + str(response.get("error", {}).get("message", "unknown")))
    return
var result = response["result"]

---

Common Pitfalls

• SolanaClient must be in the scene tree. Call add_child(client) before making requests; remove and queue_free() when done.
• TokenProgram.transfer_checked is the correct method, not transfer. It requires the mint address and decimals to prevent cross-mint transfers.
• Pubkey.new_associated_token_address is how you derive ATAs — not a method on AssociatedTokenAccountProgram.
• Signers are not stored in serialized transaction bytes. After Transaction.new_from_bytes, call set_signers([...]) again before signing.
• AnchorProgram IDL loading: Set pid and try_from_json_file/try_from_pid in the Godot inspector, not from GDScript.
• Pubkey.new_pda returns null if it cannot find a valid PDA. Always null-check.
• WalletAdapter is primarily for Web exports. Use Keypair for desktop/server builds.