eyesos

// developers

A small SDK over swappable adapters: pool, prover, verifier and relayer. Mock and production implementations share the same interfaces.

What's real today

We label mocks explicitly. Don't ship user funds on anything marked mock or planned.

  • Vault / alpha / risk circuits

    Mock prover for now

    Planned

  • Shielded custody layer

    Not built yet — holdings are not actually sealed yet

    Planned

  • Vault performance data

    Seeded simulation, labeled as simulated in the UI

    Mock

  • Wallet connection (wagmi / viem)

    MetaMask & injected wallets; WalletConnect with a project ID

    Production

  • Withdrawal / receipt / credential circuits

    Mock prover only. Needs Poseidon tree + audited circuits

    Planned

  • On-chain pool adapter

    UI uses MockPoolAdapter (browser state)

    Planned

  • Relayer network

    Mock API routes

    Mock

  • Payment links

    URL-encoded; production should sign links

    Mock

SDK

import { createEyesosClient } from "@/sdk";

const eyesos = createEyesosClient({ appUrl: "https://app.example" });
eyesos.isDemo; // true until real provers + on-chain adapter are configured

// Private payments
await eyesos.sendPrivatePayment({
  token: "USDC",
  amount: 250,
  recipient: "0x1234…",
  relayerId: "r-kestrel",       // or pick from GET /api/relayers
  mode: "strong",               // "standard" | "strong" | "maximum"
  invoice: { id: "INV-0142", merchant: "Acme Studio" },
});

// Payment links
const { url } = eyesos.createPaymentLink({
  handle: "alice", address: "0xabc…", token: "USDC",
  amount: 100, expiresInMs: 7 * 86_400_000, oneTime: true,
});

// Receipts
const { url: proofUrl } = await eyesos.generatePaymentProof(statement, { receiptSecret });
const result = await eyesos.verifyPaymentProof(proofUrl.split("/proof/")[1]);
// → { valid: true, sound: false }  // sound=false means mock verifier

// Private credentials
await eyesos.generateCredentialProof({
  kind: "credential",
  scope: "forum.example.org",
  claims: [{ id: "payments", threshold: 10, label: "10+ private payments" }],
});

Adapter interfaces

interface PoolAdapter {
  readonly isDemo: boolean;
  deposit(token: TokenSymbol, amount: number): Promise<Note[]>;
  send(req: SendRequest): Promise<SendResult>;
  withdraw(noteIds: string[], recipient: Address, relayerId: string): Promise<PoolActivity>;
}

interface WithdrawalProver {
  readonly isProduction: boolean;
  proveWithdrawal(witness: WithdrawalWitness, inputs: WithdrawalPublicInputs): Promise<Hex>;
}

interface StatementProver {
  readonly isProduction: boolean;
  prove(statement: Statement, witness: Record<string, unknown>): Promise<ProofEnvelope>;
}

interface StatementVerifier {
  verify(envelope: ProofEnvelope): Promise<{ valid: boolean; sound: boolean; reason?: string }>;
}

Relayer API

GET  /api/relayers         → { relayers: Relayer[] }          (mock)
POST /api/relay/quote      { relayerId, token, amount }
                           → { relayerFee, protocolFee, gasUnits, expiresAt }
POST /api/relay/submit     { relayerId, token, amount, proof, publicInputs }
                           → { reference, status, preview: true }  (never touches a chain)