# 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)