🚢 Autonomous TEE Trade Finance (Letter of Credit) Agent

An autonomous escrow agent for international trade finance executing Letter of Credit (LC) agreements. The agent locks a buyer's funds, verifies unstructured logistics webhooks, and securely releases payment to the exporter.

By executing the trade rules and payment resolution inside a secure Trusted Execution Environment (TEE) boundary via the Terminal 3 Agent Auth SDK, the agent never exposes sensitive keys or exporter destination accounts, and every state transition is recorded in an immutable cryptographic audit ledger.

---

🌐 Live Demo

The application is deployed live and fully functional at: 👉 Autonomous TEE Trade Finance Agent - Live Demo

You can interact with the live dashboard and trigger test scenarios directly on the web app.

➕ How to Create Custom Contracts (Scenarios)

Click the CREATE CONTRACT button in the top right of the console to deploy your own custom Letter of Credit (LC) and test different policy gates.

Here is how to set up the form for each situation:

1. Successful Settlement (Happy Path)

• Value (AUD): 25000 (or any amount)
• Target Delivery Port: Rotterdam
• Policy Customization: Leave Customize TEE Policy Rules unchecked.
• Simulation: Click Authorize Escrow, then click Simulate Delivery. The webhook port matches the target port (Rotterdam), and the payment resolves successfully (SETTLED).

2. Port Mismatch Denial

• Value (AUD): 25000
• Target Delivery Port: Rotterdam (where cargo is simulated to arrive)
• Policy Customization: Check Customize TEE Policy Rules and set Required Port to Hamburg (or any port other than Rotterdam).
• Simulation: Click Simulate Delivery. The webhook reports arrival at Rotterdam but the policy requires Hamburg, triggering a policy rejection (DENIED).

3. Over Value Cap Denial

• Value (AUD): 60000
• Target Delivery Port: Rotterdam
• Policy Customization: Check Customize TEE Policy Rules and set Max Value Cap to 50000 (lower than the contract Value).
• Simulation: Click Simulate Delivery. The policy engine flags that the contract value exceeds the maximum allowable cap, blocking the payout (FAILED).

4. Automatic Exporter Payout Setup (Stripe Connect)

• Exporter Reference: Set to a new reference (e.g., exporter-ref:my-custom-cargo-999).
• Simulation: The enclave automatically provisions a new Stripe Connect custom account on-the-fly to receive the payout, demonstrating dynamic merchant routing. Use exporter-ref:acme-textiles-001 to test using the pre-seeded account.

---

🛠️ Tech Stack & Components

• Secure Enclave Sandbox: Terminal 3 Agent Auth SDK (WASM cryptographic metamorphic signatures, on-chain DID identity challenges).
• AI Document Parser: Google Gemini 2.5 Flash (Structured JSON parsing of raw, unstructured Bill of Lading webhooks).
• Database & Schema Engine: Prisma ORM with Neon Serverless PostgreSQL (Fully migrated from SQLite for production-grade reliability).
• Escrow holds & Exporter Payouts: Stripe Connect API (Requires capture hold initialization and connected exporter account routing).
• Framework & Hosting: Next.js 14 (App router, TypeScript, deployed on Vercel).

---

💡 Why Terminal 3 Agent Auth SDK?

This project fundamentally depends on Terminal 3's secure capabilities:

1. Zero Server Trust for Keys: Without Terminal 3, Stripe live secrets and merchant connected credentials would have to be stored on standard application databases, forcing users to blindly trust server operators. Under T3, these keys are resolved only inside the hardware-isolated enclave memory.
2. Delegated Authority Control: The buyer delegates payment release authority using standard wallets, producing a cryptographically verified capability. The agent cannot act without this signed delegation.
3. Cryptographic Audit Trail: Every policy decision, TEE execution, and payout creates an signed receipt bound to the Agent's DID, ensuring total compliance without leaking corporate trade secrets.

📊 Project Metrics

• 3 Security Zones (Client Zone ➔ TEE Enclave ➔ Settlement)
• 5 Core SDK Integration Points
• 3 Pre-Seeded Verification Scenarios
• 5 Lifecycle State Machine Transitions
• 100% Cryptographically Signed State Receipts

🛡️ Agent Auth SDK Coverage

• Agent Identity Verification (DID contract validation)
• Delegation Credential Issuance (Browser EIP-191 delegation)
• TEE Isolated Resolution (Secure enclave execution)
• Secure Payout Resolution (Stripe Connect shielding)
• Replay Protection (Secure nonces and preimage signing)
• Immutable Cryptographic Audit Logging (Agent DID signed receipts)

---

🗺️ Architecture Overview

Our architecture splits execution into three strict security zones to ensure no sensitive hot keys or bank details escape the isolated TEE boundary:

1. Client Zone (Browser): The buyer uses their wallet to sign a contract delegation credential (EIP-191). This creates a secure, signed capability represented by an opaque placeholder. The agent never sees the buyer's private key.
2. TEE Enclave (Private Execution): When a Bill of Lading delivery webhook is received, the agent operates in hardware-isolated memory. It uses Google Gemini to parse the unstructured logistics data, feeding it into a deterministic TypeScript policy engine. The LLM acts purely as an advisor; the code remains the sole gatekeeper for funds.
3. Settlement Zone (Stripe & Ledger): If policy checks pass, the TEE agent resolves the opaque exporter placeholder to a real Stripe Connected Account ID and captures the escrow hold.

