Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Mobile Applications                          │
│  ┌──────────────────┐              ┌─────────────────────────┐  │
│  │   Wallet App     │              │    POS/Merchant App     │  │
│  │  (Kotlin/Compose)│              │   (Kotlin/Compose)      │  │
│  │  - Stealth addrs │              │   - Proposal creation   │  │
│  │  - ZK proof gen  │              │   - QR code display     │  │
│  │  - NFC passport  │              │   - Settlement monitor  │  │
│  └────────┬─────────┘              └──────────┬──────────────┘  │
└───────────┼────────────────────────────────────┼─────────────────┘
            │                                    │
            │  HTTPS + WebSocket                 │
            │                                    │
┌───────────▼────────────────────────────────────▼─────────────────┐
│                    Backend Services (Deno/Hono)                  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  REST API (/api/identipay/v1/*)                             │ │
│  │  - Proposals, Intents, Announcements, Names, Merchants      │ │
│  │  - Gas sponsorship, Transaction building                    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Event Indexers (Polling)                                   │ │
│  │  - Settlement events → Update proposal status               │ │
│  │  - Stealth announcements → Store for wallet scanning        │ │
│  └─────────────────────────────────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  PostgreSQL Database (Drizzle ORM)                          │ │
│  │  - Proposals, Merchants, Announcements, Names cache         │ │
│  └─────────────────────────────────────────────────────────────┘ │
└───────────┬──────────────────────────────────────────────────────┘
            │
            │  Sui RPC (JSON-RPC 2.0)
            │
┌───────────▼──────────────────────────────────────────────────────┐
│                    Sui Blockchain (Move)                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Core Protocol Modules                                      │ │
│  │  - settlement.move        (atomic commerce execution)       │ │
│  │  - shielded_pool.move     (privacy firewall)                │ │
│  │  - zk_verifier.move       (Groth16 proof verification)      │ │
│  │  - meta_address_registry  (name → public keys)              │ │
│  │  - trust_registry.move    (merchant DIDs)                   │ │
│  │  - announcements.move     (stealth address broadcast)       │ │
│  │  - receipt.move           (encrypted receipt NFTs)          │ │
│  │  - warranty.move          (encrypted warranty NFTs)         │ │
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│              Zero-Knowledge Circuits (Circom)                    │
│  - identity_registration.circom  (~700 constraints)              │
│  - age_check.circom              (~1.2K constraints)             │
│  - pool_spend.circom             (~35K constraints)              │
└──────────────────────────────────────────────────────────────────┘

entry fun execute_commerce<T>(
    state: &mut SettlementState,
    payment: &mut Coin<T>,
    amount: u64,
    merchant: address,
    buyer_stealth_addr: address,
    intent_sig: vector<u8>,
    intent_hash: vector<u8>,
    buyer_pubkey: vector<u8>,
    proposal_expiry: u64,
    zk_vk: &VerificationKey,
    zk_proof: vector<u8>,
    zk_public_inputs: vector<u8>,
    encrypted_payload: vector<u8>,
    // ... additional parameters
    ctx: &mut TxContext,
)

public struct ShieldedPool<phantom T> has key {
    id: UID,
    balance: Balance<T>,
    merkle_root: u256,  // Poseidon Merkle tree of note commitments
    nullifiers: Table<u256, bool>,  // Prevents double-spend
    next_leaf_index: u64,
    filled_subtrees: vector<u256>,  // Incremental Merkle tree state
    tree_depth: u8,  // Default: 20 (1M capacity)
}

entry fun deposit<T>(
    pool: &mut ShieldedPool<T>,
    coin: Coin<T>,
    note_commitment: u256,  // Poseidon(amount, owner_key, salt)
    _ctx: &mut TxContext,
)

entry fun withdraw<T>(
    pool: &mut ShieldedPool<T>,
    vk: &VerificationKey,
    proof: vector<u8>,
    public_inputs: vector<u8>,
    nullifier: u256,  // Prevents re-spending same note
    recipient: address,
    amount: u64,
    change_commitment: u256,  // If partial withdraw
    ctx: &mut TxContext,
)

public struct VerificationKey has key, store {
    id: UID,
    alpha_g1: vector<u8>,     // G1 point (compressed)
    beta_g2: vector<u8>,      // G2 point (compressed)
    gamma_g2: vector<u8>,     // G2 point (compressed)
    delta_g2: vector<u8>,     // G2 point (compressed)
    ic: vector<vector<u8>>,   // IC[i] G1 points for public inputs
}

public fun verify_proof(
    vk: &VerificationKey,
    proof: &vector<u8>,
    public_inputs: &vector<u8>,
): bool

public struct MetaAddressRegistry has key {
    id: UID,
    names: Table<String, MetaAddress>,          // name → pubkeys
    commitments: Table<vector<u8>, String>,     // identity commitment → name
}

public struct MetaAddress has store {
    spend_pubkey: vector<u8>,  // 32-byte Ed25519 public key
    view_pubkey: vector<u8>,   // 32-byte X25519 public key
    registered_at: u64,
}

public struct Merchant has store {
    did: String,              // did:identipay:{hostname}:{uuid}
    name: String,
    sui_address: address,
    public_key: vector<u8>,   // For ECDH encryption
    registered_at: u64,
    active: bool,
}

public struct StealthAnnouncement has copy, drop {
    ephemeral_pubkey: vector<u8>,  // 32-byte X25519 ephemeral key
    view_tag: u8,                  // First byte of shared secret (fast scan)
    stealth_address: address,       // Sui address of recipient
    metadata: vector<u8>,           // Encrypted transaction metadata
    timestamp: u64,
}

// From main.ts:125-161
async function pollSettlementEvents(): Promise<void> {
  let cursor = await loadCursor(SETTLEMENT_CURSOR_KEY);
  
  while (hasMore) {
    const result = await suiService.pollSettlementEvents(cursor);
    
    for (const event of result.events) {
      // Update proposal status to "settled"
      await db.update(proposals)
        .set({ status: "settled", suiTxDigest: event.txDigest })
        .where(eq(proposals.intentHash, event.intentHash));
      
      // Push WebSocket update to connected clients
      pushSettlementUpdate(txId, "settled", event.txDigest);
    }
    
    cursor = result.nextCursor;
    await saveCursor(SETTLEMENT_CURSOR_KEY, cursor);
  }
}

// POST /api/identipay/v1/transactions/sponsor-send
{
  "senderAddress": "0x...",  // User's stealth address
  "amount": "5000000",       // USDC micros
  "recipient": "0x...",      // Merchant's stealth address
  "coinType": "0x...::usdc::USDC",
  "ephemeralPubkey": [/* 32 bytes */],
  "viewTag": 42
}

