Go

2.0.0 on Go-moduulien ensimmäinen vakaa julkaisu, joten migroitavaa ei ole. 2.0-migraatio-opas käsittelee saman ominaisuusjaon Rustille ja TypeScriptille.

Asennus

Jokainen taustajärjestelmä on oma Go-moduulinsa, joten koontiversiosi ja moduulikaaviosi sisältävät vain ne taustajärjestelmät, jotka tuot:

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

Moduulit tagataan muodossa go/<module>/v2.0.0 (esimerkiksi go/signers/memory/v2.0.0). Jokainen moduuli vaatii Go 1.25.0:n, paitsi gcpkms, joka vaatii Go 1.25.8:n google.golang.org/api:n asettaman alarajan vuoksi. Ledger on vain Rustille eikä sillä ole Go-moduulia.

solana-go v2 ja v1-transaktiot

Moduulit perustuvat pakettiin github.com/solana-foundation/solana-go/v2 v2.0.0 ja käyttävät sen *solana.Transaction-tyyppiä. Legacy-, v0- ja v1-transaktiot (solana.MessageVersionV1) ovat tuettuja, paitsi Fireblocksissa asetuksella UseProgramCall: true, joka hyväksyy vain legacy- ja v0-transaktiot.

Peruskäyttö

Jokainen allekirjoittaja toteuttaa perustason core.SolanaSigner-rajapinnan (Pubkey, SignMessage, IsAvailable). Metodit ottavat parametrinaan context.Context-arvon ja ovat estäviä. Lisäksi jokainen taustajärjestelmä toteuttaa täsmälleen yhden ominaisuusrajapinnan:

• core.TransactionSigner: SignTransaction allekirjoittaa transaktiosi sellaisenaan.
• core.ModifyingSigner: ModifyAndSignTransaction antaa palveluntarjoajan kirjoittaa transaktion uudelleen ja allekirjoittaa sen sitten.
• core.SendingSigner: SignAndSendTransaction antaa palveluntarjoajan allekirjoittaa ja lähettää sen verkkoon.

Jokainen taustajärjestelmäpaketti tarjoaa Config-structin ja New-konstruktorin:

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 ja ModifyAndSignTransaction palauttavat core.SignedTransaction-arvon (EncodedTransaction, Signature, Completeness). HTTP-pohjaiset etätaustajärjestelmät hyväksyvät valinnaiset HTTPClient- ja HTTPClientConfig-asetukset (aikakatkaisut). Oletusasiakas pakottaa HTTPS:n käytön; oman asiakkaan antaminen ohittaa sen, ja vastaat itse sen tietoturvatasosta.

Allekirjoittajan ominaisuudet

Taustajärjestelmällä, joka ei voi allekirjoittaa transaktiota, ei ole lainkaan SignTransaction-metodia, joten ominaisuus on konkreettisille tyypeille käännösaikainen tosiasia ja core.SolanaSigner-arvolle tyyppivarmistus (type assertion):

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)
}

Alustus

Erillistä Init-vaihetta ei ole. Privy, Fireblocks, Dfns, Crossmint, Para, Openfort ja Utila selvittävät lompakon osoitteen New-kutsun sisällä, minkä vuoksi niiden konstruktorit ottavat parametrinaan context.Context-arvon. Luo allekirjoittajat aina New-kutsulla: alustamaton Crossmint-, Para- tai Utila-allekirjoittaja epäonnistuu virheeseen CodeNotInitialized sen sijaan, että allekirjoittaisi nolla-osoitteelle.

Allekirjoita ja lähetä millä tahansa allekirjoittajalla

core.SignAndSendTransaction vie transaktion ketjuun allekirjoittajan muodosta riippumatta. SendingSigner lähettää palveluntarjoajansa kautta ja ohittaa lähetys- funktion; kaikki muut muodot allekirjoittavat, ja oma funktiosi lähettää base64- tuloksen, joka ModifyingSigner-tapauksessa on palveluntarjoajan uudelleenkirjoittama transaktio. Core ei riipu RPC:stä:

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)
	})

Erä-allekirjoitus

Erä-allekirjoitus tarjotaan erillisinä apufunktioina, jotka toimivat rinnakkain ja joissa on valinnainen pyyntökohtainen porrastus nopeusrajoitetuille rajapinnoille:

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 ottaa parametrinaan core.TransactionSigner-arvon, joten lähetyksen hallitsevia allekirjoittajia (Crossmint, Fordefi native auto) ja Fordefi native manualia ei voi käsitellä erinä sen kautta; kutsu niitä yksi transaktio kerrallaan. Allekirjoittaja, jonka kutsut luovat palveluntarjoajan puolella työtä (Fireblocks asetuksella UseProgramCall), ilmoittaa tämän core.BatchServerSideEffects-rajapinnan kautta, ja erä suoritetaan silloin järjestyksessä.

Taustajärjestelmän asetukset

Memory

Anna täsmälleen yksi seuraavista: PrivateKey (raakatavut), PrivateKeyString (base58 tai [1,2,...]-tavutaulukko) tai PrivateKeyPath (Solana CLI:n keypair-tiedosto):

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

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

Go ei tarjoa luotettavaa tapaa nollata muistia: roskienkerääjä voi kopioida ja pitää avaintavuja muistissa kunnes keruu tapahtuu (memory-keypairit sekä avaimet, jotka Crossmint ja Openfort johtavat paikallisesti). Kohtele koko prosessin muistia arkaluonteisena, kun käytät paikallisen avaimen taustajärjestelmiä.

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:n SignMessage hyväksyy vain UTF-8-sisältöjä.

