Payment hash

Chaque saut d'une route Lightning voit le même payment hash, et c'est ce qui identifie le paiement auprès de chacun d'eux. BOLT 11 en exige exactement un par facture, écrit sous la forme de 52 caractères bech32 portant 256 bits. Présenter le secret correspondant est le seul moyen de réclamer les fonds, et conserver ce secret ensuite constitue votre reçu.

Comment cela fonctionne

Un payment hash commence sa vie comme son contraire : le destinataire choisit 32 octets aléatoires, appelés préimage de paiement, et ne publie que leur SHA-256.

Cette valeur entre dans la facture sous le tag p, que BOLT 11 fixe à un data_length de 52 et exige exactement une fois. De là, elle descend la route à l'intérieur de update_add_htlc, message de type 128, dont les champs sont l'identifiant de canal, un compteur de 64 bits, le montant en millisatoshis, le payment_hash lui-même, une expiration CLTV et un oignon de 1366 octets. Elle remplit un double rôle dans ce message : elle est aussi fournie à la construction de l'oignon comme donnée associée, de sorte que les HMAC à chaque saut s'engagent sur elle. Rejouer un ancien paquet d'oignon contre un payment hash différent échoue donc au premier nœud qui vérifie.

Le règlement fait le chemin inverse. Le destinataire renvoie la préimage dans update_fulfill_htlc, message de type 130, sous forme d'une valeur brute de 32 octets, et chaque nœud en amont la transmet en retour le long des mêmes canaux. Un nœud à qui l'on remet une préimage qui ne donne pas le SHA-256 du hash qu'il détient ne l'ignore pas simplement : BOLT 2 dit qu'il doit soit envoyer un avertissement et fermer la connexion, soit envoyer une erreur et faire échouer le canal, car il n'existe aucune explication innocente.

On-chain, le hash est tronqué. Le script de sortie du HTLC ne contient pas du tout la valeur de 32 octets ; il exécute une comparaison OP_HASH160 avec RIPEMD160(payment_hash), un engagement de 20 octets, et celui qui dépense fournit la préimage dans le witness. Deux HTLC offerts avec le même montant arrondi et le même payment hash produisent des sorties identiques octet pour octet même lorsque leurs expirations diffèrent, ce qui explique pourquoi BOLT 3 doit spécifier une règle d'ordonnancement pour eux.

Une exigence semble étrange jusqu'à ce que l'on voie l'attaque qui la motive. Un nœud doit accepter plusieurs HTLC portant le même payment hash, et BOLT 2 en donne la raison : si les doublons étaient refusés, un attaquant pourrait sonder avec un hash connu et apprendre si ce nœud détenait déjà ce paiement. L'identifiant séparé de 64 bits existe pour distinguer les doublons.

Pourquoi cela compte quand vous achetez du bitcoin

Deux des 63 plateformes d'échange examinées ici documentent un paiement Lightning dans leurs notes sur les frais : Strike, dont la note sur les retraits indique que les retraits vers un portefeuille sont pris en charge sur Lightning et on-chain, et Coinbase, dont le tableau des frais fixe un envoi Lightning à 0,2 % du montant envoyé.

Quand l'un de ces paiements se bloque, il n'y a pas d'identifiant de transaction à rechercher, car rien n'a atteint la blockchain. Le payment hash est la seule chaîne que votre journal de portefeuille et le back-office de la plateforme d'échange détiennent tous les deux, alors copiez-le depuis l'écran de détail du paiement avant de le fermer. Un service d'assistance qui demande « l'identifiant de transaction » d'un retrait Lightning demande cette valeur.

L'erreur que vous recevez ne vous apprendra pas grand-chose, et c'est délibéré. BOLT 4 regroupe cinq problèmes distincts en un seul code d'échec, incorrect_or_unknown_payment_details, numéroté PERM|15 : le hash est inconnu du nœud final, le payment secret ne lui correspond pas, le montant associé à ce hash est trop faible, l'expiration est trop proche de la hauteur de bloc actuelle, ou des métadonnées de paiement requises sont absentes. La spécification explique ce regroupement. Les anciens codes séparés permettaient à un nœud de transfert de deviner où allait un paiement en transmettant le même hash plus loin avec une valeur bien plus faible et en lisant la réponse. Votre portefeuille ne vous cache pas la raison, elle ne lui a jamais été communiquée, alors régénérer la facture et payer à nouveau est la réponse pratique.

