{"_id":"@prxvt/sdk","_rev":"3-278356ae5b7679b9925840ff75bb6f61","name":"@prxvt/sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@prxvt/sdk","version":"1.0.0","keywords":["privacy","px402","x402","zero-knowledge","payments","zkp","usdc"],"author":{"name":"prxvt"},"license":"MIT","_id":"@prxvt/sdk@1.0.0","maintainers":[{"name":"prxvt","email":"contact@prxvt.com"}],"homepage":"https://github.com/prxvt/sdk#readme","bugs":{"url":"https://github.com/prxvt/sdk/issues"},"dist":{"shasum":"6c5a3194a92dbdc8a0fccb51e5e4e1608cdceffc","tarball":"https://registry.npmjs.org/@prxvt/sdk/-/sdk-1.0.0.tgz","fileCount":33,"integrity":"sha512-Y3ava1S4X0hVpk4hZ44V27mefRm7Z50MCNsSiRxtdC/2/eGZh1lG5KTthhhhF8fby+Elk/xuXX2W2RIq7MQlLQ==","signatures":[{"sig":"MEYCIQDOoZvEOO7EQUKlSg7LMXY+dZEXoWy58big4kekQ/QhugIhANzixhVNJj2frZVaD2srSEQH6v6iAJLDMjdFwe1gbiTe","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":138011},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"ac866c1d7e38ff24f55252721574f37c441c8b84","scripts":{"dev":"tsc --watch","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"prxvt","email":"contact@prxvt.com"},"repository":{"url":"git+https://github.com/prxvt/sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"px402 - Private x402 payments using zero-knowledge proofs. Pay for APIs privately without revealing your identity.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"graphql":"^16.12.0","snarkjs":"^0.7.0","graphql-request":"^7.3.4"},"_hasShrinkwrap":false,"devDependencies":{"viem":"^2.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"peerDependencies":{"viem":"^2.0.0"},"optionalDependencies":{"circomlibjs":"^0.1.7"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1764102964713_0.42234751889214817","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@prxvt/sdk","version":"1.0.1","keywords":["privacy","px402","x402","zero-knowledge","payments","zkp","usdc"],"author":{"name":"prxvt"},"license":"MIT","_id":"@prxvt/sdk@1.0.1","maintainers":[{"name":"prxvt","email":"contact@prxvt.com"}],"homepage":"https://github.com/prxvt/sdk#readme","bugs":{"url":"https://github.com/prxvt/sdk/issues"},"dist":{"shasum":"6e7df0d816eb83e36cc568ea1d7e547dca3f00a7","tarball":"https://registry.npmjs.org/@prxvt/sdk/-/sdk-1.0.1.tgz","fileCount":33,"integrity":"sha512-JHJd0Ei7oRWjNL8s6T3XbVt6OCkwcy1y3JlLdDBNbVfuQ5hKkMTLqnD8+zIcVs8SW12toHJ86l9StWgdAFNLCQ==","signatures":[{"sig":"MEUCIGTG3678/8O/pwjLiM/0NClNg1U+XJtaPej/8N6xBsZvAiEAzbJIyJ4DBhIe6QfLsI1LPTfxJYWIPJU4tU7CnNeFcjQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":138060},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"ac866c1d7e38ff24f55252721574f37c441c8b84","scripts":{"dev":"tsc --watch","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"prxvt","email":"contact@prxvt.com"},"repository":{"url":"git+https://github.com/prxvt/sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"px402 - Private x402 payments using zero-knowledge proofs. Pay for APIs privately without revealing your identity.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"graphql":"^16.12.0","snarkjs":"^0.7.0","graphql-request":"^7.3.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"viem":"^2.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"peerDependencies":{"viem":"^2.0.0"},"optionalDependencies":{"circomlibjs":"^0.1.7"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.1_1764103259297_0.28553548681414087","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@prxvt/sdk","version":"1.0.2","publishConfig":{"access":"public"},"description":"px402 - Private x402 payments using zero-knowledge proofs. Pay for APIs privately without revealing your identity.","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"npm run build"},"keywords":["privacy","px402","x402","zero-knowledge","payments","zkp","usdc"],"author":{"name":"prxvt"},"license":"MIT","peerDependencies":{"viem":"^2.0.0"},"dependencies":{"graphql":"^16.12.0","graphql-request":"^7.3.4","snarkjs":"^0.7.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0","viem":"^2.0.0"},"optionalDependencies":{"circomlibjs":"^0.1.7"},"repository":{"type":"git","url":"git+https://github.com/prxvt/sdk.git"},"bugs":{"url":"https://github.com/prxvt/sdk/issues"},"homepage":"https://github.com/prxvt/sdk#readme","gitHead":"ac866c1d7e38ff24f55252721574f37c441c8b84","_id":"@prxvt/sdk@1.0.2","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-m6EI4Yz5e7XBMRn4oUt87L7MD9R41E/8jaUofR/Z6oxvY9Yd1W+N2vGDDl9jxoYjHQ93IOVvRPuKbi5Ie/jVJw==","shasum":"5c2ef8b9494663b5509be29a17b9e544e38d9163","tarball":"https://registry.npmjs.org/@prxvt/sdk/-/sdk-1.0.2.tgz","fileCount":33,"unpackedSize":138971,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDopwJimmRGMFTd/8/i3IiIjW3KRX9vcouczvHE4MejwAiEA9e8dyaRIaCBLMB/KURMWV5cJzivRp2Ezd0pLvvR07SA="}]},"_npmUser":{"name":"prxvt","email":"contact@prxvt.com"},"directories":{},"maintainers":[{"name":"prxvt","email":"contact@prxvt.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.2_1764106982595_0.7183818082900224"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-25T20:36:04.593Z","modified":"2025-11-25T21:43:02.997Z","1.0.0":"2025-11-25T20:36:04.898Z","1.0.1":"2025-11-25T20:40:59.496Z","1.0.2":"2025-11-25T21:43:02.798Z"},"bugs":{"url":"https://github.com/prxvt/sdk/issues"},"author":{"name":"prxvt"},"license":"MIT","homepage":"https://github.com/prxvt/sdk#readme","keywords":["privacy","px402","x402","zero-knowledge","payments","zkp","usdc"],"repository":{"type":"git","url":"git+https://github.com/prxvt/sdk.git"},"description":"px402 - Private x402 payments using zero-knowledge proofs. Pay for APIs privately without revealing your identity.","maintainers":[{"name":"prxvt","email":"contact@prxvt.com"}],"readme":"# @prxvt/sdk\n\n**px402** - Private x402 payments using zero-knowledge proofs. Pay privately without revealing your identity or transaction history.\n\n[![npm version](https://badge.fury.io/js/@prxvt%2Fsdk.svg)](https://www.npmjs.com/package/@prxvt/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- **Full Privacy**: Each payment uses a fresh burner wallet, unlinkable to previous payments\n- **x402 Compatible**: Works seamlessly with any x402-enabled API\n- **Cross-Chain**: Deposit on one chain, spend on another (Base <-> Polygon)\n- **ZK Proofs**: All transactions validated with Groth16 zero-knowledge proofs\n- **Note Encryption**: AES-256-GCM encryption for secure note storage\n\n## Installation\n\n```bash\nnpm install @prxvt/sdk\n```\n\n## Quick Start\n\n### 1. Initialize SDK\n\n```typescript\nimport { PrivacySDK } from '@prxvt/sdk';\n\nconst sdk = new PrivacySDK({\n  chain: 'base', // or 'polygon'\n});\n```\n\n### 2. Deposit USDC -> Get Private Note\n\n```typescript\n// Deposit 10 USDC -> Get private note\nconst note = await sdk.deposit(10, '0xYourPrivateKey');\n\n// The note is your private balance - save it securely!\nconsole.log('Note created:', JSON.stringify(note));\n```\n\n### 3. Make Private px402 Payments\n\n```typescript\n// Load your note\nsdk.setNote(note);\n\n// Wrap fetch with privacy\nconst privateFetch = sdk.wrapFetch(fetch);\n\n// Make px402 payment - COMPLETELY PRIVATE!\nconst response = await privateFetch('https://api.example.com/x402/endpoint', {\n  method: 'POST',\n  body: JSON.stringify({ message: 'Hello!' }),\n});\n\n// Get updated note (old note is spent, this is the change!)\nconst updatedNote = sdk.getUpdatedNote();\n```\n\n### 4. Encrypt Notes for Storage\n\n```typescript\nimport { encryptNote, decryptNote } from '@prxvt/sdk';\n\n// Encrypt note with password\nconst encrypted = await encryptNote(note, 'my-secret-password');\nlocalStorage.setItem('encrypted-note', encrypted);\n\n// Later: decrypt to use\nconst decrypted = await decryptNote(encrypted, 'my-secret-password');\n```\n\n## Complete Example\n\n```typescript\nimport {\n  PrivacySDK,\n  encryptNote,\n  decryptNote,\n  getNoteBalance,\n  logger\n} from '@prxvt/sdk';\n\nasync function main() {\n  // Enable debug logging (optional)\n  logger.setLevel('debug');\n\n  // 1. Setup SDK\n  const sdk = new PrivacySDK({ chain: 'base' });\n\n  // 2. Deposit USDC\n  const note = await sdk.deposit(10, '0xYourPrivateKey');\n  console.log('Deposited:', getNoteBalance(note), 'USDC');\n\n  // 3. Encrypt and save\n  const encrypted = await encryptNote(note, 'password123');\n  localStorage.setItem('note', encrypted);\n\n  // 4. Make payments\n  sdk.setNote(note);\n  const privateFetch = sdk.wrapFetch(fetch);\n\n  const response = await privateFetch('https://api.example.com/x402');\n  console.log('Payment successful!');\n\n  // 5. Save updated note\n  const updated = sdk.getUpdatedNote();\n  const newEncrypted = await encryptNote(updated, 'password123');\n  localStorage.setItem('note', newEncrypted);\n\n  console.log('Remaining:', getNoteBalance(updated), 'USDC');\n}\n```\n\n## API Reference\n\n### PrivacySDK\n\nThe main SDK class for privacy payments.\n\n#### Constructor\n\n```typescript\nnew PrivacySDK(config: PrivacySDKConfig)\n```\n\n**Config Options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `chain` | `'base' \\| 'polygon'` | `'base'` | Blockchain to use |\n| `bundlerUrl` | `string` | prxvt proxy | Custom bundler URL |\n| `bundlerApiKey` | `string` | - | Pimlico API key (optional) |\n| `rpcUrl` | `string` | public RPC | Custom RPC URL |\n\n#### Methods\n\n##### `deposit(amount: number, privateKey: string): Promise<Note>`\n\nDeposit USDC to create a private note.\n\n```typescript\nconst note = await sdk.deposit(50, '0xYourPrivateKey');\n```\n\n##### `depositFast(amount: number, privateKey: string): Promise<Note>`\n\nFast deposit using ERC-3009 `transferWithAuthorization` (gasless).\n\n```typescript\nconst note = await sdk.depositFast(50, '0xYourPrivateKey');\n```\n\n##### `makePayment(note: Note, recipient: string, amount: number): Promise<PaymentResult>`\n\nMake a direct payment to a recipient.\n\n```typescript\nconst result = await sdk.makePayment(note, '0x742d35Cc...', 1.5);\nconsole.log('TX:', result.txHash);\nconsole.log('Change note:', result.note);\n```\n\n##### `wrapFetch(fetch: typeof fetch): typeof fetch`\n\nWrap fetch to automatically handle x402 payments.\n\n```typescript\nconst privateFetch = sdk.wrapFetch(fetch);\nconst response = await privateFetch('https://api.example.com/x402');\n```\n\n##### `setNote(note: Note): void`\n\nLoad a saved note into the SDK.\n\n```typescript\nsdk.setNote(savedNote);\n```\n\n##### `getUpdatedNote(): Note | undefined`\n\nGet the current note state after payments.\n\n```typescript\nconst updatedNote = sdk.getUpdatedNote();\n```\n\n### Encryption Functions\n\n##### `encryptNote(note: Note, password: string): Promise<string>`\n\nEncrypt a note with AES-256-GCM.\n\n```typescript\nconst encrypted = await encryptNote(note, 'my-password');\n// encrypted is a base64 string safe for storage\n```\n\n##### `decryptNote(encrypted: string, password: string): Promise<Note>`\n\nDecrypt an encrypted note.\n\n```typescript\nconst note = await decryptNote(encrypted, 'my-password');\n```\n\n##### `isEncryptedNote(str: string): boolean`\n\nCheck if a string is an encrypted note.\n\n```typescript\nif (isEncryptedNote(stored)) {\n  const note = await decryptNote(stored, password);\n}\n```\n\n### Helper Functions\n\n##### `getNoteBalance(note: Note): number`\n\nGet balance from a note in USDC.\n\n```typescript\nconst balance = getNoteBalance(note); // e.g., 10.5\n```\n\n##### `hasEnoughBalance(note: Note, amount: number): boolean`\n\nCheck if note has sufficient balance.\n\n```typescript\nif (!hasEnoughBalance(note, 5)) {\n  console.log('Insufficient balance');\n}\n```\n\n##### `formatUSDCAmount(microUsdc: number): string`\n\nFormat micro USDC to display string.\n\n```typescript\nformatUSDCAmount(1500000); // \"1.50\"\n```\n\n##### `parseUSDCAmount(usdc: number): number`\n\nParse USDC to micro USDC.\n\n```typescript\nparseUSDCAmount(1.5); // 1500000\n```\n\n### Cross-Chain Functions\n\n##### `isCrossChain(depositChain: string, paymentChain: string): boolean`\n\nCheck if payment is cross-chain.\n\n```typescript\nisCrossChain('base', 'polygon'); // true\nisCrossChain('base', 'base');    // false\n```\n\n##### `getChainEid(chain: string): number`\n\nGet LayerZero endpoint ID for a chain.\n\n```typescript\ngetChainEid('base');    // 30184\ngetChainEid('polygon'); // 30109\n```\n\n### Logger\n\n##### `logger.setLevel(level: LogLevel): void`\n\nConfigure logging level.\n\n```typescript\nimport { logger } from '@prxvt/sdk';\n\nlogger.setLevel('debug'); // 'none' | 'error' | 'warn' | 'info' | 'debug'\n```\n\n### Error Types\n\n```typescript\nimport {\n  PrivacySDKError,\n  InsufficientBalanceError,\n  InvalidNoteError,\n  DecryptionError,\n  MerkleProofError,\n  ProofGenerationError,\n  BundlerError,\n  NetworkError,\n  PaymentRequiredError,\n  TransactionError,\n  NullifierSpentError,\n} from '@prxvt/sdk';\n```\n\n## Types\n\n### Note\n\n```typescript\ninterface Note {\n  version: string;\n  commitments: NoteCommitment[];\n}\n\ninterface NoteCommitment {\n  secret: string;      // Random secret (field element)\n  nullifier: string;   // Random nullifier (field element)\n  amount: number;      // Amount in micro USDC (6 decimals)\n  depositChain: string; // Chain where commitment was created\n}\n```\n\n### PaymentResult\n\n```typescript\ninterface PaymentResult {\n  note: Note;              // Updated note with change\n  txHash: string;          // Transaction hash\n  nullifierHash: string;   // Nullifier hash (for tracking)\n  burnerAddress?: string;  // Burner wallet address\n  burnerPrivateKey?: string; // Burner private key (for x402)\n}\n```\n\n### PrivacySDKConfig\n\n```typescript\ninterface PrivacySDKConfig {\n  chain?: 'base' | 'polygon';\n  bundlerUrl?: string;\n  bundlerApiKey?: string;\n  rpcUrl?: string;\n  attestorUrl?: string;\n  circuitWasmPath?: string;\n  circuitZkeyPath?: string;\n}\n```\n\n## How It Works\n\n### Privacy Payment Flow\n\n1. **Generate Burner Wallet**: SDK creates ephemeral EOA\n2. **ZK Proof Generation**: Proves you have a valid note without revealing it\n3. **Withdraw to Burner**: UserOperation withdraws USDC to burner (paymaster sponsors gas!)\n4. **Sign x402 Payment**: Burner signs EIP-3009 authorization (no gas needed!)\n5. **Make API Call**: Payment is sent to merchant\n6. **Create Change Note**: Remaining balance becomes a new note\n7. **Discard Burner**: Burner wallet is thrown away\n\n**Result**: Completely private payment, no gas fees, untraceable!\n\n### Cross-Chain Payments\n\nDeposit on Base, pay on Polygon (or vice versa):\n\n```typescript\n// Deposit on Base\nconst sdk = new PrivacySDK({ chain: 'base' });\nconst note = await sdk.deposit(10, privateKey);\n\n// Pay on Polygon\nconst polygonSdk = new PrivacySDK({ chain: 'polygon' });\npolygonSdk.setNote(note); // Note from Base works on Polygon!\nconst result = await polygonSdk.makePayment(note, recipient, 1);\n```\n\nCross-chain payments use an attestor service that verifies the nullifier hasn't been spent on the origin chain.\n\n## Browser Usage\n\nFor browser environments, load Poseidon hash and snarkjs:\n\n```html\n<script src=\"https://cdn.prxvt.io/poseidon-browser.js\"></script>\n<script src=\"https://cdn.jsdelivr.net/npm/snarkjs@0.7.0/build/snarkjs.min.js\"></script>\n<script type=\"module\">\n  import { PrivacySDK } from '@prxvt/sdk';\n\n  const sdk = new PrivacySDK({ chain: 'base' });\n  // ... use SDK\n</script>\n```\n\n## Node.js Usage\n\nFor Node.js, install circomlibjs:\n\n```bash\nnpm install circomlibjs snarkjs\n```\n\n```typescript\nimport { PrivacySDK } from '@prxvt/sdk';\nimport { buildPoseidon } from 'circomlibjs';\nimport * as snarkjs from 'snarkjs';\n\n// Setup global Poseidon (required for Node.js)\nconst poseidon = await buildPoseidon();\nglobalThis.window = {\n  poseidonHash3: (a, b, c) => Promise.resolve(\n    poseidon.F.toString(poseidon([BigInt(a), BigInt(b), BigInt(c)]))\n  ),\n  poseidonHash2: (a, b) => Promise.resolve(\n    poseidon.F.toString(poseidon([BigInt(a), BigInt(b)]))\n  ),\n  poseidonHash: (a) => Promise.resolve(\n    poseidon.F.toString(poseidon([BigInt(a)]))\n  ),\n  snarkjs,\n};\n\nconst sdk = new PrivacySDK({ chain: 'base' });\n```\n\n## Important Notes\n\n### Note Management\n\n- **Notes are spent after each payment**: You CANNOT reuse the same note\n- **Always save the updated note**: After each payment, get and save the new note\n- **UTXO model**: Each payment consumes the old commitment and creates a new change commitment\n\n### Privacy Guarantees\n\n- **Unlinkable payments**: Each payment uses a fresh burner wallet\n- **No transaction history**: Payments cannot be linked together\n- **Zero-knowledge proofs**: Your identity and note are never revealed\n- **Cross-chain privacy**: Deposit and withdraw on different chains\n\n### Security\n\n- **Never share your note data**: Notes contain secrets that prove ownership\n- **Use note encryption**: Always encrypt notes before storage\n- **HTTPS only**: Always use HTTPS for API calls\n- **Trusted RPCs**: Use trusted RPC providers\n\n## Supported Chains\n\n| Chain | Network | USDC Contract | LayerZero EID |\n|-------|---------|---------------|---------------|\n| Base | Mainnet | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | 30184 |\n| Polygon | Mainnet | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | 30109 |\n\n## License\n\nMIT\n\n## Links\n\n- **GitHub**: [github.com/prxvt/sdk](https://github.com/prxvt/sdk)\n- **npm**: [npmjs.com/package/@prxvt/sdk](https://www.npmjs.com/package/@prxvt/sdk)\n- **Issues**: [Report bugs](https://github.com/prxvt/sdk/issues)\n","readmeFilename":"README.md"}