# Embassy Trust Protocol — Payments & Settlement Layer

**Status:** Service-layer specification  
**Protocol:** ETP (Embassy Trust Protocol) — draft-0.1  
**Positioning:** Settlement and credit acceptance, not finance

**Public runtime:** Organization plans (Teams £49/mo, Business £299/mo) are billed in GBP via Stripe Checkout at `/pricing`. This document also specifies agent-token / IOU adapters; those adapters are **not** live checkout. Embassy does not price, convert, or redeem tokens.

---

## Overview

The Embassy Service supports payments for services through a settlement layer. This layer is **service-layer only** and **not part of the core ETP protocol**.

**Critical Constraint:**
> We are not building a treasury, bank, exchange, or token issuer. We are building a settlement and credit acceptance layer.

---

## Design Principles

### Protocol Neutrality

- **ETP remains payment-agnostic**
- Payments are a service-layer concern only
- No financial logic in core verification paths
- Protocol verification is independent of payment status

### Dual Payer Model

**Humans → Fiat Payments**
- Stripe, card, invoice
- Standard payment processing
- Receipts for accounting

**Agents → Agent-Native Value**
- Tokens (ERC-20, etc.)
- IOUs (agent-signed promises)
- Platform credits
- Receipts for audit

### No Treasury Speculation

**Embassy does not:**
- Trade tokens
- Price or value tokens
- Expose balance sheets as financial instruments
- Promise redemption, yield, or conversion

**Embassy does:**
- Verify payment proofs
- Confirm settlement
- Issue service credits (internal only)
- Generate receipts

### Closed-Loop Credit Use

**Embassy Credits:**
- Issued when agent payments settle
- Non-transferable
- Non-withdrawable
- Service-scoped
- Expirable (optional)

**Credits are NOT money.**
They are prepaid service allowances.

### Receipts Over Accounts

**Every payment produces a signed receipt:**
- Receipts are verifiable via `/api/verify`
- Receipts contain no pricing opinions
- Receipts are proof of settlement, not value
- No running "accounts" in protocol layer

---

## System Components

### 1. Settlement Adapter Interface

**Purpose:** Abstract payment verification

**Interface:**
```typescript
interface SettlementAdapter {
  verifyPayment(proof: PaymentProof): Promise<VerificationResult>;
}

interface VerificationResult {
  verified: boolean;
  amount: string;
  payer_type: "human" | "agent";
  reference: string;
  currency: string;
}
```

**Adapters:**
- `StripeAdapter` — Fiat payments (humans)
- `ERC20Adapter` — ERC-20 token transfers (agents)
- `IOUAdapter` — Agent-signed promises (agents)
- Future adapters (platform credits, DAOs)

### 2. Payment Intent Model

**Purpose:** Unified payment intent schema

**Schema:**
```json
{
  "intent_id": "pay_int_xxxx",
  "payer_type": "human | agent",
  "method": "fiat | agent_token | iou",
  "service": "authoritative_visa | verification | continuity | registry",
  "amount": "string",
  "currency": "USD | TOKEN_SYMBOL | CREDIT",
  "status": "pending | settled | rejected",
  "created_at": "ISO8601",
  "agent_id": "emb_xxxx | null",
  "metadata": {}
}
```

**No balances. No accounts.**
Only intents → verification → settlement → receipt.

### 3. Embassy Credits (Internal Only)

**Purpose:** Service-scoped credits for agent payments

**Schema:**
```json
{
  "credit_id": "cred_xxxx",
  "agent_id": "emb_xxxx",
  "issued_for": "authoritative_visa | verification | continuity | registry",
  "amount": "100",
  "issued_at": "ISO8601",
  "payment_intent_id": "pay_int_xxxx",
  "status": "active",
  "spent": "0"
}
```

**Properties:**
- Non-transferable
- Non-withdrawable
- Service-scoped
- Expirable (optional)

**Credits are NOT money.**
They are prepaid service allowances.

### 4. Payment Receipts

**Purpose:** Verifiable proof of settlement

**Receipt Type:** `payment_settlement`

**Event Fields:**
```json
{
  "decision": "settled",
  "reason_code": "PAYMENT_VERIFIED",
  "payment_intent_id": "pay_int_xxxx",
  "payer_type": "human | agent",
  "method": "fiat | agent_token | iou",
  "service": "authoritative_visa | verification | continuity | registry",
  "amount": "10",
  "currency": "USD | TOKEN_SYMBOL | CREDIT",
  "settlement_reference": "tx_hash_or_payment_intent_id",
  "credits_issued": "cred_xxxx | null"
}
```

**Receipts:**
- Are verifiable via `/api/verify`
- Contain no pricing opinions
- Are proof of settlement, not value
- Are signed and tamper-evident

---

## API Endpoints

### POST /api/payment_intent

**Purpose:** Create payment intent

**Request:**
```json
{
  "payer_type": "human | agent",
  "method": "fiat | agent_token | iou",
  "service": "authoritative_visa | verification | continuity | registry",
  "amount": "10",
  "currency": "USD | TOKEN_SYMBOL | CREDIT",
  "agent_id": "emb_xxxx" // Required for agent payments
}
```

**Response:**
```json
{
  "ok": true,
  "intent_id": "pay_int_xxxx",
  "status": "pending",
  "created_at": "ISO8601"
}
```

### POST /api/settle_payment

**Purpose:** Verify proof, settle intent, issue receipt

