btcDeriveContextHash

Dérivez sur l’appareil un hachage de contexte Babylon de 32 octets pour la clé Bitcoin, l’application, le contexte et le réseau sélectionnés. La réponse contient un secret sensible destiné à votre application.

Disponible dans le SDK 1.2.8-alpha.6. Nécessite Classic 1s ou Classic 1s Pure avec un micrologiciel 3.21.0 ou ultérieur et Protocol V1. Les autres familles d’appareils et Protocol V2 ne sont pas pris en charge.


const result = await HardwareSDK.btcDeriveContextHash(connectId, deviceId, params);

01 Préparer le contexte02 Confirmer sur l’appareil03 Utiliser le secret

Avant l’appel

Initialisez le SDK et sélectionnez un appareil.
Enregistrez les gestionnaires d’événements d’interface et sélectionnez explicitement la session de portefeuille souhaitée.
Avant l’appel, obtenez l’accord de l’utilisateur pour l’application demandeuse et son origine. appName est fourni par l’appelant ; votre application doit déterminer quel site ou quelle application demande l’accès.

Paramètres

connectIdstringobligatoire

L’identifiant de connexion renvoyé par la découverte d’appareils.

deviceIdstringobligatoire

L’identité du portefeuille renvoyée par getDeviceState ou openWalletSession.

params.pathstring | number[]obligatoire

Chemin BIP32 de la clé Bitcoin connectée, avec au moins 3 composants. Le type de script est déduit du chemin. Utilisez le chemin de la clé connectée, pas le chemin interne de dérivation IKM.

params.appNamestringobligatoire

1–64 caractères ASCII correspondant à [a-z0-9-].

params.contextstringobligatoire

Chaîne hexadécimale en minuscules, de longueur paire et sans préfixe 0x, représentant 1–1024 octets. Un contexte vide est invalide. Le SDK envoie les octets décodés à l’appareil.

params.networkstringobligatoire

Exactement bitcoin-mainnet, bitcoin-testnet, bitcoin-signet ou bitcoin-regtest. Testnet3 et testnet4 utilisent tous deux bitcoin-testnet. Le réseau n’est pas déduit du chemin.

Paramètres communs facultatifs

Exemple

Ce fragment suppose que le SDK est initialisé et qu’un portefeuille standard est sélectionné. Remplacez les valeurs d’exemple path, appName, context et network par celles approuvées par l’utilisateur. Le contexte ci-dessous est un exemple de données encodées en hexadécimal.


const result = await HardwareSDK.btcDeriveContextHash(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  appName: 'babylon-example',
  context: '48656c6c6f',
  network: 'bitcoin-mainnet',
  useEmptyPassphrase: true,
});
 
if (result.success === false) throw new Error(result.payload.error);
const secret = result.payload.secret;
// Use only for the approved application and context. Do not log or persist it.

L’exemple sélectionne explicitement le portefeuille standard avec useEmptyPassphrase: true. Pour un portefeuille caché, transmettez le même passphraseState que lors de la confirmation du compte Bitcoin connecté. Le parcours habituel de PIN, de passphrase et de confirmation sur l’appareil reste applicable.

Réponse

Vérifiez success avant de lire le contenu de la réponse. En cas de succès, payload.secret est une chaîne hexadécimale en minuscules de 64 caractères (32 octets). Les onglets ci-dessous montrent les types de réponse, pas de véritables valeurs secrètes.

Succès


type SuccessResponse = {
  success: true;
  payload: {
    secret: string; // 64 lowercase hexadecimal characters (32 bytes)
  };
};

Gestion des erreurs et du secret

Une valeur invalide de path, appName, context ou network renvoie CallMethodInvalidParameter (405) avant l’envoi de la commande de dérivation. Les familles d’appareils non prises en charge ou Protocol V2 renvoient DeviceNotSupportMethod (415) ; un micrologiciel antérieur à 3.21.0 nécessite une mise à jour.

L’annulation sur l’appareil renvoie la réponse standard success: false. Arrêtez la requête et traitez payload.error et payload.code avant de tenter un nouvel appel.

Le SDK renvoie le véritable secret à votre application. Traitez-le comme une donnée sensible : excluez-le des journaux, de la télémétrie, du presse-papiers et du stockage persistant. La dérivation s’exécute sur l’appareil ; la clé interne du portefeuille n’est pas exportée.