TypeScript

Installation

Installez le package global ou des signataires individuels selon vos besoins :

# Umbrella package (includes all signers)
pnpm add @solana/keychain

# Or install individual packages
pnpm add @solana/keychain-core        # Core interfaces (required for custom signers)
pnpm add @solana/keychain-memory      # Local keypair signer
pnpm add @solana/keychain-vault       # HashiCorp Vault
pnpm add @solana/keychain-aws-kms     # AWS KMS
pnpm add @solana/keychain-gcp-kms     # GCP KMS
pnpm add @solana/keychain-privy       # Privy
pnpm add @solana/keychain-turnkey     # Turnkey
pnpm add @solana/keychain-fireblocks  # Fireblocks
pnpm add @solana/keychain-cdp         # Coinbase Developer Platform
pnpm add @solana/keychain-crossmint   # Crossmint
pnpm add @solana/keychain-dfns        # Dfns
pnpm add @solana/keychain-openfort    # Openfort
pnpm add @solana/keychain-para        # Para
pnpm add @solana/keychain-utila       # Utila

# Kit client plugins (keychainSigner / keychainPayer / keychainIdentity)
pnpm add @solana/keychain-kit-plugin

Utilisation de base

Factory unifiée (Recommandée pour les applications souhaitant prendre en charge plusieurs signataires)

Utilisez createKeychainSigner avec une configuration discriminée pour créer n'importe quel backend :

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

const signer = await createKeychainSigner({
  backend: "privy",
  appId: "your-app-id",
  appSecret: "your-app-secret",
  walletId: "your-wallet-id"
});

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

Ou installez un package de signataire individuel pour réduire l'empreinte des dépendances :

import { createPrivySigner } from "@solana/keychain-privy";

const signer = await createPrivySigner({
  appId: "your-app-id",
  appSecret: "your-app-secret",
  walletId: "your-wallet-id"
});

Utilisation avec les messages de transaction

Tous les signataires implémentent l'interface SolanaSigner, qui est compatible avec @solana/kit et @solana/signers :

import { signTransactionMessageWithSigners } from "@solana/signers";
import {
  createTransactionMessage,
  setTransactionMessageFeePayerSigner,
  pipe
} from "@solana/kit";

async function signWithKeychain(signer: SolanaSigner) {
  // Check availability (useful for remote signers)
  if (!(await signer.isAvailable())) {
    throw new Error("Signer offline");
  }

  // Use with @solana/kit transaction builder
  const transaction = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayerSigner(signer, tx)
    // ... add instructions
  );

  // Sign with the standard signers API
  const signedTx = await signTransactionMessageWithSigners(transaction);
  return signedTx;
}

Utilisation avec un client Kit (plugin keychainSigner)

@solana/keychain-kit-plugin installe un signataire de trousseau directement sur un client Kit, en le configurant comme payer et identity, ce qui vous évite la configuration manuelle de pipe décrite ci-dessus :

import { createClient } from "@solana/kit";
import { keychainSigner } from "@solana/keychain-kit-plugin";

const client = await createClient().use(
  keychainSigner({
    backend: "privy",
    appId: process.env.PRIVY_APP_ID!,
    appSecret: process.env.PRIVY_APP_SECRET!,
    walletId: process.env.PRIVY_WALLET_ID!
  })
);

client.payer; // SolanaSigner — also a Kit TransactionSigner
client.identity; // same signer instance

Le plugin accepte la même configuration avec balise backend que createKeychainSigner, et seul le backend vers lequel il distribue est inclus dans le bundle (les packages backend se chargent via import() dynamique).

Utilisez keychainPayer ou keychainIdentity pour définir un seul rôle, et combinez des backends sur un même client :

import { createClient } from "@solana/kit";
import { keychainIdentity, keychainPayer } from "@solana/keychain-kit-plugin";

const client = await createClient()
  .use(
    keychainPayer({
      backend: "memory",
      privateKeyPath: "~/.config/solana/id.json"
    })
  )
  .use(keychainIdentity({ backend: "turnkey", ...turnkeyConfig }));

Vous avez déjà un SolanaSigner ? Chaque signataire de trousseau est un Kit TransactionSigner valide, vous pouvez donc en installer un existant avec @solana/kit-plugin-signer à la place (pnpm add @solana/kit-plugin-signer) :

