padreug created pull request aiolabs/lightning-pub#16

padreug
2026-04-02T19:21:25Z

16#feat(extensions): add split payments extension#

Summary

Adds a split payments extension that automatically distributes a percentage of every incoming payment to one or more recipients. 518 lines of TypeScript.

Closes #13

Architecture

Dual-layer split design (see #13 comment):

Layer 1 (preferred): NIP-57 zap tags — Nostr-aware wallets split at the sender side, each recipient gets a direct zap. Extension does nothing.

Layer 2 (fallback): onPaymentReceived() catches non-Nostr payments (BOLT11, LNURL, CLINK) and splits internally.

Recursion guard: metadata.splitted = true prevents the two layers from double-splitting.

RPC Methods

Method | Auth | Description
splitpay.setTargets | User | Configure split recipients and percentages (replaces all)
splitpay.getTargets | Public | List current split configuration
splitpay.clearTargets | User | Remove all targets
splitpay.getHistory | Public | View split payment audit trail (paginated)

Data Model

split_targets: recipient (pubkey/LNURL/Lightning Address), percent (0-100), alias, creator_pubkey

split_records: audit trail of every split — source payment hash, target, amount, outgoing payment hash, status (pending/success/failed), error

Validation

Total percentages must not exceed 100%

Each target must have a recipient and percent > 0

Atomic target replacement (delete all + insert all in transaction)

Files

src/extensions/splitpay/
├── index.ts                        # Extension entry, RPC registration
├── types.ts                        # Data types and request/response interfaces
├── migrations.ts                   # 2 migrations (targets + records tables)
└── managers/
    └── splitPayManager.ts          # Core logic: target CRUD + payment splitting

Test plan

TypeScript compiles

Set targets via RPC, verify stored

Receive payment → verify splits created and paid

Receive payment with splitted: true metadata → verify no re-split

Set targets exceeding 100% → verify rejection

Clear targets → verify no splits on next payment

Check history returns paginated records