Tributary: Executable Revenue-Share Infrastructure

Turn plain-English revenue-share contracts into deterministic, integer-cent multi-party payouts on PayPal with zero float loss and automated refund clawbacks.

Comment

Inspiration

Revenue-share agreements power the modern creator, freelance, indie game, and startup economies. Whether it is an indie dev team splitting game sales, a podcast network dividing sponsorship revenue, creators launching courses with marketing partners, or developers collaborating on client projects, revenue-sharing aligns incentives without requiring upfront capital.

Yet in practice, revenue-sharing is fragile and error-prone:

  1. The Spreadsheet Trap: Payout calculations are typically done manually in spreadsheets weeks or months after sales occur. Collaborators have little visibility into how deductions or fees were calculated.
  2. The Recoup & Tier Straddle Dilemma: Deals frequently involve recoupment (e.g. Maya fronting $400 for art) followed by tiered revenue splits (e.g. 40/30/20/10 until $2,000 net, then 25/25/25/25). Single transactions that straddle boundary thresholds almost always cause spreadsheet calculation errors.
  3. The Post-Payout Refund Crisis: What happens when a customer requests a $50 refund after payouts have already cleared into collaborator accounts? In traditional setups, the merchant absorbs the loss or attempts awkward manual clawbacks.
  4. The LLM Math Risk: While Large Language Models excel at understanding contract legalese, LLMs cannot perform exact financial arithmetic. Floating-point roundoffs and hallucinated numbers in financial transactions break trust and violate accounting integrity.

I built Tributary to solve this with a neuro-symbolic architecture: an LLM parses natural-language agreements and interrogates ambiguous clauses; but a pure, deterministic integer-cent engine handles 100% of the financial math, backed by SQLite 3-layer idempotency, PayPal Orders v2, and PayPal Payouts v1.

What It Does

Tributary is a complete revenue settlement platform organized across four cohesive screens:

  1. Deal Studio (Contract Compilation & Ambiguity Interrogation): Users paste any plain-English agreement. Google Gemini 2.5 Flash extracts payees, basis points, recoupment terms, and reserve holdbacks into a strictly validated DealSpec schema. Crucially, Tributary flags latent contract ambiguities (such as whether recoupment occurs before or after PayPal processing fees) and requires human signatories to resolve them interactively before locking the terms with an immutable SHA-256 deal hash.
  2. Waterfall Simulator (Property-Based Prover): An interactive FinOps sandbox featuring an integer-cent volume slider and recoupment tracker. It runs 100 randomized property tests via fast-check to prove that not a single cent is created or lost across arbitrary sales volumes ($1 to $50,000).
  3. Live Settlement Ledger (Orders v2 + Payouts v1): Captures customer checkouts via PayPal Orders v2, ingests exact merchant processing fees (sellerReceivableBreakdown.paypalFee), and dispatches multi-party batch payouts via PayPal Payouts v1 directly to collaborator personal sandbox accounts. When a customer refund occurs post-payout, Tributary's Refund Clawback Engine drains rolling reserves first, records any remaining deficit pro-rata, and automatically nets it out against each payee's future sales.
  4. Payee Statements & Allowlist Verifier: Individual collaborator dashboards detailing Total Earned, Total Paid via PayPal, Carried Forward Balance, and Recovery Deficits. Gemini drafts natural-language statement explanations, while a Strict Allowlist Number Verifier extracts every currency token via regex and validates it against the deterministic engine trace allowlist. Any number not present in the engine trace is intercepted and rejected.
  5. 8-Test Chaos Drawer: Slide-over failure injection harness testing duplicate webhooks, tampered signatures, out-of-order refunds, batch replays, unclaimed timeouts, concurrent double-clicks, and deliberate 1-cent invariant tampering—all simulated locally in-process with continuous audit continuity.

How I Built It

Tributary was built around 5 Core Invariants:

1. Modular Boundary: AI Plane Never Touches Money

The ai-compiler module is strictly separated from financial execution. It never imports from paypal-gateway, never accesses PayPal credentials, and never performs monetary arithmetic. It is strictly limited to extracting structured contract schemas and explaining verified ledger traces.

2. Pure Integer-Cent Financial Core

Zero floating-point arithmetic. All monetary strings are converted into exact integer cents ("100.02" $\rightarrow$ 10002). Every settlement enforces the hard conservation invariant:

$$\text{feeCents} + \text{reserveCents} + \sum \text{payoutCents} + \sum \text{carriedForwardCents} + \text{withheldRecoveryCents} \equiv \text{grossCents}$$

If this equation fails by even a single cent, the engine halts immediately with an InvariantViolationError and logs a halt event in the audit chain.

3. 3-Layer Idempotency Architecture

  • Transport Layer: Deterministic PayPal-Request-Id headers generated for all capture and refund calls.
  • Database Mutex: Deterministic sender_batch_id = "trib_" + SHA256(saleId + ":" + dealHash) enforced by SQLite UNIQUE PRIMARY KEY constraints before network dispatch.
  • Webhook Deduplication: Dedicated webhook_events table with event_id PRIMARY KEY deduplication prior to processing.

4. Technical Stack

  • Backend: Node.js 22 (ESM), TypeScript 5.7, Hono, SQLite with better-sqlite3.
  • PayPal Integration: @paypal/paypal-server-sdk v2.5.0 for Orders v2 & Captures/Refunds v2; typed REST client for Payouts v1 and Webhook Signature Verification.
  • AI Compiler: Google Gemini 2.5 Flash (temperature: 0, strict JSON mode) with an SHA-256 Record/Replay cache (fixtures/replay-cache.json) for zero-key offline reproducibility.
  • Frontend: React 18, Vite 6, Tailwind CSS 3.4, Lucide Icons, formatted with tabular numerals (.tabular-nums).
  • Testing: Vitest (49 unit, integration, and chaos tests), fast-check (2,000 property-based testing runs).

Challenges I Faced

  1. APIMatic SDK v2.5.0 Method Migration: During Day-1 sandbox smoke tests, I noticed legacy methods (ordersCreate, ordersCapture) had evolved into controller-scoped methods (ordersController.createOrder, ordersController.captureOrder). I mapped these into typed wrappers and documented the signatures in APIMATIC_DEVLOG.md.
  2. Defensive Fee Extraction: PayPal captures return seller_receivable_breakdown in snake_case over REST, whereas the APIMatic SDK exposes camelCase sellerReceivableBreakdown. I implemented defensive extraction to safely convert string fees into integer cents without float loss.
  3. Canonical JSON Serialization for Audit Continuity: In SQLite audit logging, JavaScript objects with undefined fields can cause hash discrepancies when re-serialized. I wrote a lexicographically sorted canonicalJson() serializer to guarantee consistent SHA-256 hash chaining.
  4. Net Revenue Tier Straddling: When a single transaction crosses a boundary threshold, Tributary dynamically divides the sale into pre-tier and post-tier pools, applies distinct basis-point splits, and awards remaining cents using the Largest-Remainder (Hamilton) method.

What I Learned & What's Next

  • Neuro-Symbolic Design is Essential in FinTech: Generative AI should interpret human intent, while deterministic state machines handle the math. This separation provides the natural-language flexibility of LLMs alongside the exactness of double-entry bookkeeping.
  • Next Steps: Multi-currency FX conversion for global teams, automated 1099 tax exports directly from the audit log, and recurring subscription stream-splitting via PayPal Subscriptions.

Built With

Share this project:

Updates

Submission history