import { signer } from "@solana/kit-plugin-signer";
import { createKeychainSigner } from "@solana/keychain";

const mySigner = await createKeychainSigner({
  backend: "vault",
  ...vaultConfig
});
const client = createClient().use(signer(mySigner));

Configuration du backend

HashiCorp Vault

import { createVaultSigner } from "@solana/keychain-vault";

const signer = createVaultSigner({
  vaultAddr: "https://vault.example.com:8200",
  vaultToken: "hvs.xxxxx",
  keyName: "my-solana-key",
  publicKey: "base58_public_key"
});

AWS KMS

import { createAwsKmsSigner } from "@solana/keychain-aws-kms";

const signer = createAwsKmsSigner({
  keyId: "alias/my-solana-key",
  publicKey: "base58_public_key",
  region: "us-east-1" // optional
});

Privy

import { createPrivySigner } from "@solana/keychain-privy";

const signer = await createPrivySigner({
  appId: "app_id",
  appSecret: "app_secret",
  walletId: "wallet_id"
});

Turnkey

import { createTurnkeySigner } from "@solana/keychain-turnkey";

const signer = createTurnkeySigner({
  apiPublicKey: "api_public_key",
  apiPrivateKey: "api_private_key",
  organizationId: "org_id",
  privateKeyId: "private_key_id",
  publicKey: "base58_public_key"
});

Fireblocks

import { createFireblocksSigner } from "@solana/keychain-fireblocks";

const signer = await createFireblocksSigner({
  apiKey: "api_key",
  privateKeyPem: "-----BEGIN RSA PRIVATE KEY-----\n...",
  vaultAccountId: "0",
  assetId: "SOL" // or "SOL_TEST" for devnet
});

CDP (Coinbase Developer Platform)

import { createCdpSigner } from "@solana/keychain-cdp";

const signer = await createCdpSigner({
  apiKeyId: "api_key_id",
  apiKeySecret: "api_key_secret",
  walletSecret: "wallet_secret",
  address: "base58_address"
});

Crossmint

import { createCrossmintSigner } from "@solana/keychain-crossmint";

const signer = await createCrossmintSigner({
  apiKey: "api_key",
  walletLocator: "wallet_locator"
});

Dfns

import { createDfnsSigner } from "@solana/keychain-dfns";

const signer = await createDfnsSigner({
  authToken: "auth_token",
  credId: "cred_id",
  privateKeyPem: "-----BEGIN EC PRIVATE KEY-----\n...",
  appId: "app_id",
  walletId: "wallet_id"
});

Para

import { createParaSigner } from "@solana/keychain-para";

const signer = await createParaSigner({
  apiKey: "api_key",
  walletId: "wallet_id"
});

Interface SolanaSigner

L'interface SolanaSigner étend les types @solana/signers pour une compatibilité complète :

interface SolanaSigner<TAddress extends string = string>
  extends TransactionPartialSigner<TAddress>,
    MessagePartialSigner<TAddress> {
  // Public key address
  readonly address: Address<TAddress>;

  // Health check for remote signers
  isAvailable(): Promise<boolean>;

  // Sign messages (@solana/kit compatible)
  signMessages(
    messages: readonly SignableMessage[]
  ): Promise<readonly SignatureDictionary[]>;

  // Sign transactions (@solana/kit compatible)
  signTransactions(
    transactions: readonly Transaction[]
  ): Promise<readonly SignatureDictionary[]>;
}

Création de signataires personnalisés

Implémentez l'interface SolanaSigner pour créer des signataires personnalisés :

import { SolanaSigner } from "@solana/keychain-core";
import type { Address } from "@solana/addresses";

class MyCustomSigner implements SolanaSigner {
  readonly address: Address;

  constructor(address: Address) {
    this.address = address;
  }

  async isAvailable(): Promise<boolean> {
    return await myBackend.healthCheck();
  }

  async signMessages(messages) {
    return await myBackend.signMessages(messages);
  }

  async signTransactions(transactions) {
    return await myBackend.signTransactions(transactions);
  }
}

Consultez le guide d'ajout de signataires pour intégrer des services de gestion de clés supplémentaires.

Table des matières