Keychain

O Solana Keychain fornece uma interface unificada para assinar transações Solana em múltiplos backends de gerenciamento de chaves. Desenvolva localmente com uma chave em memória, depois mude para gerenciamento de chaves empresarial, HSMs em nuvem ou serviços de carteira gerenciada em produção, sem reescrever seu código de assinatura.

Por que Keychain?

• Interface Única: Uma interface base SolanaSigner em todos os backends, mais uma capacidade por backend: assinar, reescrever e assinar, ou assinar e transmitir
• Troque de Backend: Mude os provedores de gerenciamento de chaves por configuração; os pontos de chamada só mudam quando o novo backend tem uma capacidade diferente (modos nativos da Crossmint e da Fordefi)
• Pague pelo que usa: Feature flags do Rust, pacotes npm por backend, extras do Python e módulos Go por backend incluem apenas os backends de que você precisa
• Auditado: Rust, TypeScript, Python e Go auditados pela OtterSec (o backend Ledger opcional ficou fora do escopo); uma auditoria anterior da Accretion cobriu Rust e TypeScript. Veja o status da auditoria.

Arquitetura

• Linguagens: Rust, TypeScript, Python e Go, com paridade (o backend Ledger é exclusivo do Rust)
• Interface: base SolanaSigner (pubkey, sign_message, is_available) mais exatamente uma capacidade por backend: TransactionSigner, ModifyingSigner ou SendingSigner
• Backends: Memory, Vault, AWS KMS, GCP KMS, Privy, Turnkey, Fireblocks, CDP, Crossmint, Dfns, Openfort, Para, Utila, Fordefi, Ledger (somente Rust, opcional, não auditado)
• Compatibilidade: @solana/kit e @solana/signers 8.1+ (TypeScript) | solana-sdk 2.x, 3.x ou 4.x por meio dos recursos sdk-v2 / sdk-v3 / sdk-v4 (Rust; transações v1 exigem sdk-v4) | solders (Python) | solana-go v2 (Go)

Backends Suportados

Os backends abrangem desenvolvimento local, gerenciamento de chaves auto-hospedado e em nuvem, e serviços de carteira gerenciada ou MPC. Consulte Como escolher um backend para comparar os modelos de custódia e escolher o mais adequado.

Início Rápido

Rust

Instale o crate Rust:

cargo add solana-keychain

Uso básico:

use solana_keychain::{Signer, SolanaSigner};

// Create a signer from any backend
let signer = Signer::from_memory("base58_private_key")?;
let pubkey = signer.pubkey();

// Transaction signing is a capability; `tx` is a VersionedTransaction
if let Some(tx_signer) = signer.as_transaction_signer() {
    let result = tx_signer.sign_transaction(&mut tx).await?;
}

// Or let the umbrella route any backend shape and supply the RPC hop yourself
let signature = signer
    .sign_and_send(&mut tx, |encoded| async move { broadcast(encoded).await })
    .await?;

• Guia Rust - Instalação completa e configuração de backend
• Crates.io - Crate Rust

TypeScript

Instale o pacote TypeScript:

pnpm add @solana/keychain

Uso básico:

import { createKeychainSigner } from "@solana/keychain";
import { signTransactionWithSigners } from "@solana/signers";

// Create any signer via the unified factory
const signer = await createKeychainSigner({
  backend: "vault",
  vaultAddr: "https://vault.example.com:8200",
  vaultToken: "hvs.xxxxx",
  keyName: "my-solana-key",
  publicKey: "base58_public_key"
});

// Sign an already-compiled transaction
const signedTx = await signTransactionWithSigners(
  [signer],
  compiledTransaction
);

• Guia TypeScript - Pacotes @solana/keychain
• Pacote npm - Pacote npm

Para instalar um signer do Keychain em um cliente Kit como payer ou identity, use @solana/keychain-kit-plugin (os modos nativos da Crossmint e da Fordefi são excluídos, pois reescrevem transações).

Python

Instale o pacote (os backends mais pesados são distribuídos como extras, por exemplo solana-keychain[aws-kms]):

pip install solana-keychain

Uso básico:

import os

from solana_keychain import VaultSignerConfig, create_vault_signer

signer = await create_vault_signer(
    VaultSignerConfig(
        api_base_url="https://vault.example.com:8200",
        token=os.environ["VAULT_TOKEN"],
        key_name="my-solana-key",
        public_key="base58_public_key",
    )
)

# tx is a solders VersionedTransaction
result = await signer.sign_transaction(tx)

• Guia Python - Instalação completa, extras e configuração de backend
• PyPI - Pacote Python

Go

Cada backend é seu próprio módulo Go, então você baixa apenas os backends que importar:

go get github.com/solana-foundation/solana-keychain/go/signers/vault/v2@latest

Uso básico:

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

signer, err := vault.New(vault.Config{
	VaultAddr: "https://vault.example.com:8200",
	Token:     os.Getenv("VAULT_TOKEN"),
	KeyName:   "my-solana-key",
	Pubkey:    "base58_public_key",
})
if err != nil {
	return err
}

// tx is a *solana.Transaction from solana-go v2
res, err := signer.SignTransaction(ctx, tx)

• Guia Go - Módulos, capacidades e configuração de backend
• pkg.go.dev - Referência Go

Próximos passos

Fonte

• Repositório GitHub
• Histórico de versões
• Modelo de segurança
• Migração para a 2.0

Desenvolvido e mantido pela Solana Foundation. Licenciado sob MIT.