# uWu Protocol — Whitepaper (v0.1, March 2026)

## Abstract

uWu is **payment-attestation infrastructure**: it verifies that a fiat payment (starting with India’s UPI ecosystem) actually occurred, then issues a **cryptographic attestation** that can trigger **on-chain settlement** (e.g., escrow release) without screenshots, manual clearing, or custody of INR.

**One-line thesis:** verify a bank/UPI payment event → produce a signed attestation → release escrowed digital assets according to contract rules.

---

## 1. Problem

India’s digital economy runs on real-time payments (UPI and bank rails). Yet **cross-app verification** is still brittle:

- Screenshots are forgeable.
- Merchant-dashboard polling is siloed and not interoperable.
- Manual verification creates disputes, delays, and support cost.
- “Proof of payment” rarely composes into **programmable settlement** across neutral platforms.

uWu targets this gap by becoming a **neutral verification + attestation layer** for any marketplace, desk, or dApp.

---

## 2. Solution overview

uWu introduces a **Payment Attestation Layer** with four cooperating components:

1. **Escrow (on-chain)** — locks assets under deterministic rules + timeouts.
2. **Attestation oracle (off-chain)** — verifies payment events and signs attestations.
3. **Verification engine** — connects to compliant rails (Account Aggregator first-class; OCR/MVP demos optional).
4. **API + SDK** — developer surface to request attestations and complete settlement flows.

**Core flow**

1. Maker locks assets in escrow (native PC or ERC-20, depending on deployment).
2. Taker pays INR off-chain (UPI today).
3. Oracle verifies payment via trusted rails and produces an attestation.
4. Anyone submits attestation + signature on-chain to release funds (subject to contract checks).

---

## 3. Threat model (high level)

Primary threats include:

- **Forged proofs** (fake receipts / tampered evidence)
- **Replay** (reusing the same proof twice)
- **Oracle compromise** (signing key misuse)
- **Risk / fraud** patterns (velocity, suspicious rails, inconsistent amounts)

Mitigations (design targets):

- Use **bank-sourced** verification where possible (AA data).
- Contracts enforce **replay protection**, **expiry**, and **risk thresholds**.
- Long-term: **multi-signer attestations** and public audit logs.

---

## 4. Attestation interface

Attestations are structured payloads describing what was verified (trade linkage, amounts, payer/payee identifiers hashed, timestamps, evidence hash, risk score, oracle identity).

- Human-readable reference: `docs/uwu-attestation-spec.md` (EIP-712 domain + typed data in newer iterations).

On-chain verifiers can check attestations using:

- Escrow contract path (`UwuEscrow`), or
- Composable verification via `UwuAttestationLib` (example integration contracts).

---

## 5. Architecture

```text
┌─────────────┐   UPI / bank    ┌──────────────────┐   signed attestation   ┌──────────────┐
│   Taker     │ ──────────────▶ │ Verification      │ ────────────────────▶ │    Oracle    │
│  (fiat)     │                 │ Engine (AA/OCR)  │                       │   Signer     │
└─────────────┘                 └──────────────────┘                       └──────┬───────┘
                                                                                  │
                                                                                  ▼
┌─────────────┐   create/lock   ┌──────────────────┐   submit proof          ┌──────────────┐
│   Maker     │ ──────────────▶ │ On-chain Escrow   │ ◀────────────────────── │  Any submitter│
│  (crypto)   │                 │ (deterministic)   │                       │  (taker/bot)  │
└─────────────┘                 └──────────────────┘                       └──────────────┘
```

---

## 6. Product surfaces

### 6.1 REST API (oracle)

Canonical endpoints include:

- `POST /api/attest` — request attestation after payment evidence is available
- `GET /api/attestation/:hash` — fetch stored attestation metadata (implementation-dependent)
- `GET /api/rate` — reference FX/rate endpoints (where applicable)
- `GET /api/health` — service health + signer address

### 6.2 JavaScript SDK

`@uwu/sdk` packages typed helpers for:

- Oracle HTTP calls
- Escrow interactions (ethers v6)
- Hashing/formatting utilities

**Packaging guidance:** treat REST as the canonical contract; keep the SDK as a thin, typed client.

---

## 7. Roadmap (indicative)

- **Phase 1:** testnet demo (escrow + signer + UI)
- **Phase 2:** production lifecycle (disputes, timeouts, risk scoring)
- **Phase 3:** Account Aggregator integrations (Setu / Finvu / others)
- **Phase 4:** trust reduction (multi-signer, monitoring, public logs)
- **Phase 5:** developer platform (SDK polish, partner integrations)

---

## 8. Compliance posture (non-advice)

uWu aims to integrate **regulated, consent-based** data rails for verification (AA) and avoid INR custody. Deployments should seek appropriate legal review for their jurisdiction and product shape.

---

## 9. Contact / updates

- Developer docs: `/docs`
- Waitlist: `/waitlist`
- Community: `/community`

---

*This document is informational and may change without notice. Version: v0.1 — March 2026.*