Crossmint

Crossmint on vain lähettävä: sen rajapinta suorittaa jokaisen hyväksytyn transaktion palvelinpuolella, joten *crossmint.Signerssa on SignAndSendTransaction mutta ei SignTransaction-metodia. Transaktiotasi ei koskaan muokata; palautettu allekirjoitus tunnistaa transaktion, jonka Crossmint sai ketjuun, ja se voi poiketa omastasi, jos Crossmint sponsoroi kaasumaksut.

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 vain allekirjoittaa transaktioita; SignMessage epäonnistuu, ja allekirjoitetun transaktion lähetät itse.

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 on saatavilla kolmena allekirjoittajatyyppinä, jotka määräytyvät luonnin yhteydessä asetuksilla Config.Chain ja Config.PushMode. Kaikki kolme allekirjoittavat viestejä:

fordefi.New ohjaa asetusten perusteella ja palauttaa core.SolanaSigner-arvon; fordefi.NewBlackBox, fordefi.NewNativeAuto ja fordefi.NewNativeManual palauttavat konkreettisen tyypin ja hylkäävät muiden tilojen asetukset. API-pyynnöt todennetaan ECDSA P-256 -pyyntöallekirjoituksella: anna täsmälleen yksi seuraavista: PrivateKeyPEM tai RequestSigner, jos haluat pitää avaimen KMS:ssä tai HSM:ssä.

Native auto -tila: Fordefi voi vaihtaa blockhashin ja maksut, minkä jälkeen se allekirjoittaa ja lähettää. Se hyväksyy vain allekirjoittamattoman transaktion, jonka ainoa vaadittu allekirjoittaja on vault.

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 -tila: aseta PushMode: fordefi.PushModeManual. Fordefi kirjoittaa viestin uudelleen (tuore blockhash, Compute Budget -maksuohjeet) ja allekirjoittaa sen lähettämättä sitä. ModifyAndSignTransaction korvaa tx:n transaktiolla, jonka Fordefi allekirjoitti: jatka aina siitä. Fordefin on oltava maksun maksaja ja sen on allekirjoitettava ennen muita vaadittuja allekirjoittajia, koska uudelleenkirjoitus mitätöi olemassa olevat allekirjoitukset. Uudelleenkirjoituksesta ei muodosteta diffiä, joten tarkista tulos ennen lähettämistä.

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 -tila: jätä Chain asettamatta. Fordefi allekirjoittaa viestisi tavut täsmälleen sellaisenaan eikä lähetä niitä. Käytä tätä Fordefi black box -vaultin kanssa.

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),
})

Miksi kattopakettia ei ole

Rustissa on Signer-enum ja TypeScriptissä createKeychainSigner; Gossa ei syystä ole kumpaakaan. Go ei poista kuollutta koodia ajonaikaisen haarautuskytkimen yli, joten kattopaketti pakottaisi jokaisen taustajärjestelmän toimittajan SDK:n (AWS, GCP ja muut) jokaisen käyttäjän koontiversioon. Tarvitsemasi taustajärjestelmäpaketin tuominen on valitsin. Jos haluat valita taustajärjestelmän ajon aikana, kirjoita switch omaan koodiisi vain tukemiesi taustajärjestelmien osalta ja säilytä tulos core.SolanaSigner-arvona.

Virheidenkäsittely

Jokainen virhe on *core.SignerError, jolla on vakaa Code (CodeConfigError, CodeHTTPError, CodeRemoteAPIError, CodeSigningFailed, CodeNotInitialized, CodeBroadcastUnconfirmed ja muut). Error() palauttaa vain kiinteän viestin koodia kohden, ei koskaan avainmateriaalia tai palveluntarjoajan raakavastauksia. Täsmäytä käyttämällä errors.As, errors.Is(err, &core.SignerError{Code: ...}) tai core.CodeOf(err).

Crossmintissa ja Fordefin native auto -tilassa virhe ei tarkoita, ettei mikään päätynyt ketjuun. Kun palveluntarjoaja on voinut hyväksyä transaktion, koodi on core.CodeBroadcastUnconfirmed ("SIGNER_BROADCAST_UNCONFIRMED"). ProviderTxID asetetaan, kun luonti hyväksyttiin, ja IdempotencyKey sisältää viestistä johdetun avaimen. Tavu tavulta identtisen transaktion uudelleenlähetys on turvallista; uudelleenrakennettu (esimerkiksi uudella blockhashilla) on uusi siirto. core.SignAndSendTransaction ilmoittaa tämän koodin myös silloin, kun lähetysfunktiosi epäonnistuu, ja maksun maksajan allekirjoitus on kentässä TransactionSignature. Fireblocksin PROGRAM_CALL on vain allekirjoittava eikä lähetä avainta; se ilmoittaa tämän koodin vain, kun kysely osoittaa Fireblocksin lähettäneen transaktion silti.

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.
}

Katso tietoturvamalli saadaksesi tietää, mitä kukin allekirjoitustapa takaa, Go READMEstä koko moduululuettelo ja pkg.go.devistä API-viite.

Mukautettujen allekirjoittajien lisääminen

Toteuta core.SolanaSigner sekä täsmälleen yksi ominaisuusrajapinta äläkä lisää metodia, jota taustajärjestelmäsi ei voi tukea: kutsujat tunnistavat ominaisuuden tyyppivarmistuksella. Katso Allekirjoittajien lisäämisen opas, jos haluat integroida lisää avainhallintapalveluita.