story-research-zapwall/docs/payment-linking-system.md

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)