@logia/sdk - Privacy Layer for X402 Payments & Transfers

A zero-knowledge privacy layer built on top of X402, enabling private, gasless, and flexible crypto payments and transfers.

Logia allows users and agents to interact with Web2 and Web3 apps without revealing wallet addresses or transaction history, while remaining fully compatible with the HTTP 402 payment protocol.

✨ Features

• Privacy Accounts – Private balances represented as notes, unlinkable to your wallet
• Private Payments – Send crypto to merchants or apps without revealing your identity
• x402 Integration – Fulfill HTTP 402 payment requests privately
• Zero-Knowledge Proofs – Groth16 SNARKs prove note ownership and valid payments
• Flexible Payments – Deposit once, spend any amount, and keep change in new notes
• Gasless Transactions – ERC-4337 paymaster sponsors operations automatically
• UTXO-Style Model – Multiple payments can be made from a single deposit

🏗️ Architecture Overview

User / Agent
    ↓
Logia Pool (private notes & commitments)
    ↓
Merkle Tree (off-chain, large anonymity set)
    ↓
Generate ZK proof → UserOp → EntryPoint
    ↓
ZKPaymaster verifies proof → Pool sponsors payment
    ↓
Recipient receives crypto; remaining balance stored in new note

Key principles:

• Proof generation is client-side – no backend servers store sensitive data
• Supports Web2 and Web3 applications using x402 payments
• Privacy grows with more users, deposits, and transactions

📦 Installation

Prerequisites

• Node.js v18+
• Circom (optional, for advanced ZK circuit compilation)
• Foundry (optional, for contract deployment)

Clone and Install

git clone <repo-url>
cd logia-sdk
npm install

🚀 Quick Start

1. Initialize SDK

import { LogiaSDK } from "@logia/sdk";

const sdk = new LogiaSDK({
  poolAddress: "0x...", // Logia Pool contract
  paymasterAddress: "0x...", // ZKPaymaster contract
  tokenAddress: "0x...", // ERC-20 token or USDC
  rpcUrl: "https://sepolia.base.org",
  zkeyPath: "./build/circuit_final.zkey",
  wasmPath: "./build/circuit_js/circuit.wasm",
  chainId: 84532, // Base Sepolia
});

await sdk.init();

2. Deposit Funds

// Deposit 5 tokens into the privacy pool
const note = await sdk.createNote("USDC", 5);

// Backup secret and note ID
console.log("Secret:", note.secret);
console.log("Commitment:", note.commitment);

// Check balance
console.log("Balance:", sdk.getBalance());

3. Make Private Payment

const recipient = "0x1234...";
const proof = await sdk.generateProof(note, recipient, 2.5); // Pay 2.5 tokens

// Send transaction
const tx = await sdk.sendPrivate({
  note,
  to: recipient,
  amount: 2.5,
});

console.log("Transaction hash:", tx.hash);

4. Backup & Restore Notes

// Export notes for backup
const backup = sdk.exportNotes();
localStorage.setItem("logia_backup", backup);

// Restore on a new device
sdk.importNotes(localStorage.getItem("logia_backup"));
console.log("Restored balance:", sdk.getBalance());

📚 API Reference

Method	Description
init()	Initialize SDK, load ZK circuits and Merkle tree
createNote(asset: string, amount: number)	Create a private balance note in the Logia pool
generateProof(note, recipient, amount)	Generate a zero-knowledge proof for a payment
sendPrivate({note, to, amount})	Submit a private transaction
verifyProof(proof)	Verify a proof without revealing sender identity
getBalance()	Returns total balance across all notes
listNotes()	List all active private notes
exportNotes()	Export notes for backup
importNotes(json: string)	Restore notes from backup

💡 Use Cases

• Private Payments – Pay websites, APIs, or merchants without exposing wallet addresses
• Private Social Actions – Tips, rewards, or content unlocks without tracking
• Encrypted Reputation Systems – Verify achievements without exposing full history
• DAO Voting with Privacy – Vote anonymously in governance systems
• Agent-Based Private Workflows – Automate payments or tasks while keeping identity private

🗺️ Roadmap

Upcoming Features

• Multi-asset support (ERC-20s beyond USDC/ETH)
• Batch transactions and payments
• Stealth capsules for incoming private transfers
• Web2 app integrations
• Privacy analytics tools

🤝 Contributing

We welcome contributions in the following areas:

• SDK improvements
• Contract audits and optimizations
• Documentation and tutorials
• Community support

📞 Contact & Community

Connect with the Logia community:

• Twitter/X: @LogiaTerminal
• GitHub: github.com/Logiaterminal
• Website: logiaterminal.com

🔒 Security

⚠️ Status: Testnet Only – Do not use in production

Important notes:

• Trusted setup is single-party; secrets must be backed up
• Contracts and circuits are not audited
• Start with small deposits and test thoroughly

📄 License

MIT