Go | Solana

2.0.0, Go modüllerinin ilk kararlı sürümüdür; bu yüzden geçiş yapılacak bir şey yok. 2.0 geçiş kılavuzu, Rust ve TypeScript için aynı yetenek ayrımını ele alır.

Kurulum

Her arka uç kendi Go modülüdür; bu sayede derlemenizde ve modül grafiğinizde yalnızca içe aktardığınız arka uçlar yer alır:

go get github.com/solana-foundation/solana-keychain/go/core/v2                # Interfaces, errors, helpers
go get github.com/solana-foundation/solana-keychain/go/signers/memory/v2      # Local keypair signer
go get github.com/solana-foundation/solana-keychain/go/signers/vault/v2       # HashiCorp Vault
go get github.com/solana-foundation/solana-keychain/go/signers/awskms/v2      # AWS KMS
go get github.com/solana-foundation/solana-keychain/go/signers/gcpkms/v2      # GCP KMS
go get github.com/solana-foundation/solana-keychain/go/signers/privy/v2       # Privy
go get github.com/solana-foundation/solana-keychain/go/signers/turnkey/v2     # Turnkey
go get github.com/solana-foundation/solana-keychain/go/signers/fireblocks/v2  # Fireblocks
go get github.com/solana-foundation/solana-keychain/go/signers/cdp/v2         # Coinbase Developer Platform
go get github.com/solana-foundation/solana-keychain/go/signers/crossmint/v2   # Crossmint
go get github.com/solana-foundation/solana-keychain/go/signers/dfns/v2        # Dfns
go get github.com/solana-foundation/solana-keychain/go/signers/openfort/v2    # Openfort
go get github.com/solana-foundation/solana-keychain/go/signers/para/v2        # Para
go get github.com/solana-foundation/solana-keychain/go/signers/utila/v2       # Utila
go get github.com/solana-foundation/solana-keychain/go/signers/fordefi/v2     # Fordefi

Modüller go/<module>/v2.0.0 biçiminde etiketlenir (örneğin go/signers/memory/v2.0.0). google.golang.org/api tarafından belirlenen alt sınır nedeniyle Go 1.25.8 gerektiren gcpkms dışında her modül Go 1.25.0 gerektirir. Ledger yalnızca Rust'a özgüdür ve Go modülü yoktur.

solana-go v2 ve v1 İşlemleri

Modüller github.com/solana-foundation/solana-go/v2 v2.0.0 üzerine inşa edilmiştir ve *solana.Transaction türünü kabul eder. Legacy, v0 ve v1 (solana.MessageVersionV1) işlemleri desteklenir; yalnızca UseProgramCall: true ile kullanılan Fireblocks bunun dışındadır ve yalnızca legacy ile v0 işlemlerini kabul eder.

Temel Kullanım

Her imzalayıcı, temel core.SolanaSigner arayüzünü (Pubkey, SignMessage, IsAvailable) uygular. Metotlar bir context.Context alır ve engelleyicidir (blocking). Her arka uç ayrıca tam olarak bir yetenek arayüzünü uygular:

core.TransactionSigner: SignTransaction, işleminizi olduğu gibi imzalar.
core.ModifyingSigner: ModifyAndSignTransaction, sağlayıcının işlemi yeniden yazmasına izin verir, ardından imzalar.
core.SendingSigner: SignAndSendTransaction, işlemi sağlayıcının imzalayıp yayınlamasını sağlar.

Her arka uç paketi bir Config struct'ı ve bir New yapıcısı sunar:

import (
	"context"
	"fmt"

	"github.com/solana-foundation/solana-go/v2"
	"github.com/solana-foundation/solana-keychain/go/core/v2"
	"github.com/solana-foundation/solana-keychain/go/signers/memory/v2"
)

func signWithKeychain(ctx context.Context, tx *solana.Transaction) error {
	signer, err := memory.New(memory.Config{PrivateKeyPath: "/path/to/id.json"})
	if err != nil {
		return err
	}

	if !signer.IsAvailable(ctx) {
		return core.NewSignerError(core.CodeNotAvailable, "signer offline")
	}

	result, err := signer.SignTransaction(ctx, tx)
	if err != nil {
		return err
	}
	fmt.Println("signature:", result.Signature)
	fmt.Println("complete:", result.IsComplete())
	// result.EncodedTransaction is the base64 wire transaction
	return nil
}

