107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
# Payment Linking System
|
|
|
|
**Author**: Équipe 4NK
|
|
**Date**: 2026-01-14
|
|
|
|
## Overview
|
|
|
|
This document describes the system for linking payments, payment notes, and related objects (publications, reviews, authors), and tracking funds received by authors and the platform.
|
|
|
|
## Structure
|
|
|
|
### Objects and Payments
|
|
|
|
- **Publications** (kind 1, type='publication'): Objects that are purchased
|
|
- Contains pages in JSON metadata (not separate notes)
|
|
- Linked via `articleId` tag in payment events
|
|
- Purchased via zap receipts (kind 9735) with `kind_type: purchase`
|
|
|
|
- **Series** (kind 1, type='series'): Objects that are reviewed
|
|
- Linked via `seriesId` tag in review payment events
|
|
- Reviews are about series
|
|
|
|
- **Reviews** (kind 1, type='quote'): Objects that are rewarded
|
|
- Linked via `reviewId` tag in payment events
|
|
- Rewarded via zap receipts (kind 9735) with `kind_type: review_tip`
|
|
|
|
- **Authors** (kind 1, type='author'): Objects that are sponsored
|
|
- Linked via `authorPubkey` / `#p` tag in payment events
|
|
- Sponsored via zap receipts (kind 9735) with `kind_type: sponsoring` (Lightning)
|
|
- Sponsored via Bitcoin mainnet transactions (mempool)
|
|
|
|
### Payment Flow
|
|
|
|
1. **Zap Receipt** (kind 9735) is created by Lightning wallet
|
|
- Contains payment hash, amount, recipient pubkey
|
|
- Tagged with `kind_type: purchase | review_tip | sponsoring`
|
|
- Links to object via tags: `article`, `review_id`, `author` (seriesId)
|
|
|
|
2. **Payment Note** (kind 1, type='payment') is published by platform/user
|
|
- Contains same information as zap receipt
|
|
- Links to zap receipt via `zap_receipt` tag
|
|
- Links to object via tags: `article`, `review_id`, `series`, `author`
|
|
|
|
3. **Funds Split**:
|
|
- **Author funds**: Amount received by author (after platform commission)
|
|
- **Platform funds**: Commission amount collected by platform
|
|
|
|
## Links
|
|
|
|
### Purchase Payment
|
|
- Zap Receipt (kind 9735) → `#e: [articleId]`, `#p: [authorPubkey]`, `kind_type: purchase`
|
|
- Payment Note (kind 1) → `article: [articleId]`, `recipient: [authorPubkey]`, `zap_receipt: [zapReceiptId]`
|
|
- Publication (kind 1) → `id: [articleId]`
|
|
|
|
### Review Tip Payment
|
|
- Zap Receipt (kind 9735) → `#p: [authorPubkey]`, `#e: [articleId]`, `kind_type: review_tip`, `review_id: [reviewId]`
|
|
- Payment Note (kind 1) → `recipient: [authorPubkey]`, `article: [articleId]`, `review_id: [reviewId]`, `zap_receipt: [zapReceiptId]`
|
|
- Review (kind 1) → `id: [reviewId]`, `article: [articleId]`
|
|
|
|
### Sponsoring Payment
|
|
- Zap Receipt (kind 9735) → `#p: [authorPubkey]`, `kind_type: sponsoring`
|
|
- OR Bitcoin Transaction (mempool) → verified via transaction ID
|
|
- Payment Note (kind 1) → `recipient: [authorPubkey]`, `zap_receipt: [zapReceiptId]` OR `transaction_id: [txId]`
|
|
- Author Presentation (kind 1) → `id: [authorPresentationId]`, `pubkey: [authorPubkey]`
|
|
|
|
## Funds Tracking
|
|
|
|
### For Each Author
|
|
|
|
**Funds Received** (author portion):
|
|
- Purchase payments: Total from zap receipts - platform commission
|
|
- Review tips: Total from zap receipts - platform commission
|
|
- Sponsoring (Lightning): Total from zap receipts - platform commission
|
|
- Sponsoring (Bitcoin mainnet): Total from verified transactions - platform commission
|
|
|
|
**Platform Funds** (commission):
|
|
- Purchase commission: 100 sats per purchase (from 800 sats total)
|
|
- Review tip commission: Variable per tip
|
|
- Sponsoring commission: Variable per sponsoring
|
|
|
|
### Implementation
|
|
|
|
1. Query all zap receipts for author (as recipient)
|
|
2. Query all payment notes for author (as recipient)
|
|
3. Query Bitcoin mainnet transactions for author's mainnet address
|
|
4. Calculate funds split for each payment
|
|
5. Aggregate totals
|
|
|
|
## Tags Enhancement
|
|
|
|
### Payment Notes should include:
|
|
- `publication_id` or `article`: Publication/Article ID
|
|
- `series_id` or `series`: Series ID (if applicable)
|
|
- `review_id`: Review ID (for review tips)
|
|
- `author`: Author pubkey (recipient)
|
|
- `zap_receipt`: Zap receipt ID (if Lightning)
|
|
- `transaction_id`: Bitcoin transaction ID (if mainnet sponsoring)
|
|
- `platform_commission`: Commission amount
|
|
- `author_funds`: Funds received by author
|
|
|
|
### Zap Receipts already include:
|
|
- `#e`: Event ID (article ID for purchases)
|
|
- `#p`: Pubkey (author pubkey)
|
|
- `kind_type`: Payment type
|
|
- `review_id`: Review ID (for review tips)
|
|
- `series`: Series ID (optional)
|