Nicolas Cantu
a099f3c24a
- Fusion tous documents implémentations en features.md - Suppression documents redondants/obsolètes : - final-cleanup-summary.md, storage-encryption.md - storage-improvement-implementation.md, notifications-scope.md - user-profile-implementation.md, filtering-search-implementation.md - article-edit-delete.md, priority1-implementation.md - alby-integration.md, nostr-paywall-implementation.md - technical-doc.md (redondant avec docs/technical.md) - rizful-integration.md (obsolète, remplacé par Alby) - Documentation fidèle au code actuel - Garde zapwall4science-refactoring.md (spécifications) - Garde series-and-media-spec.md (spécifications) - Garde notifications-implementation.md (détails techniques)
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 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.
|