SignTransaction ve ModifyAndSignTransaction, bir core.SignedTransaction (EncodedTransaction, Signature, Completeness) döndürür. Uzak HTTP arka uçları isteğe bağlı bir HTTPClient ve HTTPClientConfig (zaman aşımları) kabul eder. Varsayılan istemci HTTPS'i zorunlu kılar; kendi istemcinizi sağlarsanız bu kontrol atlanır ve güvenlik duruşunun sorumluluğu size ait olur.

İmzalayıcı Yetenekleri

Bir işlemi imzalayamayan arka uçta SignTransaction metodu hiç bulunmaz; bu yüzden yetenek, somut türler için derleme zamanında bilinen bir olgudur, bir core.SolanaSigner için ise tür doğrulamasıyla (type assertion) belirlenir:

Arka uç	Yetenek	`SignMessage`
memory, vault, privy, turnkey, awskms, gcpkms, fireblocks, dfns, para, openfort	`TransactionSigner`	Evet
cdp	`TransactionSigner`	Yalnızca UTF-8 yükleri
utila	`TransactionSigner`	`CodeSigningFailed` ile başarısız olur
fordefi black box (`fordefi.BlackBoxSigner`)	`TransactionSigner`	Evet
fordefi native manual (`fordefi.NativeManualSigner`)	`ModifyingSigner`	Evet
fordefi native auto (`fordefi.NativeAutoSigner`)	`SendingSigner`	Evet
crossmint	`SendingSigner`	`CodeSigningFailed` ile başarısız olur

switch s := signer.(type) {
case core.SendingSigner:
	sig, err := s.SignAndSendTransaction(ctx, tx)
case core.ModifyingSigner:
	signed, err := s.ModifyAndSignTransaction(ctx, tx)
case core.TransactionSigner:
	signed, err := s.SignTransaction(ctx, tx)
}

Başlatma

Ayrı bir Init adımı yoktur. Privy, Fireblocks, Dfns, Crossmint, Para, Openfort ve Utila cüzdan adresini New içinde çözümler; yapıcılarının bir context.Context almasının nedeni budur. İmzalayıcıları her zaman New ile oluşturun: sıfır değerli bir Crossmint, Para veya Utila imzalayıcısı, sıfır adres için imzalamak yerine CodeNotInitialized ile başarısız olur.

Herhangi Bir İmzalayıcı ile İmzala ve Gönder

core.SignAndSendTransaction, imzalayıcının yapısı ne olursa olsun bir işlemi zincire ulaştırır. Bir SendingSigner işlemi sağlayıcısı üzerinden yayınlar ve gönderme fonksiyonunu yok sayar; diğer tüm yapılarda imzalama yapılır ve base64 sonucu sizin fonksiyonunuz yayınlar; ModifyingSigner için bu sonuç, sağlayıcısının yeniden yazdığı işlemdir. Core'un herhangi bir RPC bağımlılığı yoktur:

import "github.com/solana-foundation/solana-go/v2/rpc"

client := rpc.New("https://api.devnet.solana.com")

sig, err := core.SignAndSendTransaction(ctx, signer, tx,
	func(ctx context.Context, encoded string) (solana.Signature, error) {
		return client.SendEncodedTransaction(ctx, encoded)
	})

Toplu İmzalama

Toplu imzalama, serbest yardımcı fonksiyonlar olarak sunulur; eşzamanlı çalışır ve hız sınırlı API'ler için isteğe bağlı olarak istek başına kademelendirme (stagger) uygulanabilir:

sigs, err := core.SignMessages(ctx, signer, [][]byte{msg1, msg2}, core.BatchOptions{
	MaxConcurrency: 4, // 0 = unbounded
	RequestDelay:   50 * time.Millisecond,
})

signed, err := core.SignTransactions(ctx, signer, txs, core.BatchOptions{})

core.SignTransactions bir core.TransactionSigner alır; bu nedenle yayını kendisi yöneten imzalayıcılar (Crossmint, Fordefi native auto) ile Fordefi native manual bu yolla toplu işlenemez; bunları her seferinde tek bir işlemle çağırın. Çağrıları sağlayıcı tarafında iş oluşturan bir imzalayıcı (UseProgramCall ile Fireblocks) bunu core.BatchServerSideEffects aracılığıyla bildirir ve toplu işlem bu durumda ardışık olarak çalışır.

Arka Uç Yapılandırması

Memory

