Transaction Twin

The trust and recovery layer for autonomous commerce: enforcing human intent across the PayPal lifecycle with continuous verification and safe recovery.

Comment

Inspiration

When autonomous AI agents are given delegated spending power to shop on our behalf, traditional e-commerce checkouts break down. Conventional payment checkouts were designed for a human reviewing an order summary before clicking "Place Order".

Autonomous shopping agents operate in dynamic, noisy merchant environments:

  1. Dynamic Cart Drift: A user instructs an agent to "Buy Sony WH-1000XM5 headphones for under $400". The agent navigates to the retailer, but shipping fees, merchant price adjustments, or dynamic checkout pricing push the total to $429.
  2. Subtle SKU Substitutions: An out-of-stock item is silently swapped for a refurbished unit, an incorrect colorway, or an incompatible variant.
  3. Ghost Subscriptions: A one-time purchase option switches to a recurring monthly auto-ship plan during final checkout steps.
  4. The Agentic Checkout Dilemma: When agents use traditional 1-step capture payments, funds leave the user's account before anyone catches the discrepancy. Resolving errors after settlement requires manual customer support, merchant disputes, or bank chargebacks—which cost businesses $3.60 for every $1.00 in dispute.

We realized that the payment layer itself must become an active verifier. By anchoring the agent's workflow to a two-step PayPal authorization hold (intent: 'AUTHORIZE'), we can create an architectural safety window: human intent is compiled into an immutable digital contract, reality is continuously reconciled against that contract during agent checkout, and any detected deviation triggers deterministic pre-capture recovery—such as voiding the uncaptured authorization hold before merchant capture, releasing reserved funds without moving capital into settlement.

What It Does

Transaction Twin wraps every autonomous transaction in an immutable, dual-state digital twin that reconciles human intent against reality across the PayPal lifecycle:

  1. Human Intent Compilation: Natural language prompts are compiled into cryptographically anchored, typed IntentContract schemas with exact numeric budgets ($400.00), condition allowlists, and delivery constraints.
  2. Two-Step Financial Isolation: The agent initiates a PayPal Order with intent: 'AUTHORIZE', placing funds on hold without moving money into merchant settlement ($349.99 in the demonstration).
  3. Continuous Pre-Capture Verification: As the agent checks out, Transaction Twin continuously monitors 12 drift categories (including PRICE_LIMIT, CATEGORY_MATCH, and SUBSCRIPTION_TRAP).
  4. Deterministic Policy Clearance: If drift is detected ($429.00 cart vs $400 budget), a hardcoded policy engine evaluates 9 rules before any recovery action can execute. AI is strictly prohibited from executing financial mutations.
  5. Pre-Capture Recovery: In live sandbox mode, the system dispatches a void request to PayPal to release the authorization hold. In the public demonstration transaction, evaluators can inspect the pre-execution hold and trigger simulated void execution with $0.00 settled.
  6. Cryptographic Proof Graph: State transitions and verification events are recorded in an append-only, SHA-256 hash-chained event store, viewable in an interactive visual proof graph and an AG Grid Evidence Explorer.

How We Built It

  • PayPal Platform Integration: Built in @transaction-twin/paypal with support for Orders v2 (createOrder, getOrder), Authorizations v2 (authorizeOrder, getAuthorization), Payments v2 (voidAuthorization, captureAuthorization, refundCapture), Webhooks with cryptographic signature verification (verifyWebhookSignature), and OAuth2 with token caching. Implements PayPal-Request-Id idempotency headers on mutating requests.
  • AI Cognitive Layer: Powered by Google Gemini (gemini-1.5-pro via @google/genai) for intent compilation, product catalog proposal evaluation, semantic anomaly findings, and causal post-mortem narratives. Includes heuristic fallback provider for resilient offline operation.
  • Deterministic Policy Firewall: Built in @transaction-twin/recovery and @transaction-twin/verifier, enforcing cent-exact budget math and 9 hardcoded rules (Rules A through E).
  • State Machine & Cryptographic Event Store: Formally specifies transaction lifecycles and records SHA-256 Merkle-chained event logs.
  • Web Application & Evidence Explorer: Next.js 14 App Router, TypeScript, Tailwind CSS, AG Grid React (^36.2.0), and a 30-scenario Chaos Lab simulation suite.

Challenges We Faced

  1. Reconciling Probabilistic AI with Financial Determinism: Segregating duties so AI only compiles intent and suggests advisory findings, while pure deterministic code enforces financial state transitions and PayPal API mutations.
  2. Managing Pre-Capture Hold Semantics: Shifting from direct capture to intent: 'AUTHORIZE' required modeling the full PayPal authorization lifecycle and tracking order-to-authorization ID linking.
  3. Idempotency & Deduplication: Enforcing unique PayPal-Request-Id headers and hashing operation keys to prevent duplicate lifecycle executions during asynchronous agent operations.

Accomplishments That We're Proud Of

  • 100% Passing Automated Test Suite: 529 automated tests across 74 test suites passing cleanly with 0 type errors and 0 lint warnings.
  • Architectural Pre-Capture Protection: Intercepting cart drift during the PayPal authorization hold state, allowing uncaptured funds to be voided before settlement ($0.00 settled in the demonstrated recovery flow).
  • Comprehensive Chaos Lab: 30 automated simulation scenarios (C01 through C30) demonstrating resilience against edge cases without external network calls.
  • Enterprise-Grade AG Grid Integration: Evidence Explorer built on AG Grid React for compliance and audit log inspection.
  • Hermetic Production Deployment: Deployed and live as a Docker container on Render.

What We Learned

  • Pre-Capture Holds are Essential for Agentic Commerce: The two-step authorization pattern creates a time-bounded safety window to verify merchant reality before money moves permanently.
  • Separation of Cognitive and Settlement Layers: An AI agent should never be handed a blank check; the cognitive layer must be separated from financial execution by a deterministic policy firewall.

What's Next for Transaction Twin

  • Agentic Commerce Protocol (ACP): Formalizing IntentContract schemas into an open specification for agentic shopping frameworks (LangChain, AutoGen, Browser-Use).
  • Merchant Webhook Sidecars: Native Shopify and WooCommerce plugins for real-time pricing and stock locks.
  • Multi-Agent Budget Pools: Shared spending limits and departmental approval workflows for autonomous agent teams.

Built With

  • ag-grid-react
  • docker
  • google-gemini-api
  • lucide-react
  • next.js-14
  • node.js
  • paypal-authorizations-v2-api
  • paypal-developer-platform
  • paypal-orders-v2-api
  • paypal-payments-v2-api
  • render
  • tailwind-css
  • typescript
  • zod
Share this project:

Updates

Submission history