La même valeur reste identique de votre nœud à celui du destinataire, y compris sur chaque partie d'un paiement en plusieurs parties, qui doit, selon BOLT 4, partager un seul payment hash. Quiconque la voit deux fois sait qu'il regarde un seul paiement. Notre avis sur Phoenix cite la FAQ d'ACINQ elle-même, qui reconnaît connaître la destination finale et le montant des paiements effectués via le portefeuille, ce qui est la version directe de la même exposition, énoncée par le fournisseur plutôt que déduite par ce site.

Réutiliser une facture est pire qu'inutile pour une raison connexe. BOLT 4 laisse un nœud final à qui l'on remet un hash déjà payé libre soit de le traiter comme inconnu, soit d'accepter les fonds, de sorte que le résultat d'un QR code republié dépend de l'implémentation que le destinataire se trouve utiliser.

Décoder le payment hash dans le vecteur de test de don BOLT 11

La spécification BOLT 11 fournit une facture de don entièrement rédigée, et le payment hash qu'elle contient est une valeur de test fixe qu'aucun portefeuille ne devrait jamais produire.

L'exemple est intitulé "Please make a donation of any amount using payment_hash 0001020304050607080900010203040506070809000102030405060708090102" et la chaîne commence par lnbc1pvjluez. Après le préfixe lnbc et le séparateur bech32, pvjluez est l'horodatage, 1496314658 secondes depuis le début de 1970. Le champ payment secret vient ensuite, puis le tag p, puis p5, qui est la longueur : en bech32, p vaut 1 et 5 vaut 20, donc le champ court sur 1 * 32 + 20 = 52 caractères. Ces caractères, qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq, correspondent au hash cité dans cet intitulé.

Rien n'y est privé. La spécification publie la clé privée avec laquelle ses exemples sont signés, e126f68f7eafcc8b74f54d269fe206be715000f94dac067d1c04a8ca3b2db734, et indique que chaque facture de cette section porte le payment secret 1111111111111111111111111111111111111111111111111111111111111111 sauf mention contraire, de sorte que ces chaînes sont des fixtures d'analyseur plutôt que des demandes de paiement. Si un portefeuille ou un outil de diagnostic vous montre un jour ce hash en dehors d'une suite de tests, quelque chose reproduit la spécification plutôt que de signaler votre paiement.

Payment hash vs identifiant de transaction

Un payment hash nomme un paiement Lightning ; un identifiant de transaction nomme une transaction qui existe sur la blockchain bitcoin. Les deux font 32 octets et s'affichent tous deux en 64 caractères hexadécimaux, ce qui explique qu'ils se retrouvent dans les formulaires d'assistance l'un de l'autre. Un identifiant de transaction est calculé à partir des octets de la transaction elle-même après coup et peut être collé dans n'importe quel explorateur de blocs. Un payment hash est choisi par le destinataire avant que le paiement n'existe, n'apparaît jamais dans un bloc lorsque le paiement se règle normalement, et ne renvoie rien depuis un explorateur. Un résultat de recherche vide signifie généralement que vous avez la bonne valeur et le mauvais outil.

Payment hash vs payment secret

Un payment hash et un payment secret sont deux valeurs distinctes de 256 bits dans la même facture, portées par les tags p et s et chacune encodée en 52 caractères bech32. Le hash est nécessairement public : chaque saut doit le voir pour construire son HTLC. Le secret n'est livré qu'au dernier nœud, à l'intérieur de l'oignon, et BOLT 11 énonce son rôle en une ligne, à savoir qu'il "prevents forwarding nodes from probing the payment recipient". Un lecteur qui ne trouve aucun champ s doit faire échouer le paiement d'emblée. Le hash est la serrure ; le secret est la preuve que celui qui paie a obtenu la facture de la personne qui l'a émise.