BTCPay Lightning Part 2: The Inbound Channel Journey

BTCPay Lightning, 2e partie : le parcours du canal entrant

Voici la deuxième partie du guide pour configurer le nœud Lightning d'un BTCPay Server afin qu'il puisse recevoir les paiements que les clients Shopify envoient à l'adresse du nœud Lightning qui leur est présentée lors du paiement du panier. Elle fait suite à la première partie, où nous avons configuré et ouvert notre premier canal Lightning.

Où nous en sommes : seulement de la liquidité sortante

Dans l'article précédent, nous avons doté le nœud Lightning du BTCPay Server d'un solde en satoshis et ouvert notre premier canal Lightning. Nous avions d'abord ouvert un canal vers le nœud pair ACINQ, mais des difficultés de routage nous ont poussés à explorer d'autres pairs bien connectés. Nous avons finalement établi deux canaux de 100 000 sats avec blocktank et gameb_1, deux nœuds affichés comme « Reachable » dans Lightning Terminal et ouverts aux connexions.

À l'ouverture de ces canaux, toute la capacité de transfert était du côté de la boutique. C'est ce qu'on appelle la « liquidité sortante » : nous pouvons envoyer des paiements, mais pas en recevoir.

Pour un commerçant, c'est l'inverse de ce qu'il faut. Il nous faut un moyen pour que l'argent en bitcoin aille du portefeuille du client, via Shopify, à la facture de notre nœud Lightning, puis à travers le réseau Lightning jusqu'à notre nœud, avant de « sortir en boucle » (loop out) vers le portefeuille BTC de notre BTCPay Server. Où, en bons maximalistes du Bitcoin, nous le gardons précieusement, bien sûr.

Le sens de la liquidité :

  • Liquidité sortante : vous avez des sats du côté boutique du canal, vous pouvez donc envoyer des paiements
  • Liquidité entrante : vous avez de la capacité disponible du côté boutique, vous pouvez donc recevoir des paiements

Pour les commerçants : il faut de la liquidité entrante pour recevoir les paiements des clients.

Nous avons maintenant un nœud Lightning avec deux canaux ouverts (blocktank et gameb_1), chacun avec 100 000 sats de capacité sortante et 0 sat de capacité entrante. L'étape suivante consiste à créer de la liquidité entrante pour recevoir les paiements des clients.

Créer de la liquidité entrante : deux approches

Il existe fondamentalement deux façons de créer de la capacité entrante :

  1. Dépenser des sats depuis vos canaux : quand vous envoyez un paiement Lightning, votre solde local baisse et votre solde distant augmente, ce qui crée naturellement de la capacité entrante.
  2. L'échange sous-marin (Loop Out) : vous envoyez des sats sur le réseau Lightning, recevez en retour du bitcoin classique on-chain, et cela crée de la capacité entrante sur votre canal.

Nous verrons les deux méthodes, mais commençons par installer les outils.

Lightning Terminal et Loop

Loop est un service d'échange sous-marin créé par Lightning Labs. Un échange sous-marin est un échange atomique entre bitcoin on-chain et bitcoin du réseau Lightning : il permet de déplacer des fonds entre les deux couches sans avoir à faire confiance.

Loop est inclus dans Lightning Terminal (LiT), une interface web qui regroupe plusieurs outils de gestion Lightning. L'installer sur BTCPay Server est un jeu d'enfant.

Un échange sous-marin est un échange atomique entre bitcoin on-chain et bitcoin du réseau Lightning. Il permet de déplacer des fonds entre les deux couches sans confiance : par exemple, envoyer un paiement on-chain et recevoir des sats Lightning en retour, ou l'inverse.

En bref :
il utilise le même mécanisme HTLC (contrat à verrouillage par empreinte et par temps) que Lightning lui-même. Une partie crée un secret (une préimage) et son empreinte. La transaction on-chain est verrouillée sur cette empreinte, et le paiement Lightning aussi.

Quand le paiement Lightning est réclamé, la préimage est révélée au bénéficiaire, qui s'en sert ensuite pour réclamer aussi les fonds on-chain. Comme les deux volets de l'échange utilisent le même secret, aucune partie ne peut tricher : soit les deux volets aboutissent, soit aucun.

