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.

Système de tags Nostr

Nouveau système de tags (tous en anglais)

Tous les contenus sont des notes Nostr (kind 1) avec un système de tags unifié :

• Type : #author, #series, #publication, #quote (tags simples sans valeur)
• Catégorie : #sciencefiction ou #research (tags simples sans valeur)
• ID : #id_<id> (tag avec valeur : ['id', '<id>'])
• Paywall : #paywall (tag simple, pour les publications payantes)
• Payment : #payment (tag simple optionnel, pour les notes de paiement)

Utilitaires (lib/nostrTagSystem.ts)

• buildTags() : Construit les tags à partir d'un objet typé
• extractTagsFromEvent() : Extrait les tags d'un événement
• buildTagFilter() : Construit les filtres Nostr pour les requêtes

Internationalisation (i18n)

Système de traduction (lib/i18n.ts)

• Chargement depuis fichiers texte plats (public/locales/fr.txt, public/locales/en.txt)
• Format : key=value avec support des paramètres {{param}}
• Hook useI18n pour utiliser les traductions dans les composants
• Initialisé dans _app.tsx avec locale par défaut (fr)

Langues supportées

• Français (fr) : langue par défaut
• Anglais (en) : disponible
• Extensible : ajout de nouvelles langues via fichiers de traduction

Financement IA

Jauge de financement (components/FundingGauge.tsx)

• Affiche le montant collecté, la cible (0.27 BTC) et le pourcentage
• Calcul des fonds via lib/fundingCalculation.ts
• Agrégation de toutes les commissions (articles, avis, sponsoring)
• Description de l'usage des fonds pour le développement IA

Calcul des fonds (lib/fundingCalculation.ts)

• Estimation basée sur les taux de commission
• Agrégation des zap receipts par type (purchase, review_tip, sponsoring)
• Calcul du pourcentage de progression vers la cible

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.