Best practice per la produzione

Keychain astrae il backend di firma, ma la gestione di un firmatario in produzione è ancora una tua responsabilità. Queste pratiche si applicano a tutti i backend; consulta Scelta di un backend per la selezione.

Separare i firmatari hot e cold

Utilizza un firmatario operativo a basso saldo ("hot") per transazioni frequenti e automatizzate, e un firmatario separato ad alto valore ("cold") per i movimenti del treasury. Supporta il firmatario cold con la custodia MPC o un HSM cloud e richiedi policy di approvazione prima della firma. Poiché l'interfaccia è identica, ogni ruolo può utilizzare un backend diverso senza modificare i call site.

Ruotare le chiavi in modo deliberato

Su Solana la chiave di firma è l'indirizzo dell'account, quindi ruotare una chiave produce un nuovo indirizzo. Pianifica la rotazione come una migrazione: fornisci una nuova chiave, riassegna le autorità pertinenti (o sposta i fondi) al nuovo indirizzo, poi dismetti quella vecchia. Usa chiavi distinte per ogni ambiente, in modo che le chiavi devnet non vengano mai riutilizzate su mainnet.

Concedere l'accesso con privilegi minimi

Limita le credenziali di ciascun backend al minimo necessario per firmare. Per AWS KMS, sono kms:Sign, kms:DescribeKey e kms:GetPublicKey sulla chiave specifica (il controllo di disponibilità usa le ultime due); preferisci i ruoli IAM alle credenziali statiche. Applica lo stesso principio alle policy di Vault e alle chiavi API dei wallet gestiti.

Pianificare la disponibilità

I backend remoti dipendono da un servizio di rete. Verifica la disponibilità prima di affidarti a un firmatario (isAvailable() in TypeScript, is_available() in Rust e Python, IsAvailable(ctx) in Go), riprova con backoff in caso di errori di sola firma e definisci un percorso di fallback per le interruzioni. Non riprovare alla cieca con un backend che trasmette (Crossmint, modalità auto nativa di Fordefi): consulta Gestire le trasmissioni non confermate. Keychain impone HTTPS sugli URL di base configurati, rifiuta i reindirizzamenti e applica un timeout predefinito alle richieste.

Gestire le trasmissioni non confermate

Crossmint e la modalità auto nativa di Fordefi firmano e trasmettono lato server, quindi una chiamata fallita non significa che nulla sia stato inviato. Quando il provider potrebbe aver accettato la transazione, Keychain segnala BROADCAST_UNCONFIRMED (SignerError::BroadcastUnconfirmed in Rust). L'errore include l'ID della transazione del provider quando la creazione è stata accettata e include sempre la chiave di idempotenza con cui è stata inviata la creazione, derivata dal messaggio.

• Riconcilia con il provider usando l'ID della transazione prima di fare qualsiasi altra cosa.
• Reinviare la transazione identica byte per byte è sicuro: la chiave di idempotenza la deduplica.
• Ricostruire la transazione (ad esempio con un nuovo blockhash) produce una nuova chiave e quindi un nuovo trasferimento.

Proteggere i segreti e il trasporto

• I backend remoti impongono HTTPS sugli URL di base configurati e rifiutano i reindirizzamenti. L'unica eccezione è Vault, che accetta HTTP semplice su loopback, così che un vault server -dev locale funzioni.
• Fornisci chiavi API, token e credenziali da un gestore di segreti o da variabili d'ambiente — non codificarli mai nel codice sorgente né eseguirne il commit nel controllo del codice sorgente.
• Keychain sanifica le risposte di errore per evitare che i segreti vengano esposti nei log; mantieni il tuo logging privo di credenziali grezze e materiale relativo alle chiavi.

Monitorare e controllare le firme

Monitora il tasso di successo delle firme, la latenza e il numero di errori, e configura avvisi per i picchi — consulta le metriche in Production Readiness. Abilita i log di audit lato provider (KMS, Vault o custodian) e riconciliali con le transazioni inviate dalla tua applicazione.

Sapere cosa verifica Keychain

• Keychain convalida il passaggio di firma, non la tua transazione: non c'è simulazione, né controllo del contenuto della transazione, né motore di policy. Applica questi controlli nella tua applicazione o nei controlli delle policy del provider.
• La modalità manuale nativa di Fordefi riscrive la transazione (blockhash, istruzioni di fee del Compute Budget) prima di firmarla. Prosegui dalla transazione che restituisce, mai da quella che hai inviato, ed eseguila prima di qualsiasi altro firmatario.
• Rust azzera i buffer intermedi delle chiavi (zeroize); Python e Go no. Con il backend Memory in questi linguaggi, considera sensibile l'intera memoria del processo.
• Con Ledger, lo schermo del dispositivo è l'unica descrizione affidabile di ciò che si sta firmando. Non abilitare la feature unsafe-debug né il logging TRACE per solana_remote_wallet in produzione, poiché entrambi registrano nei log i dettagli del dispositivo e della transazione.

Consulta il modello di sicurezza per il quadro completo.