PrivateKey (ham bayt), PrivateKeyString (base58 veya bir [1,2,...] bayt dizisi) ya da PrivateKeyPath (Solana CLI keypair dosyası) seçeneklerinden tam olarak birini belirtin:

import "github.com/solana-foundation/solana-keychain/go/signers/memory/v2"

signer, err := memory.New(memory.Config{
	PrivateKeyPath: "/path/to/id.json",
})

Go, belleği sıfırlamak için güvenilir bir yol sunmaz: çöp toplayıcı, anahtar baytlarını toplama gerçekleşene kadar kopyalayıp tutabilir (memory keypair'leri ve Crossmint ile Openfort'un yerel olarak türettiği anahtarlar). Yerel anahtar kullanan arka uçlarda tüm işlem belleğini hassas kabul edin.

HashiCorp Vault

import "github.com/solana-foundation/solana-keychain/go/signers/vault/v2"

signer, err := vault.New(vault.Config{
	VaultAddr: "https://vault.example.com:8200",
	Token:     "hvs.xxxxx",
	KeyName:   "my-solana-key",
	Pubkey:    "base58_public_key",
})

AWS KMS

import "github.com/solana-foundation/solana-keychain/go/signers/awskms/v2"

signer, err := awskms.New(ctx, awskms.Config{
	KeyID:     "alias/my-solana-key",
	PublicKey: "base58_public_key",
	Region:    "us-east-1", // optional
})

GCP KMS

import "github.com/solana-foundation/solana-keychain/go/signers/gcpkms/v2"

signer, err := gcpkms.New(ctx, gcpkms.Config{
	KeyName:   "projects/my-project/locations/us-east1/keyRings/my-ring/cryptoKeys/my-key/cryptoKeyVersions/1",
	PublicKey: "base58_public_key",
})
if err != nil {
	return err
}
defer signer.Close()

Privy

import "github.com/solana-foundation/solana-keychain/go/signers/privy/v2"

signer, err := privy.New(ctx, privy.Config{
	AppID:     "app_id",
	AppSecret: "app_secret",
	WalletID:  "wallet_id",
})

Turnkey

import "github.com/solana-foundation/solana-keychain/go/signers/turnkey/v2"

signer, err := turnkey.New(turnkey.Config{
	APIPublicKey:   "api_public_key",
	APIPrivateKey:  "api_private_key",
	OrganizationID: "org_id",
	PrivateKeyID:   "private_key_id",
	PublicKey:      "base58_public_key",
})

Fireblocks

import "github.com/solana-foundation/solana-keychain/go/signers/fireblocks/v2"

signer, err := fireblocks.New(ctx, fireblocks.Config{
	APIKey:         "api_key",
	PrivateKeyPEM:  "-----BEGIN RSA PRIVATE KEY-----\n...",
	VaultAccountID: "0",
	AssetID:        "SOL",  // or "SOL_TEST" for devnet
	UseProgramCall: false, // true signs via sign-only PROGRAM_CALL (legacy/v0, hot wallet)
})

CDP (Coinbase Developer Platform)

import "github.com/solana-foundation/solana-keychain/go/signers/cdp/v2"

signer, err := cdp.New(cdp.Config{
	APIKeyID:     "api_key_id",
	APIKeySecret: "api_key_secret", // base64 Ed25519
	WalletSecret: "wallet_secret",  // base64 PKCS#8 DER
	Address:      "base58_address",
	Network:      cdp.NetworkMainnet, // or cdp.NetworkDevnet; required for address lookup tables
})

CDP'nin SignMessage metodu yalnızca UTF-8 yüklerini kabul eder.

Crossmint

Crossmint yalnızca gönderim yapar: API'si onaylanan her işlemi sunucu tarafında yürütür; bu yüzden *crossmint.Signer türünde SignAndSendTransaction vardır, SignTransaction yoktur. İşleminiz asla değiştirilmez; döndürülen imza, Crossmint'in zincire işlediği işlemi tanımlar. Crossmint gas ücretini sponsor ederse bu işlem sizinkinden farklı olabilir.

import "github.com/solana-foundation/solana-keychain/go/signers/crossmint/v2"

signer, err := crossmint.New(ctx, crossmint.Config{
	APIKey:        "api_key",
	WalletLocator: "wallet_locator",
	SignerSecret:  "", // optional xmsk1_ secret: auto-approves what Crossmint presents
})

sig, err := signer.SignAndSendTransaction(ctx, tx)

Dfns

import "github.com/solana-foundation/solana-keychain/go/signers/dfns/v2"

