Nicolas Cantu
9ea4965c05
- Fusion tous documents commissions en technical.md - Suppression documents redondants : - architecture.md, commissions.md, commission-system.md - commission-implementation.md, split-and-transfer.md - implementation-summary.md, content-delivery-verification.md - Documentation fidèle au code actuel - remaining-tasks.md mis à jour avec état réel - Documentation centralisée et sans répétitions
93 lines
4.1 KiB
Markdown
93 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.
|
|
|