story-research-zapwall/docs/technical.md

Documentation technique

Auteur : Équipe 4NK

Architecture

Zapwall est une plateforme décentralisée basée sur Nostr pour la publication et la monétisation de contenu. Le système utilise Lightning Network pour les paiements et Bitcoin mainnet pour le sponsoring.

Services principaux

• Nostr (lib/nostr.ts) : Pool de connexions, publication/récupération d'événements, profils, zap requests
• Paiements (lib/payment.ts, lib/paymentPolling.ts) : Invoices Lightning via Alby/WebLN, vérification zap receipts (NIP-57), envoi automatique contenu privé
• Commissions (lib/platformCommissions.ts) : Configuration centralisée, calcul splits, validation montants
• Tracking (lib/platformTracking.ts, lib/sponsoringTracking.ts) : Événements Nostr (kind 30078/30079) pour audit
• Intégrations :
  • lib/mempoolSpace.ts : Vérification transactions Bitcoin via mempool.space API
  • lib/lightningAddress.ts : Récupération adresses Lightning depuis profils Nostr (lud16/lud06)

Stockage

• IndexedDB : Contenu privé chiffré (AES-GCM)
• localStorage : Métadonnées articles, invoices
• Nostr : Contenus publics et événements de tracking

Système de commissions

Configuration (lib/platformCommissions.ts)

• Articles : 800 sats (700 auteur, 100 plateforme)
• Avis : 70 sats (49 reviewer, 21 plateforme)
• Sponsoring : 0.046 BTC (0.042 auteur, 0.004 plateforme)

Implémentation

Articles (lib/paymentPolling.ts, lib/articleInvoice.ts) :

• Validation montant 800 sats à chaque étape
• Tracking avec author_amount et platform_commission dans événements Nostr
• Récupération adresse Lightning auteur via lightningAddressService
• Transfert automatique déclenché (logs, nécessite nœud Lightning pour exécution)

Sponsoring (lib/sponsoringPayment.ts, lib/sponsoringTracking.ts) :

• Validation montant 0.046 BTC
• Vérification transactions Bitcoin via mempoolSpaceService (sorties auteur + plateforme)
• Tracking sur Nostr (kind 30079) avec confirmations

Avis (lib/reviewReward.ts) :

• Validation montant 70 sats
• Mise à jour événement Nostr avec tags rewarded: true et reward_amount: 70
• Récupération adresse Lightning reviewer
• Transfert automatique déclenché (logs, nécessite nœud Lightning)

Tracking

Tous les paiements sont trackés sur Nostr :

• Kind 30078 : Livraisons de contenu (lib/platformTracking.ts)
• Kind 30079 : Paiements de sponsoring (lib/sponsoringTracking.ts)

Les événements incluent author_amount, platform_commission, zap_receipt (si applicable), et sont signés par l'auteur avec tag p pour la plateforme.

Flux de paiement article

1. Lecteur clique "Unlock for 800 sats"
2. Création invoice Lightning via Alby/WebLN (lib/articleInvoice.ts)
3. Publication zap request sur Nostr (NIP-57)
4. Lecteur paie l'invoice
5. Polling vérification zap receipt (lib/paymentPolling.ts)
6. Envoi automatique contenu privé (message chiffré NIP-04, lib/articlePublisher.ts)
7. Tracking livraison avec commissions (lib/platformTracking.ts)

Flux de sponsoring

1. Utilisateur demande sponsoring 0.046 BTC (lib/sponsoringPayment.ts)
2. Service calcule split (0.042/0.004 BTC)
3. Retourne deux adresses Bitcoin (auteur + plateforme)
4. Utilisateur crée transaction avec deux sorties
5. Vérification via mempool.space (lib/mempoolSpace.ts)
6. Tracking sur Nostr (lib/sponsoringTracking.ts)

Vérification livraison contenu

Le système vérifie l'envoi du contenu privé à trois niveaux :

1. Publication : publishEvent() retourne l'ID de l'événement publié
2. Vérification relay : verifyPrivateMessagePublished() confirme présence sur relay (timeout 5s)
3. Tracking : Événement Nostr (kind 30078) avec verified: true/false

Tous les événements sont loggés avec IDs, timestamps et statuts.

Limitations

Transferts Lightning automatiques : Nécessitent un nœud Lightning de la plateforme. Actuellement, les transferts sont loggés dans lib/automaticTransfer.ts et peuvent être exécutés manuellement. Les adresses Lightning sont récupérées automatiquement depuis les profils Nostr.