Pourquoi « sous-marin » :
parce que la transaction « plonge sous la surface » : elle passe de la couche BTC on-chain visible (la « surface ») au réseau Lightning (qui fonctionne « sous l'eau », hors chaîne) ; dans l'échange inverse, elle remonte de Lightning vers le BTC on-chain.

Inventée par Alex Bosworth, l'un des premiers à mettre en œuvre cette technologie, la métaphore évoque le passage entre ce qui est publiquement visible sur la blockchain et ce qui se passe dans la couche hors chaîne en dessous.

Ajouter Lightning Terminal à BTCPay

BTCPay Server utilise Docker Compose avec des « fragments » optionnels, des configurations prêtes à l'emploi que l'on peut ajouter. Lightning Terminal en fait partie.

  • d'abord, connectez-vous en ssh à votre BTCPay Server et passez root.
cd ~/btcpayserver-docker
export LIT_PASSWD="YourSecurePasswordHere"
  • conservez ce mot de passe Lightning Terminal avec vos autres mots de passe de ce BTCPay Server.

Vous en aurez besoin pour lancer le « terminal » depuis la page Lightning du BTCPay Server.

  • ensuite, ajoutez le fragment BTCPay pour Lightning Terminal et relancez la configuration du BTCPay Server

export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-lightning-terminal" . ./btcpay-setup.sh -i

Des scripts BTCPay Server bien conçus :

Ne craignez pas de perdre la synchronisation de la blockchain ou les données de canaux de votre BTCPay Server en le reconfigurant. Les scripts de configuration arrêtent proprement les conteneurs, régénèrent la configuration et redémarrent le tout.

Votre nœud Bitcoin entièrement synchronisé le reste, le canal demeure intact, et tout était de nouveau en ligne en environ 5 minutes.

Les données de la blockchain de BTCPay Server vivent dans des volumes Docker persistants qui ne sont pas modifiés lors des reconfigurations. (Prudence si vous lancez vous-même des commandes Docker : quelques-unes suppriment des données et des fichiers d'état essentiels.)

Après le redémarrage, le lanceur de Lightning Terminal apparaît dans votre BTCPay Server, sur la page Lightning, à côté du lanceur de RTL.

Accéder à Lightning Terminal

Un clic sur le widget Lightning Terminal ouvre un nouvel onglet qui demande le mot de passe de Lightning Terminal. C'est le même LIT_PASSWD choisi à l'installation.

À la première connexion, il génère aussi une « Connect Passphrase », un jeton d'authentification unique pour la session. Elle est distincte de votre mot de passe et sert à sécuriser la connexion entre l'interface web et votre nœud Lightning.

Note de sécurité : la Connect Passphrase est générée automatiquement, inutile de la retenir. Elle est stockée dans la session de votre navigateur. C'est votre LIT_PASSWD que vous conservez dans votre gestionnaire de mots de passe et utilisez à chaque connexion.

Comprendre l'interface de Lightning Terminal

Lightning Terminal a une interface agréable comparée à RTL. L'onglet Explore présente des pairs recommandés selon une analyse du réseau : c'est là que nous avons trouvé blocktank et gameb_1 comme options de connexion « Reachable », après nos premiers essais avec ACINQ.

Dans l'onglet Loop, vous voyez les pairs et les canaux que vous avez ouverts. Nos deux canaux de 100 000 sats avec blocktank et gameb_1 y apparaissent.

L'interface du Loop Out repose sur un curseur. Il faut un peu de temps pour comprendre ce que règle vraiment le curseur du canal : il ajuste le PPM de la transaction Loop Out.

Qu'est-ce que le PPM ?

PPM signifie « parties par million » : c'est le taux de frais de routage que vous acceptez de payer pour que le paiement Lightning atteigne le serveur Loop.

Voici comment cela fonctionne :

  • PPM élevé (à droite du curseur) : vous acceptez de payer plus de frais, ce qui laisse plus de latitude au réseau pour trouver un chemin
  • PPM faible (à gauche du curseur) : vous payez des frais minimes, mais le routage peut échouer s'il exige des sauts coûteux

Pour un Loop Out de 100 000 sats :

  • À 500 PPM : au maximum ~50 sats de frais de routage (~0,05 dollar)
  • À 100 PPM : au maximum ~10 sats de frais de routage (~0,01 dollar)
  • À 1 PPM : routage pratiquement gratuit

Notez que ces frais réglés par le PPM s'ajoutent aux frais du service Loop (~0,5 à 1 %) et aux frais de minage de la transaction on-chain.

Utiliser le curseur

Pour faire un Loop, vous faites glisser le curseur vers la gauche : votre solde Lightning diminue et vous recevez des fonds on-chain en retour. C'est un Loop Out. Vous pouvez aussi faire un Loop In, qui réapprovisionne vos canaux Lightning avec votre solde on-chain.

Utilisez le curseur pour choisir combien de satoshis échanger. Un avertissement apparaît si vous n'atteignez pas le montant minimum d'échange des nœuds participants.

Le diagnostic : la propagation des nouveaux canaux

Avant de tenter un Loop Out ou de tester des paiements, nous avons appris une leçon importante sur la maturité des canaux.

Le gossip du réseau Lightning prend du temps

Quand vous ouvrez un canal Lightning, voici ce qui se passe :

  • Immédiatement (0 à 10 minutes) : la transaction on-chain est confirmée, le canal s'ouvre et apparaît « Active » dans votre nœud
  • Première heure : vous et votre pair connaissez le canal, mais pas le reste du réseau
  • 6 à 24 heures : l'annonce du canal se propage dans le réseau Lightning via le protocole de gossip
  • Au-delà de 24 heures : la plupart des nœuds de routage connaissent votre canal et peuvent l'inclure dans leur recherche de chemin

Après l'ouverture de nos canaux blocktank et gameb_1, il nous a fallu attendre plusieurs jours pour une propagation complète avant que le routage fonctionne de façon fiable. Utiliser des canaux très récents a provoqué des échecs de routage, non parce que quelque chose n'allait pas, mais simplement parce que le réseau ne les connaissait pas encore.

Leçon essentielle : il y a une différence entre un canal « actif » (les deux pairs en ligne, état du canal valide) et un canal « utile au routage » (les autres nœuds savent qu'il existe et peuvent passer par lui). Il faut de la patience.

Tester l'entrant : l'approche la plus simple

Après avoir attendu la propagation des canaux, nous avons décidé de créer d'abord de la capacité entrante de manière naturelle : en dépensant des sats pour acheter quelque chose d'utile.

Quand vous dépensez des sats Lightning, vous :

  • diminuez votre solde local (capacité sortante)
  • augmentez votre solde distant (capacité entrante)
  • obtenez quelque chose que vous voulez vraiment

Nous avons envisagé de passer par The Bitcoin Company pour acheter une carte cadeau, en dépensant environ 50 000 sats depuis l'un de nos canaux. Cela aurait immédiatement créé 50 000 sats de capacité entrante, remplissant la mission par un achat et nous laissant une carte cadeau utile. Ce n'était pas nécessaire. Nous l'essaierons toutefois bientôt, pour nous assurer que cela fonctionne aussi.

Tester la réception de paiements

La capacité entrante établie, il était temps de vérifier que notre nœud pouvait réellement recevoir des paiements depuis des portefeuilles externes.

Créer une facture Lightning

Dans BTCPay Server, nous avons créé une petite facture de test de 76 sats, juste assez pour vérifier que le flux de paiement fonctionnait.

La facture affiche :

  • un QR code
  • une chaîne de demande de paiement commençant par lnbc
  • l'empreinte du paiement et d'autres détails techniques

Important : assurez-vous de créer une facture Lightning, et non une adresse Bitcoin on-chain classique. Les factures Lightning commencent par « lnbc » et ont un QR code. Les adresses on-chain commencent par « bc1 » (ou d'autres formats). Ce sont des types de paiement très différents.

Première tentative : Coinbase

Nous avons d'abord essayé avec un compte Coinbase dans l'application mobile. Bien que Coinbase prenne en charge Lightning, le paiement n'a pas réglé la facture.

Cela concorde avec les signalements selon lesquels l'implémentation Lightning de Coinbase est limitée et ne fonctionne pas bien avec tous les nœuds. (Voir https://help.coinbase.com/en/coinbase/trading-and-funding/sending-or-receiving-cryptocurrency/lightning)

Succès : Wallet of Satoshi

Wallet of Satoshi est un portefeuille dédié à Lightning, aux excellentes capacités de routage. Nous avons ouvert l'application, scanné le QR code de notre facture BTCPay et appuyé sur Envoyer.

Résultat : succès ! ✅

Le paiement de 76 sats est arrivé instantanément sur notre nœud Lightning. Notre BTCPay Server a affiché la facture comme « Paid », et nous avons vu le solde du canal bouger :

  • le solde local a augmenté de 76 sats
  • le solde distant a diminué de 76 sats

Notre nœud Lightning marchand était désormais pleinement opérationnel et prêt à recevoir les paiements des clients !

Ce que cela prouve

Recevoir avec succès un paiement de Wallet of Satoshi a démontré que :

  • ✅ nos canaux Lightning se sont correctement propagés dans le réseau
  • ✅ des portefeuilles externes trouvent des chemins jusqu'à notre nœud
  • ✅ l'intégration Lightning de BTCPay Server fonctionne de bout en bout
  • ✅ nous pouvons recevoir des paiements de clients du monde entier
  • ✅ toute l'installation est prête pour l'intégration Shopify

À retenir

Ce que nous avons appris :

Sur le choix des pairs :

  • Tous les pairs Lightning ne sont pas aussi bien connectés
  • La fonction Explore de Lightning Terminal aide à trouver des pairs joignables
  • Plusieurs canaux apportent redondance et meilleur routage
  • La connectivité des pairs compte pour la réussite des paiements

Sur la liquidité entrante :

  • Ouvrir un canal crée de la liquidité SORTANTE (vous pouvez envoyer)
  • Les commerçants ont besoin de liquidité ENTRANTE (pour recevoir des paiements)
  • Dépenser des sats est la façon la plus simple de créer de la capacité entrante
  • Le Loop Out reste une alternative en cas de besoin

Sur Lightning Terminal :

  • Ajouter des fragments à BTCPay est simple avec Docker
  • Les reconfigurations ne font perdre ni la synchronisation ni les données de canaux
  • Le LIT_PASSWD défini à l'installation sert à la connexion web
  • La fonction Explore aide à repérer de bons candidats pairs

Sur la propagation dans le réseau :

  • Les nouveaux canaux mettent plus de 24 heures à se propager
  • « Active » dans RTL ne signifie pas « connu du réseau »
  • Les échecs de routage des premiers jours sont normaux, pas des erreurs
  • La patience est essentielle : attendez plusieurs jours avant de compter sur un routage fiable

Sur les tests :

  • La prise en charge de Lightning par Coinbase est limitée : déconseillée pour les tests
  • Wallet of Satoshi fonctionne de façon fiable pour tester les réceptions marchandes
  • De petites factures de test (76 à 1 000 sats) sont idéales pour valider
  • Un paiement de test réussi prouve que toute la chaîne fonctionne

Pour les autres commerçants sur ce chemin

Si vous mettez en place Lightning pour votre boutique, voici ce que je recommande d'après cette expérience :

  1. Choisissez des pairs bien connectés avec la fonction Explore de Lightning Terminal
  2. Ouvrez 2 ou 3 petits canaux plutôt qu'un grand, pour la redondance
  3. Attendez 48 à 72 heures après l'ouverture avant de tester des paiements
  4. Créez de l'entrant en dépensant d'abord pour des cartes cadeaux ou des articles utiles
  5. Testez avec Wallet of Satoshi avant d'activer en production
  6. Commencez par de petites factures (100 à 1 000 sats) pour valider le flux

Le délai total entre le lancement de votre BTCPay Server et l'acceptation des paiements Lightning des clients est d'environ 3 à 5 jours, en comptant la synchronisation de la blockchain, les confirmations d'ouverture des canaux et la propagation dans le réseau. Mais l'essentiel est de l'attente passive, pas du travail actif.

Le temps de configuration réellement passé à la main est peut-être de 2 à 3 heures au total, sur les deux parties.

Récapitulatif des coûts

Voici ce qu'a coûté cette installation Lightning :

  • Bitcoin pour les canaux : l'équivalent de 200 dollars en deux canaux de 100 000 sats (c'est du CAPITAL, pas une dépense : il vous appartient toujours dans les canaux)
  • Frais on-chain d'ouverture des canaux : ~10 à 15 dollars au total
  • Coût du serveur : instance AWS EC2 (~40 à 60 dollars par mois pour un nœud complet)

Prêt pour la production

Avec une liquidité entrante établie et un paiement de test confirmé, le nœud Lightning est prêt pour l'intégration Shopify. L'étape suivante consiste à activer Lightning comme moyen de paiement dans la boutique et à traiter de vrais paiements de clients.

Le chemin, de zéro connaissance de Lightning à un nœud marchand opérationnel, a demandé de la patience et du dépannage, mais le résultat est un système de paiement en auto-conservation, capable d'accepter des paiements Bitcoin instantanés et peu coûteux depuis n'importe où dans le monde.

Retour au blog