ProofLedger — Autonomous AI Escrow & Milestone Verification

Trustless milestone escrow powered by PayPal Orders v2 authorization holds, multimodal AI vision verification, and cryptographic proof chaining.

Comment

💡 Inspiration

In the global freelance gig economy—a market exceeding $1.5 trillion annually—over 30% of independent contractors report suffering from non-payment, delayed milestone releases, or fraudulent chargebacks. At the same time, clients face genuine fear: paying 100% upfront frequently results in abandoned projects, subpar deliverables, or protracted disputes.

Traditional escrow services (such as Escrow.com or Upwork) are plagued by high friction:

  • Hefty commission cuts (10% to 20%) that penalise hard-working contractors.
  • Weeks of slow, manual human arbitration where customer service agents with zero technical context must judge complex code, blueprints, or physical installations.
  • Vulnerability to bad-faith chargebacks and unilateral payment cancellations.

We asked ourselves:
What if commercial milestones could settle autonomously? What if an intelligent AI agent could inspect real-world physical and digital deliverables against explicit contract specifications, mathematically locking and releasing PayPal funds with zero human delay?

That vision inspired ProofLedger.

⚙️ What It Does

ProofLedger is the world's first autonomous AI escrow platform powered by PayPal Orders v2, multimodal computer vision, and cryptographic proof chaining. It replaces slow human arbitration with an automated, tamper-proof verification oracle.

Here is the exact autonomous settlement loop:

  1. Client Escrow Lock (PayPal Orders v2):
    The client creates an escrow milestone with explicit, verifiable criteria (e.g., HVAC pressure readings between 60–70 PSI, zero exposed wiring, or schema validation for 500 SKU entries). ProofLedger calls PayPal's Orders v2 API with intent: "AUTHORIZE". Funds are reserved on PayPal’s rails for up to 29 days without immediately transferring.

  2. Contractor Proof Submission:
    When the contractor completes the work, they upload photographic proof or documentary deliverables. The file is instantly hashed using SHA-256 and stamped with an immutable cryptographic timestamp.

  3. Autonomous Multimodal AI Oracle:
    Our AI Vision Oracle breaks the contract specifications down into an atomic criteria checklist. It forensically evaluates the submitted image—analysing edge variance, luminance, component wiring, digital gauge readings, and artefact anomalies.

  4. Dual-Pathway Autonomous Settlement (Agentic Commerce):

  5. HAPPY PATH (PASS $\ge$ 60% confidence): If all criteria are verified, ProofLedger autonomously executes a PayPal ``call. Funds transfer immediately to the contractor with zero human lag, and celebration confetti explodes across the dashboard! 🎉

  6. REJECTION PATH (FAIL < 60% confidence): If the deliverable is deficient (e.g., exposed cut copper or missing pressure gauge), the AI Oracle flags the violations and autonomously VOIDS the PayPal authorisation hold via /void, instantly returning the funds to the client! 🛑

  7. Cryptographic Proof Ledger:
    Every event (ESCROW_CREATED, ESCROW_AUTHORIZED, PROOF_SUBMITTED, AI_VERIFIED, PAYMENT_CAPTURED, PAYMENT_VOIDED) is permanently written to a SHA-256 block-chained ledger. An integrated verification endpoint recalculates the cryptographic chain in real time, guaranteeing zero tampering.

  8. 1-Click Dispute Defence Pack:
    If an off-platform dispute is ever filed, ProofLedger generates an official, two-page ReportLab PDF bundle containing timestamped evidence, visual annotations, AI confidence scores, and PayPal transaction IDs, formatted specifically for the PayPal Resolution Center.

🛠️ How We Built It

