story-research-zapwall/features/zapwall4science-refactoring.md

Refonte zapwall4Science - Spécifications

Date : Décembre 2024 Auteur : Équipe 4NK

🎯 Objectif

Transformation de Nostr Paywall en zapwall4Science : plateforme de publication d'articles scientifiques et de science-fiction avec système de sponsoring, commissions et rémunération des avis.

---

📝 Wording et terminologie

Acteurs

• Auteur : Utilisateur qui publie des articles (science-fiction ou recherche scientifique)
• Lecteur : Utilisateur qui lit les articles et peut poster des avis
• Site : La plateforme zapwall4Science (recevant les commissions)

Contenus

• Article : Publication d'un auteur (science-fiction ou recherche scientifique)
• Article de présentation : Article obligatoire créé par chaque auteur lors de son inscription, contenant sa présentation, description de son contenu et adresse de sponsoring mainnet
• Avis : Commentaire/évaluation d'un article par un lecteur qui a acheté l'article
• Message d'envoi de l'article : Message privé chiffré (kind:4) envoyé automatiquement après paiement d'un article

Paiements

• Paiement : Transaction Bitcoin/Lightning pour accéder à un article ou sponsoriser un auteur
• Sponsoring : Paiement unique de 0.05 BTC pour sponsoriser un auteur (0.004 BTC au site, 0.046 BTC à l'auteur)
• Commission pour le site sur la vente d'un article : 100 sats sur chaque achat d'article (800 sats total, 700 à l'auteur)
• Commission pour le site sur le remerciement d'un avis : 21 sats sur chaque rémunération d'avis (70 sats au lecteur, 21 sats au site)
• Remerciement pour l'avis : Paiement de 70 sats (21 sats commission site) par l'auteur à un lecteur pour son avis

---

🏗️ Architecture fonctionnelle

1. Article de présentation obligatoire

Description : Chaque auteur doit créer un article de présentation lors de sa première connexion.

Contenu obligatoire :

• Titre : "Présentation de [Nom auteur]"
• Présentation personnelle de l'auteur
• Description/aperçu du type de contenu qu'il publie
• Adresse Bitcoin mainnet pour le sponsoring (obligatoire)

Caractéristiques :

• Article gratuit (pas de paiement requis)
• Visible par tous
• Tag spécial : presentation: true
• Tag : category: author-presentation
• Tag : mainnet_address: [adresse]
• Non supprimable (peut être édité)
• Un seul par auteur

Fichiers à créer/modifier :

• components/AuthorPresentationEditor.tsx : Éditeur d'article de présentation
• lib/articlePublisher.ts : Vérification de l'existence d'un article de présentation
• hooks/useAuthorPresentation.ts : Hook pour gérer l'article de présentation
• types/nostr.ts : Ajout du type AuthorPresentationArticle

---

2. Division en 2 catégories

Catégories :

1. Science-fiction (category: science-fiction)
2. Recherche scientifique (category: scientific-research)

Fonctionnalités :

• Les auteurs peuvent publier dans les 2 catégories
• Filtrage par catégorie sur la page d'accueil
• Onglets ou sections distinctes pour chaque catégorie
• Tag obligatoire category sur chaque article (sauf article de présentation)

Fichiers à créer/modifier :

• components/CategoryFilter.tsx : Filtre par catégorie
• pages/index.tsx : Affichage par catégories
• lib/articleFiltering.ts : Filtrage par catégorie
• types/nostr.ts : Ajout de ArticleCategory

---

3. Tri des articles

Ordre de tri :

1. Par sponsoring : Auteurs les plus sponsorisés en premier
2. Par date : Articles les plus récents en premier (parmi les auteurs de même niveau de sponsoring)

Calcul du sponsoring :

• Somme totale des paiements de sponsoring reçus par l'auteur
• Stocké dans un tag sur l'article de présentation : total_sponsoring: [montant en sats]
• Mis à jour à chaque nouveau sponsoring

Fichiers à créer/modifier :

• lib/articleFiltering.ts : Tri par sponsoring puis date
• lib/sponsoring.ts : Service de gestion du sponsoring
• types/nostr.ts : Ajout de totalSponsoring dans Article

---

4. Système de sponsoring

Montant : 0.05 BTC (5 000 000 sats)

Répartition :

• Site : 0.004 BTC (400 000 sats) - frais de transaction payés par l'auteur
• Auteur : 0.046 BTC (4 600 000 sats) - frais de transaction payés par l'auteur

Fonctionnement :

• Paiement unique vers l'adresse mainnet de l'auteur (depuis l'article de présentation)
• Transaction Bitcoin mainnet (pas Lightning)
• Mise à jour du tag total_sponsoring sur l'article de présentation
• Affichage du montant total sponsorisé sur le profil de l'auteur

Fichiers à créer/modifier :

• components/SponsorButton.tsx : Bouton de sponsoring
• lib/sponsoring.ts : Service de sponsoring
• lib/bitcoinMainnet.ts : Service pour les paiements mainnet
• types/sponsoring.ts : Types pour le sponsoring

---

5. Paiement d'article modifié (BOLT12)

Montant : 800 sats

Répartition :

• Auteur : 700 sats - frais de transaction payés par l'auteur
• Site : 100 sats - frais de transaction payés par l'auteur

Technologie : BOLT12 (offers) pour diviser automatiquement le paiement

Fonctionnement :

• Création d'une offre BOLT12 avec split automatique
• 700 sats vers l'adresse Lightning de l'auteur
• 100 sats vers l'adresse Lightning du site
• Frais de transaction payés par l'auteur (déduits de sa part)

Fichiers à créer/modifier :

• lib/bolt12.ts : Service BOLT12 pour les offres avec split
• lib/payment.ts : Modification pour utiliser BOLT12
• types/payment.ts : Types pour BOLT12

---

6. Système de rémunération des avis

Conditions :

• Seuls les lecteurs qui ont acheté l'article peuvent poster un avis
• L'auteur peut rémunérer un avis avec 70 sats

Répartition :

• Lecteur (auteur de l'avis) : 70 sats - frais de transaction payés par l'auteur
• Site : 21 sats - frais de transaction payés par l'auteur

Fonctionnement :

• Bouton "Remercier" sur chaque avis (visible uniquement par l'auteur de l'article)
• Paiement Lightning avec split automatique (BOLT12)
• Tag sur l'avis : rewarded: true, reward_amount: 70

Fichiers à créer/modifier :

• components/ArticleReview.tsx : Composant d'avis avec bouton de rémunération
• components/ReviewRewardButton.tsx : Bouton de rémunération d'avis
• lib/reviewReward.ts : Service de rémunération des avis
• types/reviews.ts : Types pour les avis

---

🔧 Modifications techniques

Structure de données

Article de présentation

interface AuthorPresentationArticle extends Article {
  category: 'author-presentation'
  mainnetAddress: string
  totalSponsoring: number // en sats
  isPresentation: true
}

Article standard

interface StandardArticle extends Article {
  category: 'science-fiction' | 'scientific-research'
  authorPresentationId: string // ID de l'article de présentation
  lightningAddress: string // Adresse Lightning de l'auteur
}

Avis

interface Review {
  id: string
  articleId: string
  authorPubkey: string // Auteur de l'article
  reviewerPubkey: string // Lecteur qui a écrit l'avis
  content: string
  rating?: number // 1-5 étoiles
  createdAt: number
  rewarded: boolean
  rewardAmount?: number // 70 sats si rémunéré
  rewardTransactionId?: string
}

Tags Nostr

Article de présentation

- title: "Présentation de [Nom]"
- category: "author-presentation"
- presentation: "true"
- mainnet_address: "[adresse Bitcoin]"
- total_sponsoring: "[montant en sats]"

Article standard

- title: "[Titre]"
- category: "science-fiction" | "scientific-research"
- preview: "[Aperçu]"
- zap: "800"
- author_presentation_id: "[ID article présentation]"
- lightning_address: "[adresse Lightning auteur]"
- invoice: "[BOLT12 offer]"

Avis (kind:1 avec tag spécial)

- review: "true"
- e: "[ID article]"
- p: "[pubkey auteur]"
- rating: "[1-5]"
- rewarded: "true" | "false"
- reward_amount: "70" (si rémunéré)

---

📁 Fichiers à créer

Nouveaux composants

• components/AuthorPresentationEditor.tsx
• components/CategoryFilter.tsx
• components/CategoryTabs.tsx
• components/SponsorButton.tsx
• components/ArticleReview.tsx
• components/ReviewRewardButton.tsx
• components/ReviewForm.tsx

Nouveaux services

• lib/sponsoring.ts
• lib/bitcoinMainnet.ts
• lib/bolt12.ts
• lib/reviewReward.ts
• lib/reviews.ts

Nouveaux hooks

• hooks/useAuthorPresentation.ts
• hooks/useSponsoring.ts
• hooks/useReviews.ts
• hooks/useReviewReward.ts

Nouveaux types

• types/sponsoring.ts
• types/reviews.ts
• types/bolt12.ts

---

📁 Fichiers à modifier

Pages

• pages/index.tsx : Ajout des catégories et tri par sponsoring
• pages/publish.tsx : Sélection de catégorie obligatoire
• pages/profile.tsx : Affichage de l'article de présentation et sponsoring

Composants existants

• components/ArticleCard.tsx : Affichage catégorie et sponsoring
• components/ArticleEditor.tsx : Sélection de catégorie
• components/UserProfile.tsx : Affichage sponsoring total

Services existants

• lib/articlePublisher.ts : Vérification article de présentation
• lib/payment.ts : Migration vers BOLT12
• lib/articleFiltering.ts : Tri par sponsoring
• lib/nostr.ts : Parsing des nouveaux tags

Types existants

• types/nostr.ts : Ajout des nouveaux types

---

🔄 Flux utilisateur

Inscription d'un auteur

1. Connexion avec Nostr
2. Redirection vers création d'article de présentation (obligatoire)
3. Remplissage : présentation, description, adresse mainnet
4. Publication de l'article de présentation
5. Accès à la plateforme

Publication d'un article

1. Sélection de la catégorie (science-fiction ou recherche)
2. Remplissage du formulaire (titre, preview, contenu)
3. Création de l'offre BOLT12 avec split (700/100)
4. Publication avec tags appropriés

Achat d'un article

1. Clic sur "Unlock for 800 sats"
2. Affichage de l'offre BOLT12
3. Paiement Lightning
4. Réception automatique du contenu (message privé)
5. Possibilité de poster un avis

Sponsoring d'un auteur

1. Clic sur "Sponsor" sur l'article de présentation
2. Affichage de l'adresse mainnet
3. Paiement Bitcoin mainnet de 0.05 BTC
4. Mise à jour du sponsoring total
5. Tri mis à jour

Rémunération d'un avis

1. Auteur voit l'avis d'un lecteur qui a acheté
2. Clic sur "Remercier (70 sats)"
3. Paiement Lightning avec split (70/21)
4. Tag rewarded: true sur l'avis

---

⚠️ Points d'attention

BOLT12

• Vérifier la compatibilité avec Alby/WebLN pour BOLT12
• Implémenter le split automatique dans l'offre
• Gérer les frais de transaction

Bitcoin Mainnet

• Intégration avec un service de paiement mainnet (ou QR code)
• Vérification des paiements mainnet
• Gestion des confirmations

Sécurité

• Vérifier que seuls les acheteurs peuvent poster des avis
• Vérifier que seul l'auteur peut rémunérer les avis
• Vérifier l'authenticité des paiements

Performance

• Indexer les articles par catégorie
• Indexer les auteurs par sponsoring total
• Cache des calculs de tri

---

📊 Priorités d'implémentation

Phase 1 - Fondations

1. ✅ Wording et terminologie (documentation)
2. ⏳ Article de présentation obligatoire
3. ⏳ Division en catégories
4. ⏳ Tri par sponsoring puis date

Phase 2 - Paiements

5. ⏳ Système de sponsoring (Bitcoin mainnet)
6. ⏳ Migration vers BOLT12 pour les articles
7. ⏳ Split automatique des paiements

Phase 3 - Avis et rémunération

8. ⏳ Système d'avis (seulement pour acheteurs)
9. ⏳ Rémunération des avis par l'auteur

Phase 4 - UI/UX

10. ⏳ Interface par catégories
11. ⏳ Affichage du sponsoring
12. ⏳ Interface de rémunération des avis

---

🎨 Renommage

• Nom du site : zapwall4Science
• Titre : "zapwall4Science - Science Fiction & Scientific Research"
• Description : "Plateforme de publication d'articles scientifiques et de science-fiction avec sponsoring et rémunération des avis"

Fichiers à modifier :

• pages/index.tsx : Titre et description
• pages/_app.tsx : Titre par défaut
• README.md : Nom et description
• Tous les composants avec "Nostr Paywall" → "zapwall4Science"

---

📝 Notes techniques

BOLT12 Offers

• Utiliser lightning:lno1... pour les offres
• Split automatique via les métadonnées de l'offre
• Vérifier la compatibilité avec les wallets Lightning

Bitcoin Mainnet

• Utiliser une API de vérification de transactions (blockchain.info, blockstream, etc.)
• QR code pour faciliter les paiements
• Affichage clair de l'adresse et du montant

Stockage

• Stocker les montants de sponsoring dans IndexedDB
• Cache des calculs de tri
• Synchronisation avec les événements Nostr

---

✅ Checklist de validation

• Article de présentation créé pour chaque auteur
• Catégories fonctionnelles (science-fiction / recherche)
• Tri par sponsoring puis date opérationnel
• Sponsoring Bitcoin mainnet fonctionnel
• Paiements articles avec BOLT12 et split
• Avis uniquement pour les acheteurs
• Rémunération des avis fonctionnelle
• Wording cohérent partout
• Renommage complet en zapwall4Science