story-research-zapwall/docs/split-and-transfer.md

Implémentation du split et transfert automatique

Date : Décembre 2024 Auteur : Équipe 4NK

Contexte

Cette session implémente les fonctionnalités manquantes pour compléter le système de commissions :

1. Split pour le sponsoring (Bitcoin mainnet)
2. Split pour les avis (Lightning)
3. Système de transfert automatique après paiement

Implémentations

1. Split pour le sponsoring (Bitcoin mainnet)

Fichier créé : lib/sponsoringPayment.ts

Fonctionnalités :

• Service SponsoringPaymentService pour gérer les paiements de sponsoring
• Validation du montant (0.046 BTC total)
• Calcul du split (0.042 BTC auteur, 0.004 BTC plateforme)
• Génération des adresses Bitcoin pour la transaction
• Vérification des transactions Bitcoin (structure préparée)

Fonctionnement :

1. L'utilisateur demande un paiement de sponsoring
2. Le service calcule le split et retourne les adresses
3. L'utilisateur crée une transaction Bitcoin avec deux sorties :
   • Sortie 1 : 0.042 BTC vers l'adresse de l'auteur
   • Sortie 2 : 0.004 BTC vers l'adresse de la plateforme
4. La plateforme vérifie que la transaction contient les deux sorties correctes
5. Le sponsoring est enregistré et tracé

Limitations actuelles :

• La vérification de transaction nécessite un service blockchain (à implémenter)
• Le tracking nécessite une intégration avec un explorateur Bitcoin

2. Split pour les avis (Lightning)

Fichier créé : lib/reviewReward.ts

Fonctionnalités :

• Service ReviewRewardService pour gérer les rémunérations d'avis
• Création d'invoice Lightning avec commission (70 sats total)
• Split automatique (49 sats reviewer, 21 sats plateforme)
• Transfert automatique de la part du reviewer
• Mise à jour de l'avis avec tag rewarded: true

Fonctionnement :

1. L'auteur clique sur "Remercier" pour un avis
2. Le service crée une invoice Lightning de 70 sats
3. L'auteur paie l'invoice
4. Après confirmation du paiement :
   • La plateforme reçoit 70 sats
   • Le service déclenche le transfert automatique de 49 sats au reviewer
   • La plateforme garde 21 sats de commission
   • L'avis est mis à jour avec le tag rewarded: true

Limitations actuelles :

• Le transfert automatique nécessite l'adresse Lightning du reviewer (à récupérer du profil)
• Nécessite un nœud Lightning de la plateforme pour effectuer les transferts

3. Système de transfert automatique

Fichier créé : lib/automaticTransfer.ts

Fonctionnalités :

• Service AutomaticTransferService pour gérer les transferts automatiques
• Transfert de la part de l'auteur après paiement d'article
• Transfert de la part du reviewer après rémunération d'avis
• Tracking des transferts requis
• Logs structurés pour audit

Fonctionnement :

1. Après confirmation d'un paiement, le service calcule le split
2. Il déclenche un transfert automatique vers l'auteur/reviewer
3. Le transfert est tracé et loggé
4. En cas d'échec, le transfert peut être fait manuellement plus tard

Intégration :

• Intégré dans lib/paymentPolling.ts pour les articles
• Intégré dans lib/reviewReward.ts pour les avis

Limitations actuelles :

• Nécessite un nœud Lightning de la plateforme pour effectuer les transferts
• Nécessite les adresses Lightning des auteurs/reviewers (à récupérer des profils)
• Pour l'instant, les transferts sont loggés mais pas exécutés automatiquement

Architecture

Flux de paiement article avec transfert automatique

1. Lecteur paie 800 sats → Invoice Lightning
2. Paiement confirmé via zap receipt
3. Contenu privé envoyé au lecteur
4. Tracking avec commissions (700/100)
5. Transfert automatique déclenché :
   - 700 sats vers auteur (si adresse disponible)
   - 100 sats gardés par plateforme
6. Transfert tracé et loggé

Flux de rémunération avis avec transfert automatique

1. Auteur paie 70 sats → Invoice Lightning
2. Paiement confirmé via zap receipt
3. Transfert automatique déclenché :
   - 49 sats vers reviewer (si adresse disponible)
   - 21 sats gardés par plateforme
4. Avis mis à jour avec tag rewarded: true
5. Transfert tracé et loggé

Flux de sponsoring avec split

1. Utilisateur demande sponsoring (0.046 BTC)
2. Service calcule split :
   - 0.042 BTC → auteur
   - 0.004 BTC → plateforme
3. Service retourne deux adresses Bitcoin
4. Utilisateur crée transaction avec deux sorties
5. Transaction broadcastée sur Bitcoin mainnet
6. Plateforme vérifie transaction (à implémenter)
7. Sponsoring enregistré et tracé

Fichiers créés

1. lib/automaticTransfer.ts - Service de transfert automatique
2. lib/sponsoringPayment.ts - Service de paiement sponsoring
3. lib/reviewReward.ts - Service de rémunération avis
4. features/split-and-transfer-implementation.md - Cette documentation

Fichiers modifiés

1. lib/paymentPolling.ts - Intégration du transfert automatique pour articles

Prochaines étapes

Pour le transfert automatique Lightning

1. Récupérer les adresses Lightning :

   • Ajouter un champ lightningAddress dans les profils Nostr
   • Récupérer depuis les métadonnées de profil (NIP-05, etc.)
   • Stocker dans le cache local

2. Implémenter le transfert réel :

   • Intégrer avec un nœud Lightning de la plateforme
   • Utiliser l'API du nœud pour créer et payer des invoices
   • Gérer les erreurs et retry

3. Queue de transferts :

   • Créer une queue pour les transferts en attente
   • Traiter les transferts en batch
   • Gérer les échecs et retry

Pour le sponsoring

1. Vérification de transaction :

   • Intégrer avec un explorateur Bitcoin (Blockstream API, etc.)
   • Vérifier que la transaction contient les deux sorties
   • Vérifier les montants et adresses

2. Tracking sur Nostr :

   • Publier des événements de tracking pour les sponsoring
   • Mettre à jour le tag total_sponsoring sur l'article de présentation

Pour les avis

1. Récupération adresse reviewer :

   • Récupérer depuis le profil Nostr du reviewer
   • Stocker dans le cache

2. Mise à jour de l'avis :

   • Implémenter la mise à jour de l'événement Nostr avec tag rewarded: true
   • Publier l'événement mis à jour

Résultat

Les trois fonctionnalités sont maintenant implémentées avec :

• ✅ Calcul et validation des splits
• ✅ Services prêts pour l'intégration
• ✅ Tracking et logs structurés
• ⏳ Transferts automatiques (nécessitent nœud Lightning)
• ⏳ Vérification transactions Bitcoin (nécessitent service blockchain)

Le système est prêt pour l'intégration avec les services externes nécessaires.