9.8 KiB
Compatibilité import/export des wallets Solana
1. Statut
Cette matrice est établie pour khadhroony-bot3 0.5.2-pre.005 et borne les adaptateurs secrets de ks-wallet.
Elle ne prétend pas inventorier tous les wallets existants. Elle couvre les formats obligatoires du projet et les cibles explicitement retenues par le plan 0.5.2 : Solana CLI, Phantom, Solflare, Backpack, Trust Wallet et Base / Coinbase Wallet. Coinbase Developer Platform est distingué de Base app car son API de custody/import n'est pas le contrat utilisateur de Base app.
Règles transversales :
- tout export contenant le secret exige d'abord le mot de passe valide du
.kswallet; - aucun adaptateur ne synthétise une recovery phrase à partir d'une keypair arbitraire ;
- un format n'est implémenté que si sa représentation est suffisamment précise pour permettre un round-trip et une validation de pubkey ;
- les exports secrets sont écrits dans un fichier privé, atomiquement et sans écrasement silencieux ;
- les sources d'import sont lues comme fichiers secrets privés et ne sont jamais loguées.
Sources vérifiées le 2026-08-10.
2. Formats implémentés dans 0.5.2-pre.005
Format ks-wallet |
Représentation | Import | Export | Cible de référence |
|---|---|---|---|---|
SolanaCliJson |
tableau JSON contenant exactement 64 octets | oui | oui | Solana CLI / solana-keygen |
SolanaPrivateKeyBase58 |
Base58 du keypair Solana complet de 64 octets | oui | oui | Phantom ; compatibilité Solflare documentée |
SolanaPrivateKeyBase58 est volontairement un nom de format générique et non PhantomPrivateKey : le wire représente la keypair Solana, pas un conteneur propriétaire Phantom. Phantom sert de cible de référence parce que la documentation Solana identifie explicitement la private key copiée depuis Phantom comme Base58, et Phantom documente l'import d'une private key Solana. La référence officielle @solana/web3.js impose par ailleurs 64 octets à Keypair.fromSecretKey() ; l'adaptateur ks-wallet encode donc exactement son keypair Solana complet de 64 octets en Base58 et refuse une seed brute de 32 octets.
Solflare documente de son côté le transfert d'une private key affichée par Phantom vers son propre écran Import private key. Cette compatibilité permet d'utiliser le même export Base58 sans créer un second codec de marque identique.
La version pre.005 accepte uniquement la forme Base58 du keypair complet de 64 octets. Elle n'accepte pas une seed brute de 32 octets et ne dérive aucune keypair depuis une mnemonic.
3. Matrice des cibles étudiées
| Cible | Surface officielle observée | Encodage exploitable depuis une keypair arbitraire | Décision 0.5.2-pre.005 |
|---|---|---|---|
Solana CLI / solana-keygen |
fichier keypair JSON, tableau d'octets | oui, 64 octets | implémenté import + export |
| Phantom | import/export d'une private key Solana | oui, Base58 selon documentation Solana | implémenté via SolanaPrivateKeyBase58 |
| Solflare | import d'une private key copiée depuis Phantom ; export de private key | oui par compatibilité documentée avec Phantom | même wire Base58 ; pas de codec de marque séparé |
| Solflare Keystore | import d'un fichier keystore protégé | format exact non suffisamment spécifié ici | TODO version ultérieure non déterminée |
| Backpack | import avancé par private key ou recovery phrase | représentation Solana exacte non spécifiée | TODO version ultérieure non déterminée |
| Trust Wallet | export de private keys ; restauration pouvant utiliser des private keys | représentation Solana exacte non spécifiée | TODO version ultérieure non déterminée |
| Base app / ex-Coinbase Wallet | restauration et backup principalement documentés par recovery phrase | pas de contrat arbitraire keypair -> même wallet | aucune mnemonic synthétique ; pas d'adaptateur |
| Coinbase Developer Platform | import Solana Base58 ou tableau brut 32 octets ; export API | oui, mais API de plateforme distincte de Base app | information de compatibilité ; pas un adaptateur wallet 0.5.2 |
4. Sources officielles
Solana CLI JSON
La documentation Solana décrit le fichier keypair par défaut ~/.config/solana/id.json comme un JSON array of bytes. Le format legacy déjà caractérisé dans ks-wallet fixe son wire actuel à 64 octets et pre.005 conserve cette représentation en import/export.
- Solana —
Create a Token Account: https://solana.com/docs/tokens/extensions/confidential-transfer/create-token-account - Solana —
Deploying Programs: https://solana.com/docs/programs/deploying
Phantom / Base58
Phantom documente l'import d'une private key pour une adresse unique et l'export de la private key par réseau. Le template officiel Solana ZK Compression Airdrop précise que la private key obtenue par Phantom -> Settings -> Show Private Key est Base58 encoded.
- Phantom —
Sign in to or import an existing Phantom wallet: https://help.phantom.com/hc/en-us/articles/15079894392851-Sign-in-to-or-import-an-existing-Phantom-wallet - Phantom —
View your recovery phrase or private keys in Phantom: https://help.phantom.com/hc/en-us/articles/25334064171795-View-your-recovery-phrase-or-private-keys-in-Phantom - Solana —
ZK Compression Airdrop: https://solana.com/developers/templates/zk-compression-airdrop - Solana Foundation —
@solana/web3.js Keypair: https://solana-foundation.github.io/solana-web3.js/v1.x/classes/Keypair.html
Solflare
Solflare documente l'import d'une private key copiée depuis Phantom, ainsi que l'export de la private key d'un compte. Cette documentation établit la compatibilité du wire de private key entre les deux wallets, sans nécessiter un second format ks-wallet.
- Solflare —
How to Import a Wallet using a Private Key on Solflare: https://help.solflare.com/en/articles/6462529-how-to-import-a-wallet-using-a-private-key-on-solflare-desktop - Solflare —
How to Export Your Private Key on Solflare: https://help.solflare.com/en/articles/6150516-how-to-export-your-private-key-on-solflare-mobile - Solflare —
Importing a Keystore File into Your Solflare Wallet: https://help.solflare.com/en/articles/9351932-importing-a-keystore-file-into-your-solflare-wallet
Backpack
Backpack documente un import avancé par Private key, mais la page consultée ne fixe pas suffisamment l'encodage Solana du secret pour créer un codec testé sans hypothèse supplémentaire.
- Backpack —
Import/Recover Wallet: https://support.backpack.exchange/wallet/get-started/import-recover-wallet
Trust Wallet
Trust Wallet documente l'export de private keys et indique qu'une restauration peut utiliser des private keys stockées séparément. Les sources consultées ne fixent toutefois pas le wire Solana précis attendu par l'import utilisateur.
- Trust Wallet —
How to Backup Your Recovery Phrase and Export Private Keys in Trust Wallet: https://trustwallet.com/blog/product/how-to-backup-your-recovery-phrase-and-export-private-keys-in-trust-wallet - Trust Wallet —
Backing Up and Restoring Your Wallet: Step-by-Step Guide: https://trustwallet.com/blog/security/backing-up-and-restoring-your-wallet-step-by-step-guide
Base app et Coinbase Developer Platform
Base app documente principalement la recovery phrase pour backup/restauration. ks-wallet ne possède pas la mnemonic/seed d'origine d'une keypair arbitraire et ne doit donc pas en fabriquer une.
Coinbase Developer Platform possède un autre contrat : son API Solana accepte une private key Base58, explicitement citée comme pouvant venir de Phantom, ou un tableau brut de 32 octets. Ce contrat est utile pour confirmer l'existence du wire Base58 mais ne doit pas être confondu avec l'interface utilisateur Base app.
- Base / Coinbase Help —
Base wallet recovery phrase: https://help.coinbase.com/wallet/managing-account/wallet-recovery-phrase - Coinbase Developer Platform —
Import & Export: https://docs.cdp.coinbase.com/wallets/using-wallets/import-and-export
5. Report après 0.5.2-pre.005
Les adaptations suivantes sont volontairement reportées vers une version ultérieure non déterminée :
- vérifier et, si pertinent, implémenter le format exact
Private keyde Backpack pour Solana ; - vérifier le wire d'import Solana de Trust Wallet avant tout codec ;
- caractériser le keystore Solflare uniquement si un format stable et suffisamment spécifié est disponible ;
- réévaluer Base app si une future documentation officielle expose un import de keypair arbitraire préservant directement la même pubkey ;
- ajouter d'autres wallets uniquement à partir d'un format privé explicitement documenté et testable.
Ces reports ne bloquent pas 0.5.2 : le format Solana CLI obligatoire et l'adaptateur tiers Base58 de référence sont couverts dans pre.005.