signer, err := dfns.New(ctx, dfns.Config{
	AuthToken:     "auth_token",
	CredID:        "cred_id",
	PrivateKeyPEM: "-----BEGIN EC PRIVATE KEY-----\n...",
	WalletID:      "wallet_id",
})

Openfort

import "github.com/solana-foundation/solana-keychain/go/signers/openfort/v2"

signer, err := openfort.New(ctx, openfort.Config{
	SecretKey:    "sk_live_...",
	AccountID:    "acc_...",
	WalletSecret: "wallet_secret", // base64 PKCS#8 DER or PEM
})

Para

import "github.com/solana-foundation/solana-keychain/go/signers/para/v2"

signer, err := para.New(ctx, para.Config{
	APIKey:   "sk_...",
	WalletID: "wallet_id",
})

Utila

Utila yalnızca işlemleri imzalar; SignMessage başarısız olur ve imzalı işlemi kendiniz yayınlarsınız.

import "github.com/solana-foundation/solana-keychain/go/signers/utila/v2"

signer, err := utila.New(ctx, utila.Config{
	ServiceAccountEmail:         "sa@example.com",
	ServiceAccountPrivateKeyPEM: "-----BEGIN PRIVATE KEY-----\n...",
	VaultID:                     "vault_id",
	WalletID:                    "wallet_id",
	Network:                     "networks/solana-devnet",
})

Fordefi

Fordefi, Config.Chain ve Config.PushMode ile oluşturma sırasında belirlenen üç imzalayıcı türüyle gelir. Üçü de mesaj imzalar:

Config	Tür	Giriş noktası
`Chain` ayarlanmamış	`*fordefi.BlackBoxSigner`	`SignTransaction`
`Chain` ayarlı, `PushMode` ayarlanmamış veya `PushModeAuto`	`*fordefi.NativeAutoSigner`	`SignAndSendTransaction`
`Chain` ayarlı, `PushMode: PushModeManual`	`*fordefi.NativeManualSigner`	`ModifyAndSignTransaction`

fordefi.New yapılandırmaya göre yönlendirme yapar ve bir core.SolanaSigner döndürür; fordefi.NewBlackBox, fordefi.NewNativeAuto ve fordefi.NewNativeManual somut türü döndürür ve diğer modların yapılandırmalarını reddeder. API istekleri ECDSA P-256 istek imzasıyla doğrulanır: PrivateKeyPEM seçeneğinden tam olarak birini sağlayın ya da anahtarı bir KMS/HSM içinde tutmak için bir RequestSigner kullanın.

Native auto modu: Fordefi blockhash'i ve ücretleri değiştirebilir, ardından imzalar ve yayınlar. Yalnızca tek gerekli imzalayanı kasa (vault) olan, imzasız bir işlemi kabul eder.

import "github.com/solana-foundation/solana-keychain/go/signers/fordefi/v2"

signer, err := fordefi.NewNativeAuto(ctx, fordefi.Config{
	AccessToken:   os.Getenv("FORDEFI_ACCESS_TOKEN"),
	VaultID:       os.Getenv("FORDEFI_VAULT_ID"),
	PublicKey:     os.Getenv("FORDEFI_PUBLIC_KEY"), // Solana vault address (base58)
	PrivateKeyPEM: string(pemBytes),
	Chain:         fordefi.ChainSolanaDevnet, // or fordefi.ChainSolanaMainnet
	Fee: &fordefi.Fee{
		Type:          fordefi.FeeTypePriority,
		PriorityLevel: fordefi.PriorityMedium,
	},
})

sig, err := signer.SignAndSendTransaction(ctx, tx)

Native manual modu: PushMode: fordefi.PushModeManual ayarını yapın. Fordefi mesajı yeniden yazar (güncel blockhash, Compute Budget ücret talimatları) ve yayınlamadan imzalar. ModifyAndSignTransaction, tx değerini Fordefi'nin imzaladığı işlemle değiştirir: her zaman bu işlemle devam edin. Yeniden yazma mevcut imzaları geçersiz kıldığı için Fordefi ücret ödeyen (fee payer) olmalı ve diğer tüm gerekli imzalayanlardan önce imzalamalıdır. Yeniden yazma için fark (diff) çıkarılmaz; bu yüzden yayınlamadan önce sonucu inceleyin.