We engineered ProofLedger as an enterprise-grade full-stack architecture:

  • PayPal Financial Rails:
    Built on PayPal's Orders v2 REST API. We implemented real OAuth2 token caching, authorisation hold creation (intent: "AUTHORIZE"), programmatic /capture and /void endpoints, order inspection, and real-time webhook listeners for payment events. All verified live against the PayPal Sandbox with active credentials.

  • Multimodal AI Oracle Engine:
    A dual-layered computer vision pipeline written in Python. It includes forensic luminance and edge variance pre-processing, structured JSON criteria scoring, and pluggable support for Google Gemini 1.5 Flash Vision, OpenAI GPT-4o-mini Vision, and a deterministic forensic evaluator that ensures 100% offline uptime.

  • Cryptographic Audit Ledger:
    A custom SHA-256 hash-chained block engine (current_hash = SHA256(prev_hash + timestamp + event + payload)). Features real-time mathematical validation confirming chain integrity.

  • Dispute Generation Engine:
    ReportLab PDF streaming engine that dynamically renders a 2-page, cryptographically sealed evidence docket ready for seller protection claims.

  • High-Performance Backend:
    Python 3.11 with FastAPI (asynchronous REST framework), Pydantic v2 schemas, and SQLite with full ACID transaction guarantees. Tested with an automated Pytest suite of 21/21 passing tests (100% pass rate).

  • Production Frontend Dashboard:
    React 18 with Vite, Tailwind CSS, Lucide icons, Canvas Confetti, and refined typography (Plus Jakarta Sans for UI, JetBrains Mono for cryptographic hashes). Served directly by FastAPI on port 8000.

🧗 Challenges We Ran Into

  1. PayPal Authorisation Hold Nuances:
    Unlike instant checkout captures, authorisation holds require a strict two-step state machine (CREATED $\rightarrow$ APPROVED $\rightarrow$ AUTHORIZED $\rightarrow$ CAPTURED/VOIDED). PayPal's Orders v2 API with intent: "AUTHORIZE" returns minimal JSON unless requested with Prefer: return=representation. We built robust error handling and fallback mocks so the system functions smoothly whether fully connected to Sandbox or running in an offline developer environment.

  2. Objective Multimodal Calibration:
    Standard LLM vision queries can hallucinate or give vague answers ("the image looks good"). We engineered a strict enforcing atomic criteria decomposition, structured JSON output, individual confidence ratings, and mandatory visual evidence citations.

  3. Integrating Legacy and Modern Architectures:
    We integrated our Python FastAPI stack with the legacy Node.js/Express reference implementation from earlier drafts, ensuring full API route compatibility while upgrading the entire core to an enterprise-grade standard.

🏆 Accomplishments That We're Proud Of

  • True Agentic Commerce: We didn't just build a chatbot that chats about payments; we built an autonomous agent that moves real money bidirectionally (capturing funds on verified completion and voiding holds on substandard work).
  • 100% Test Coverage: All 21 automated Pytest tests pass in ~44 seconds, verifying state machine guards, AI evaluations, PayPal calls, and ledger cryptographic security.
  • Zero-Friction Seller Protection: The 1-click Dispute Defence Pack transforms weeks of painful arbitration into an immediate, mathematically undeniable proof bundle for PayPal's Resolution Center.
  • Flawless Demo Walkthrough: Scripted, automated, and recorded a broadcast-quality 1080p demo video aligned with millisecond precision to the pitch script.

📚 What We Learned

  • How to harness PayPal's authorisation hold architecture (intent: AUTHORIZE) as a trustless, programmable escrow mechanism rather than just a hotel booking hold.
  • How to structure multimodal AI vision prompts to achieve deterministic, auditable, and conservative criteria verification suitable for financial settlement.
  • The vital importance of Responsible AI: pairing autonomous agents with human-in-the-loop overrides (Manual Release and ``), so humans always maintain ultimate financial authority.

🔮 What's Next for ProofLedger

  1. PayPal Disputes API Two-Way Sync: Automatically submit evidence directly to POST /v1/customer/disputes/{id}/provide-evidence via API.
  2. PayPal Marketplace Multiparty Splits: Introduce a 1.5% micro-fee on settlements, automatically routing 98.5% directly to the contractor's PayPal wallet.
  3. Hardware EXIF & Geolocation Auditing: Extract camera GPS and device hardware metadata to prove physical work was performed at the correct physical site.
  4. Short Video Walkthrough Verification: Expand AI vision analysis to evaluate short 10-second video clips and 3D photogrammetry for construction and HVAC inspections.

Built With

Share this project:

Updates

Submission history