---

🛠️ Terminal 3 SDK Integration Points

For hackathon judging, here is exactly where the Terminal 3 Agent Auth SDK is implemented in the codebase:

• Connection & Handshake (lib/t3/client.ts): Initializes the SDK and loads WASM components required for secure metamorphic signatures and enclave handshake.
• Agent Identity Verification (lib/t3/adk.ts#L80-L125): Before executing privileged logic, the agent signs a challenge with its private key, resolving its registered Agent DID (did:t3n:c9f6b88a...) on-chain.
• Credential Minting (lib/t3/adk.ts#L150-L200): Captures the buyer's browser signature and packages it into a cryptographically signed Delegation Credential, returning an opaque buyerPlaceholder.
• TEE Resolution (lib/t3/adk.ts#L280-L330): Inside the isolated execution boundary, the agent builds a replay-resistant preimage containing the delegation ID, a secure nonce, and the release hash, signing it locally to authorize payout execution.
• Cryptographic Audit Write (lib/t3/adk.ts#L380-L420): Computes the SHA-256 block receipt hash and signs the state transition receipt using the agent DID.

---

🌟 Premium Visual & UX Features

• Dynamic Visual Inspector Drawer: Inspecting any enclave milestone (like policy.check, llm.parse, or payout.fire) opens a visual side drawer displaying EIP-191 signatures, Gemini's parsed explanation, and policy check pass/fail markers.
• Zero-Configuration Stripe Connect: If a new exporter is registered (e.g. exporter-ref:royal-dutch-yarn-999) and has no pre-mapped Stripe Connect ID, the agent automatically provisions a test-mode Custom Connected Account on-the-fly and caches it in stripe_destinations_cache.json.
• Interactive Enclave Panel: Highlights milestones in emerald green or amber orange, with an interactive security topology diagram visualizing active boundaries.
• Custom Contracts & Policy Rules: Toggle the creation modal to set customized required ports or max limit caps, making it easy to test policy gate violations.

---

🏁 The 4-Click Judge Journey

To verify the entire project in under 60 seconds, follow these 4 clicks:

1. Click 1: Select the Rotterdam Letter of Credit (exporter-ref:acme-textiles-001) from the console list.
2. Click 2: Click Authorize Escrow (Simulates buyer wallet signature delegation & places Stripe hold).
3. Click 3: Click Simulate Port Delivery (Fires BoL webhook, runs LLM document parsing, deterministic policy checks, and enclave payouts).
4. Click 4: Click Inspect Proof on any completed milestone (like llm.parse or policy.check) to view the visual signature card and policy outcome details.

---

🔬 Testing & Demo Scenarios

The project ships pre-seeded with three validation scenarios so you can test all policy gates instantly. Here is the operational flowchart for each:

1. Scenario 1: Happy Path Settlement

• Config: Rotterdam LC, $25,000 value, $50,000 maximum cap.
• Outcome: Bill of lading matches the contract terms, Stripe captures the hold, and executes transfer to connected account (SETTLED).

2. Scenario 2: Port Mismatch Denial

• Config: Rotterdam cargo delivery, but terms require Hamburg port.
• Outcome: The deterministic policy gate flags mismatch and aborts settlement (FAILED).

3. Scenario 3: Over Value Cap

• Config: Singapore cargo delivery, but LC value ($95,000) exceeds maximum cap ($50,000).
• Outcome: Policy gate detects limit overrun and aborts settlement (FAILED).

---

🚀 Quick Start & Run Locally

1. Install Dependencies

npm install

2. Set Up Environment

Copy the example environment file:

cp .env.example .env.local

Configure your DATABASE_URL in .env.local to point to a PostgreSQL database (e.g., Neon or Supabase). Your registered Agent DID (did:t3n:c9f6b88a...) and private keys are pre-configured for instant sandbox testing.

3. Initialize Database

Push the schema and seed the initial Letters of Credit to your PostgreSQL database:

npm run db:push

npm run db:seed

4. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

5. Run Integration Tests

Verify all gates, duplicate webhook protection, and signature checks:

npm run smoke:step5

6. Verify Cryptographic Ledger Integrity

Run the auditing tool to verify transition paths and hash chains:

npm run audit:verify

This CLI tool validates state transition legality and computes a Git-style rolling SHA-256 chain hash over the ledger history, proving no database tampering has occurred.

---

🐳 Run with Docker

You can package and run the application in a Docker container, passing your PostgreSQL configuration.

1. Build the Image

docker build -t trade-finance-agent .

2. Run the Container

Make sure your .env.local file contains the correct DATABASE_URL pointing to your Neon/PostgreSQL database.

docker run -d -p 3000:3000 --env-file .env.local trade-finance-agent

---

📹 Video Presentation

Watch the system walkthrough, live Stripe dashboard verification checklist, and the step-by-step judge demo:

• YouTube Video Presentation