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.