// From PaymentRepository.kt:51-134
suspend fun sendToName(name: String, amountMicros: Long): SendResult {
    // 1. Resolve recipient meta-address
    val resolution = backendApi.resolveName(name)
    
    // 2. Derive fresh stealth address for recipient
    val stealth = stealthAddress.derive(
        recipientSpendPub, 
        recipientViewPub
    )
    
    // 3. Find source coin with sufficient balance
    var source = stealthAddressDao.getWithBalance()
        .firstOrNull { it.balanceUsdc >= amountMicros }
    
    // 4. If no single coin is large enough, use pool-on-merge
    if (source == null && totalBalance >= amountMicros) {
        // Deposit all coins → withdraw to fresh address
        poolOnMerge(sources, amountMicros)
    }
    
    // 5. Build and submit gas-sponsored PTB
    val txDigest = executeSendTransaction(
        senderAddress = source.stealthAddress,
        senderPrivKey = source.stealthPrivKeyEnc,
        recipientStealthAddress = stealth.stealthAddress,
        // ...
    )
    
    return SendResult.Success(txDigest)
}

template IdentityRegistration() {
    signal input issuerCertHash;   // SHA-256(issuer cert) mod BN254_PRIME
    signal input docNumberHash;    // SHA-256(doc number) mod BN254_PRIME
    signal input dobHash;          // SHA-256(YYMMDD) mod BN254_PRIME
    signal input userSalt;         // Random BN254 field element
    
    signal output identityCommitment;
    
    component hasher = Poseidon(4);
    hasher.inputs[0] <== issuerCertHash;
    hasher.inputs[1] <== docNumberHash;
    hasher.inputs[2] <== dobHash;
    hasher.inputs[3] <== userSalt;
    
    identityCommitment <== hasher.out;
}