signer, err := fordefi.NewNativeManual(ctx, fordefi.Config{
	AccessToken:   os.Getenv("FORDEFI_ACCESS_TOKEN"),
	VaultID:       os.Getenv("FORDEFI_VAULT_ID"),
	PublicKey:     os.Getenv("FORDEFI_PUBLIC_KEY"),
	PrivateKeyPEM: string(pemBytes),
	Chain:         fordefi.ChainSolanaDevnet,
	PushMode:      fordefi.PushModeManual,
})

signed, err := signer.ModifyAndSignTransaction(ctx, tx)

Black box modu: Chain ayarını boş bırakın. Fordefi, mesaj baytlarınızı olduğu gibi imzalar ve yayınlamaz. Bunu bir Fordefi black box kasasıyla kullanın.

signer, err := fordefi.NewBlackBox(ctx, fordefi.Config{
	AccessToken:   os.Getenv("FORDEFI_ACCESS_TOKEN"),
	VaultID:       os.Getenv("FORDEFI_BB_VAULT_ID"),
	PublicKey:     os.Getenv("FORDEFI_BB_PUBLIC_KEY"),
	PrivateKeyPEM: string(pemBytes),
})

Neden Üst Düzey (Umbrella) Paket Yok

Rust'ta bir Signer enum'u, TypeScript'te createKeychainSigner vardır; Go'da bilerek ikisi de yoktur. Go, çalışma zamanı yönlendirme switch'i boyunca ölü kodu ayıklamaz; bu yüzden bir umbrella paket, her arka ucun satıcı SDK'sını (AWS, GCP ve diğerleri) her tüketicinin derlemesine dahil etmeye zorlar. İhtiyacınız olan arka uç paketini içe aktarmak seçicinin kendisidir. Çalışma zamanında bir arka uç seçmek için, switch'i yalnızca desteklediğiniz arka uçlar üzerinden kendi kodunuzda yazın ve sonucu bir core.SolanaSigner olarak tutun.

Hata Yönetimi

Her hata, sabit bir Code değerine (CodeConfigError, CodeHTTPError, CodeRemoteAPIError, CodeSigningFailed, CodeNotInitialized, CodeBroadcastUnconfirmed ve diğerleri) sahip bir *core.SignerError türündedir. Error(), her kod için yalnızca sabit bir mesaj döndürür; anahtar materyalini veya ham sağlayıcı yanıtlarını asla döndürmez. errors.As, errors.Is(err, &core.SignerError{Code: ...}) ya da core.CodeOf(err) ile eşleştirin.

Crossmint ve Fordefi native auto modunda, bir hata hiçbir şeyin zincire ulaşmadığı anlamına gelmez. Sağlayıcı işlemi kabul etmiş olabilirse kod core.CodeBroadcastUnconfirmed ("SIGNER_BROADCAST_UNCONFIRMED") olur. Oluşturma isteği kabul edildiğinde ProviderTxID ayarlanır ve IdempotencyKey, mesajdan türetilen anahtarı taşır. Bayt düzeyinde aynı işlemi yeniden göndermek güvenlidir; yeniden oluşturulmuş bir işlem (örneğin yeni bir blockhash ile) yeni bir transferdir. core.SignAndSendTransaction, gönderme fonksiyonunuz başarısız olduğunda da bu kodu bildirir; ücret ödeyenin imzası TransactionSignature içinde yer alır. Fireblocks PROGRAM_CALL yalnızca imzalama yapar ve anahtar göndermez; bu kodu yalnızca bir yoklama (poll) Fireblocks'un yine de yayın yaptığını gösterdiğinde bildirir.

sig, err := core.SignAndSendTransaction(ctx, signer, tx, send)
var se *core.SignerError
if errors.As(err, &se) && se.Code == core.CodeBroadcastUnconfirmed {
	// Reconcile se.ProviderTxID, se.IdempotencyKey or se.TransactionSignature
	// with the provider before retrying.
}

Her imzalama yapısının neyi garanti ettiği için güvenlik modeline, tam modül listesi için Go README dosyasına ve API başvurusu için pkg.go.dev sayfasına bakın.

Özel İmzalayıcı Ekleme

core.SolanaSigner arayüzünü ve tam olarak bir yetenek arayüzünü uygulayın; arka ucunuzun yerine getiremeyeceği hiçbir metot eklemeyin: çağıranlar yeteneği tür doğrulamasıyla (type assertion) tespit eder. Ek anahtar yönetimi hizmetlerini entegre etmek için İmzalayıcı Ekleme kılavuzuna bakın.

İçindekiler