**Request:**
```json
{
  "intent_id": "pay_int_xxxx",
  "proof": {
    "method": "fiat | agent_token | iou",
    "reference": "tx_hash_or_payment_intent_id",
    "data": {
      // Method-specific proof data
    }
  }
}
```

**Response:**
```json
{
  "ok": true,
  "intent_id": "pay_int_xxxx",
  "status": "settled",
  "receipt_id": "rct_xxxx",
  "credits_issued": "cred_xxxx | null"
}
```

### GET /api/credits/:agent_id

**Purpose:** Get non-financial credit balances

**Response:**
```json
{
  "ok": true,
  "agent_id": "emb_xxxx",
  "credits": {
    "authoritative_visa": "100",
    "verification": "50",
    "continuity": "0",
    "registry": "0"
  },
  "note": "Credits are non-transferable, non-withdrawable service allowances. Not financial instruments."
}
```

### GET /api/ledger/settlements

**Purpose:** Public, read-only, aggregated settlement view

**Response:**
```json
{
  "ok": true,
  "aggregates": {
    "total_settlements": 1000,
    "by_payer_type": {
      "human": 600,
      "agent": 400
    },
    "by_method": {
      "fiat": 600,
      "agent_token": 300,
      "iou": 100
    },
    "by_service": {
      "authoritative_visa": 500,
      "verification": 300,
      "continuity": 100,
      "registry": 100
    }
  },
  "note": "This is a non-financial settlement ledger. No valuations, no P&L, no balances. Only settlement counts and service usage."
}
```

---

## Language Rules

### Allowed Words

- settled
- verified
- credited
- receipted
- spent
- scoped
- expired

### Forbidden Words

- balance (financial sense)
- worth / value
- investment
- yield
- redeem
- exchange
- market
- price discovery
- profit

---

## Positioning

### Correct Framing

> "Agents and humans can settle payment for Embassy services using methods appropriate to them. Settlement produces cryptographic receipts and service credits."

### Incorrect Framing

> "The Embassy holds tokens / runs a treasury / manages assets"

---

## Out of Scope

**Do NOT implement:**
- Token swaps
- Withdrawals
- Exchange rates
- Yield / staking / lending
- Wallet UX
- Asset custody guarantees
- Financial advice or valuation

**IN SCOPE:**
- Payment verification
- Settlement confirmation
- Credit issuance (internal only)
- Receipt generation
- Public transparency endpoints (non-financial)

---

## Implementation Status

**Current Status:** Specification and reference implementation

**Implemented:**
- Settlement adapter interface
- Payment intent model
- Embassy Credits (internal ledger)
- Payment receipt generation
- API endpoints (payment_intent, settle_payment, credits_status, settlements_ledger)

**Adapters:**
- `StripeAdapter` — Placeholder (requires Stripe integration)
- `ERC20Adapter` — Placeholder (requires blockchain RPC)
- `IOUAdapter` — Placeholder (requires agent signature verification)

**Production Requirements:**
- Stripe integration for fiat payments
- Blockchain RPC integration for ERC-20 verification
- Agent signature verification for IOU validation
- Credit ledger persistence (currently in-memory)

---

## See Also

- [COMMERCIAL.md](COMMERCIAL.md) — Commercial model and products
- [PRODUCT.md](PRODUCT.md) — Product positioning
- [docs/ETP.md](docs/ETP.md) — Protocol specification
- [docs/RECEIPT-FORMAT.md](docs/RECEIPT-FORMAT.md) — Receipt format specification

---

## Settlement-to-Service Bridge

Credits are prepaid service allowances. Spending credits produces a verifiable service receipt that references the original payment receipt, forming a complete audit chain.

### Receipt Chain

1. **Payment Receipt** (`payment_settlement` type)
   - Emitted when payment settles
   - Contains: payment intent ID, payer type, method, amount, currency, settlement reference
   - Links to: credit issuance (internal ledger)

2. **Credit Issuance** (internal ledger entry)
   - Credits issued to agent upon payment settlement
   - Stored with: `payment_receipt_id`, `settlement_intent_id`, `reference`
   - Non-transferable, non-withdrawable, service-scoped

3. **Service Receipt** (`service_receipt` type)
   - Emitted when credits are consumed for a service
   - Contains: service name, result, credit consumed (credit_id, amount)
   - Links to: `payment_receipt_id` (root of settlement)
   - Verifiable via `/api/verify`

### Credit Consumption

Service requests can include an optional `credit_consumption` object:

```json
{
  "credit_consumption": {
    "credit_id": "cred_...",
    "amount": "10"
  }
}
```

If present:
- Credits are validated and atomically decremented
- Double-spend protection via idempotency keys
- Service receipt is emitted linking back to payment receipt
- Service is delivered only if credit consumption succeeds

### Atomicity

Credit consumption is atomic:
- Compare-and-set operations prevent partial spends
- Idempotency keys prevent double-spending
- Credits cannot be spent below zero
- Service delivery only occurs after successful credit consumption

### Example Flow

1. Agent settles payment → Payment Receipt (`rct_payment_123`)
2. Embassy issues credits → Credit record (`cred_456`) with `source.payment_receipt_id = rct_payment_123`
3. Agent requests service with credit consumption → Service Receipt (`rct_service_789`) with `event.links.payment_receipt_id = rct_payment_123`
4. Complete audit chain: `rct_payment_123` → `cred_456` → `rct_service_789`

---

## North Star

**The Embassy does not manage money.**
It manages proof that payment occurred.

**Agents don't "pay you".**
They settle access.

**Humans don't "buy crypto services".**
They purchase trust guarantees.