Documentation

Everything you need to integrate uWu attestations into your dApp.

#What is uWu?

uWu is a protocol that bridges traditional fiat payment rails (like UPI, IMPS, NEFT) with blockchain smart contracts through cryptographic attestations.

When someone makes an off-chain INR payment, our oracle network verifies the bank transfer and signs a cryptographic proof that any smart contract can verify independently.

This enables trustless P2P trading, fiat on-ramps, and any use case where you need on-chain proof that real-world money moved—without custody or screenshots.

#Quick Start (JavaScript)

Install the SDK and start verifying payments in minutes.

terminal
npm install @uwu/sdk ethers
app.ts
import { UwuClient, CHAIN_CONFIGS } from '@uwu/sdk'
import { Wallet } from 'ethers'

// Initialize client
const signer = new Wallet(process.env.PRIVATE_KEY!)
const client = new UwuClient(CHAIN_CONFIGS[97], signer)

// Maker: Create a trade (locks PC in escrow)
const { tradeId } = await client.createAndWaitForTrade({
  taker: "0xBuyer...",
  pcAmount: ethers.parseEther("100"),  // 100 PC
  inrAmount: 845000000n,               // ₹84,500 in paisa
  payeeVpa: "maker@upi",
  durationSeconds: 3600
})

// Taker: After paying INR off-chain, prove and release
const result = await client.proveAndRelease(tradeId, {
  payerVpa: "taker@upi",
  payeeVpa: "maker@upi",
  utrNumber: "412345678901",
  rail: "UPI"
})

console.log("Released!", result.releaseTxHash)

#Quick Start (Solidity)

Any smart contract can verify uWu attestations without using UwuEscrow.

MyCheckout.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@uwu/contracts/lib/UwuAttestationLib.sol";

contract MyCheckout {
    using UwuAttestationLib for UwuAttestationLib.Attestation;

    mapping(address => bool) public authorizedOracles;
    mapping(bytes32 => bool) public processedPayments;

    function processPayment(
        UwuAttestationLib.Attestation calldata att,
        bytes calldata signature
    ) external {
        bytes32 attHash = att.hash();
        
        require(!processedPayments[attHash], "Already processed");
        require(block.timestamp <= att.expiresAt, "Expired");
        require(att.riskScore < 70, "Risk too high");

        address signer = att.recoverSigner(signature);
        require(authorizedOracles[signer], "Invalid oracle");

        processedPayments[attHash] = true;

        // Your custom logic: mint NFT, credit balance, etc.
        _onPaymentVerified(msg.sender, att.inrAmount);
    }
}

#Oracle API Reference

HTTP endpoints for requesting and retrieving attestations.

EndpointMethodDescription
/api/attestPOSTRequest attestation for a payment
/api/attestation/:hashGETRetrieve attestation by hash
/api/rateGETGet current INR/USD exchange rate
/api/healthGETCheck oracle status and address
/api/oracle/statsGETOracle metrics — uptime, success rate, avg latency
/api/verification/consentPOSTInitiate Setu AA consent, returns consentId + redirectUrl
/api/setu/callbackPOSTSetu notification webhook (configure in Setu console)

POST /api/attest

Request Body
{
  "tradeId": "0x...",
  "inrAmount": 8450000,
  "usdAmount": 100000000,
  "payerVpa": "buyer@upi",
  "payeeVpa": "seller@upi",
  "utrNumber": "412345678901",
  "rail": "UPI",
  "chainId": 97
}
Response
{
  "attestation": {
    "tradeId": "0x...",
    "inrAmount": 8450000,
    "payerHash": "0x...",
    "payeeHash": "0x...",
    "timestamp": 1709740800,
    "expiresAt": 1709741400,
    "evidenceHash": "0x...",
    "riskScore": 12
  },
  "signature": "0x...",
  "attestationHash": "0x...",
  "riskScore": 12
}

GET /api/rate

Response
{
  "inrPerUsd": 84.52,
  "updatedAt": 1709740800
}

GET /api/health

Response
{
  "status": "healthy",
  "oracleAddress": "0x..."
}

#Setu AA Verification Flow

When VERIFICATION_MODE=setu, the oracle uses Setu Account Aggregator to cryptographically verify that an INR credit appeared in the seller's bank account. uWu never holds fiat — the QR routes money directly to the seller's UPI VPA.

verification-flow.txt
1. Seller creates trade + enters UPI VPA
   → Escrow locks crypto on Push Chain

2. QR generated: upi://pay?pa={sellerVpa}&am={inrAmount}&tn={tradeId}
   → Seller shares QR with buyer

3. Buyer scans QR → pays via any UPI app (GPay, PhonePe, BHIM...)
   → INR goes directly to seller's bank account (uWu never touches fiat)

4. Oracle creates Setu AA consent → buyer approves in Setu popup
   → Setu fetches DEPOSIT transactions from buyer's bank (FIP)

5. Oracle matches CREDIT by amount ± 1% + UTR number
   → Signs attestation with Ed25519 key

6. Frontend submits attestation → contract verifies oracle signature
   → Escrow auto-releases crypto to buyer
Action required: In Setu console → Step 1 → change FI type from Exchange Traded Funds to DEPOSIT. Set redirect URL to /trade/[tradeId] and callback URL to {oracle-url}/api/setu/callback.

#TDS Compliance (Section 194S)

Every uWu attestation is an auditable on-chain record. The Tax dashboard auto-calculates your Section 194S liability and exports Form 26QE-compatible CSV.

TDS Rule
Section: 194S
Rate:    1% of INR amount
Trigger: per-transaction > ₹10,000
FY:      April–March (India)

Example:
  Trade: ₹50,000
  TDS:   ₹500 (1%)

  Trade: ₹8,000
  TDS:   ₹0 (below threshold)
GET /api/tds
# JSON summary
GET /api/tds?wallet=0x...

# CSV export (Form 26QE-compatible)
GET /api/tds?wallet=0x...&format=csv

Response:
{
  "fy": "2025-26",
  "tradeCount": 12,
  "totalInrRupees": "84000.00",
  "totalTdsRupees": "840.00",
  "section": "194S"
}

#SDK vs REST API

REST API is the stable contract: routes like POST /api/attest should stay versioned and documented for any language.

npm package @uwu/sdk is a typed, ergonomic wrapper for TypeScript/JavaScript (oracle + escrow helpers). For Python, Go, or mobile clients, call the REST API directly or generate a client from an OpenAPI spec later.

#Resources