{"_id":"@aperturerwa/sdk","_rev":"3-2f2292f9c75f63ac890031b56136726b","name":"@aperturerwa/sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@aperturerwa/sdk","version":"0.1.0","keywords":["solana","zk","groth16","circom","compliance","ai-agents","x402","mpp","aperture"],"license":"MIT","_id":"@aperturerwa/sdk@0.1.0","maintainers":[{"name":"aperturerwa","email":"w.aperture1@gmail.com"}],"homepage":"https://github.com/makinci/aperture#readme","bugs":{"url":"https://github.com/makinci/aperture/issues"},"dist":{"shasum":"55ebd8b9d418a216a339c30d0bae49954a95e179","tarball":"https://registry.npmjs.org/@aperturerwa/sdk/-/sdk-0.1.0.tgz","fileCount":87,"integrity":"sha512-yBDV87yavZM25j+wX4pkjRy/DrepM2ECAlvLsQXN4l9/DWjvAL6EaxtSuAiEJXsIRrLZzcyXYvEaesDpuIrJuA==","signatures":[{"sig":"MEUCICef1ajA7XIdBthtOlToT8elT6+WtbNFJajw6cBtJL4XAiEA/TQcpN/K2Jses1dfscff1bYNQLwAu6BkDzpCy73uVG8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":240463},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./anchor":{"types":"./dist/anchor/index.d.ts","import":"./dist/anchor/index.js"}},"gitHead":"39367370279d3af40c9a496946a733ba59389268","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:live":"vitest run --config vitest.config.live.ts","test:unit":"vitest run tests/unit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"aperturerwa","email":"w.aperture1@gmail.com"},"repository":{"url":"git+https://github.com/makinci/aperture.git","type":"git","directory":"sdk/aperture-sdk"},"_npmVersion":"11.12.1","description":"Aperture compliance SDK for AI agents on Solana. Generates Circom + Groth16 ZK proofs of policy compliance and submits them to Solana through the x402 and MPP payment protocols.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"bs58":"^6.0.0","@solana/web3.js":"^1.98.0","@solana/spl-token":"^0.4.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.4","typescript":"^5.7.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1779382654174_0.8795812017729601","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aperturerwa/sdk","version":"0.1.1","keywords":["solana","zk","groth16","circom","compliance","ai-agents","x402","mpp","aperture"],"license":"MIT","_id":"@aperturerwa/sdk@0.1.1","maintainers":[{"name":"aperturerwa","email":"w.aperture1@gmail.com"}],"homepage":"https://github.com/wienerlabs/aperture#readme","bugs":{"url":"https://github.com/wienerlabs/aperture/issues"},"dist":{"shasum":"13435bdacad464a4f34698450fe5830bfdd4ab07","tarball":"https://registry.npmjs.org/@aperturerwa/sdk/-/sdk-0.1.1.tgz","fileCount":87,"integrity":"sha512-KFAobmtbj8ER+D4ScB/LWA5sxrdOCEBUKbBHOOhQlI1WMbhNNBwxCYHb9SmmwK7D/BAkk6OFj6X1Gb/QIh8LYg==","signatures":[{"sig":"MEYCIQDT7PpCPs9Ihh0u2SMfmFBabiovq8202T5ag9wK7+kZ3wIhAOj+kUw3rQRK8WuCEuhK3WqAJ/eBOpUYt7jAf1PRBmMs","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":241228},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./anchor":{"types":"./dist/anchor/index.d.ts","import":"./dist/anchor/index.js"}},"gitHead":"39367370279d3af40c9a496946a733ba59389268","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:live":"vitest run --config vitest.config.live.ts","test:unit":"vitest run tests/unit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"aperturerwa","email":"w.aperture1@gmail.com"},"repository":{"url":"git+https://github.com/wienerlabs/aperture.git","type":"git","directory":"sdk/aperture-sdk"},"_npmVersion":"11.12.1","description":"Aperture compliance SDK for AI agents on Solana. Generates Circom + Groth16 ZK proofs of policy compliance and submits them to Solana through the x402 and MPP payment protocols.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"bs58":"^6.0.0","@solana/web3.js":"^1.98.0","@solana/spl-token":"^0.4.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.4","typescript":"^5.7.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1779384577604_0.49357832496445564","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@aperturerwa/sdk","version":"0.1.2","description":"Aperture compliance SDK for AI agents on Solana. Generates Circom + Groth16 ZK proofs of policy compliance and submits them to Solana through the x402 and MPP payment protocols.","license":"MIT","type":"module","repository":{"type":"git","url":"git+https://github.com/wienerlabs/aperture.git","directory":"sdk/aperture-sdk"},"bugs":{"url":"https://github.com/wienerlabs/aperture/issues"},"homepage":"https://github.com/wienerlabs/aperture#readme","engines":{"node":">=20.0.0"},"publishConfig":{"access":"public"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./anchor":{"types":"./dist/anchor/index.d.ts","import":"./dist/anchor/index.js"}},"keywords":["solana","zk","groth16","circom","compliance","ai-agents","x402","mpp","aperture"],"scripts":{"build":"tsc","lint":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:unit":"vitest run tests/unit","test:live":"vitest run --config vitest.config.live.ts","prepublishOnly":"npm run build"},"dependencies":{"@solana/spl-token":"^0.4.9","@solana/web3.js":"^1.98.0","bs58":"^6.0.0"},"devDependencies":{"@types/node":"^25.5.0","typescript":"^5.7.3","vitest":"^3.0.4"},"gitHead":"39367370279d3af40c9a496946a733ba59389268","_id":"@aperturerwa/sdk@0.1.2","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-sMI+5qRNs2iylcBFmAdjiQlreCRDgS00NOoCnhD9hPcvX/8VHCKi373CQNJ2mS4QUbH9nnYf2wxvq0gf5S1IUA==","shasum":"310eb8377d5c760b74cbe1b418d1628a9fe90d91","tarball":"https://registry.npmjs.org/@aperturerwa/sdk/-/sdk-0.1.2.tgz","fileCount":87,"unpackedSize":242432,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCs0+Z8nxMuUHE4c4JFAANNy7/bUmxWXrABClmEbYo/wAIgQb71cT5/+BDRmSw1baiOEQguryxuaMCuFQDZMKl5ZQk="}]},"_npmUser":{"name":"aperturerwa","email":"w.aperture1@gmail.com"},"directories":{},"maintainers":[{"name":"aperturerwa","email":"w.aperture1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.2_1779385640223_0.6958214566936236"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T16:57:33.980Z","modified":"2026-05-21T17:47:20.485Z","0.1.0":"2026-05-21T16:57:34.350Z","0.1.1":"2026-05-21T17:29:37.757Z","0.1.2":"2026-05-21T17:47:20.374Z"},"bugs":{"url":"https://github.com/wienerlabs/aperture/issues"},"license":"MIT","homepage":"https://github.com/wienerlabs/aperture#readme","keywords":["solana","zk","groth16","circom","compliance","ai-agents","x402","mpp","aperture"],"repository":{"type":"git","url":"git+https://github.com/wienerlabs/aperture.git","directory":"sdk/aperture-sdk"},"description":"Aperture compliance SDK for AI agents on Solana. Generates Circom + Groth16 ZK proofs of policy compliance and submits them to Solana through the x402 and MPP payment protocols.","maintainers":[{"name":"aperturerwa","email":"w.aperture1@gmail.com"}],"readme":"# @aperturerwa/sdk\n\nProduction-ready TypeScript SDK that lets any AI agent integrate with Aperture end-to-end, **without ever touching the dashboard**. One package gives you:\n\n- Operator + policy onboarding (initialize_operator + register_policy on Solana).\n- Policy CRUD against the policy-service.\n- Circom + Groth16 ZK proof generation via the prover-service.\n- Atomic on-chain verify + transfer for x402 payments.\n- Stripe off_session + on-chain Ed25519 attestation for MPP payments.\n- Automatic proof-record + Light Protocol compressed attestation submission.\n- Batch attestation rollups anchored on Solana.\n- Audit links the Aperture dashboard renders, plus Solana Explorer URLs.\n\n## Install\n\n```bash\nnpm install @aperturerwa/sdk @solana/web3.js @solana/spl-token\n```\n\n## Hosted backend\n\nThe SDK talks to three Aperture backend services. You can either point at the publicly hosted Wiener Labs cluster (recommended for quick start) or stand up your own copy via `docker compose up` from this repository.\n\n```ts\nconst APERTURE_HOSTED = {\n  policyServiceUrl: 'https://policy-server-production.up.railway.app',\n  proverServiceUrl: 'https://prover-service-production-e486.up.railway.app',\n  complianceApiUrl: 'https://compliance-api-production-21f4.up.railway.app',\n};\n```\n\nBoth options share the same Solana devnet program IDs, so policies anchored against the hosted stack are visible on Solana regardless of which deployment you use to view them.\n\n## 60-second tour\n\n```ts\nimport { ApertureClient } from '@aperturerwa/sdk';\nimport { Keypair } from '@solana/web3.js';\n\nconst client = new ApertureClient({\n  wallet: Keypair.fromSecretKey(/* your private key bytes */),\n  rpcUrl: 'https://api.devnet.solana.com',\n  policyServiceUrl: 'https://policy-server-production.up.railway.app',\n  proverServiceUrl: 'https://prover-service-production-e486.up.railway.app',\n  complianceApiUrl: 'https://compliance-api-production-21f4.up.railway.app',\n  // Optional. If you host your own Aperture dashboard (e.g. self-hosted\n  // Next.js app from this repo), pass its public URL so `client.audit.*`\n  // helpers produce shareable audit links. Omit to fall back to\n  // Solana Explorer transaction URLs only.\n  // dashboardUrl: 'https://your-aperture-dashboard.example.com',\n  // MPP only:\n  stripeSecretKey: process.env.STRIPE_SECRET_KEY,\n});\n\n// 1. Onboard a brand new operator + policy (single call, on-chain anchored).\nconst anchor = await client.createAndAnchorPolicy({\n  operator_id: client.operatorId,\n  name: 'my-agent-v1',\n  max_daily_spend: 50,\n  max_per_transaction: 5,\n  allowed_endpoint_categories: ['x402', 'mpp'],\n  token_whitelist: ['4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'],\n});\nconsole.log('policy anchored at', client.audit.explorerTx(anchor.txSignature));\n\n// 2. Pay an x402-protected endpoint with a ZK proof.\nconst policy = await client.loadActivePolicy();\nconst pay = await client.payX402(\n  'https://api.example.com/protected-report',\n  policy,\n);\nconsole.log('on-chain settlement:', client.audit.explorerTx(pay.txSignature));\n// pay.recording is non-null when compliance-api persisted the proof row.\nif (pay.recording) {\n  console.log('proof row id:', pay.recording.proofRowId);\n}\n\n// 3. Roll up a batch attestation across the period.\nconst batch = await client.createBatchAttestation({\n  periodStart: new Date(Date.now() - 60_000),\n  periodEnd: new Date(),\n});\nconsole.log('batch tx:', client.audit.explorerTx(batch.txSignature));\nconsole.log('batch attestation id:', batch.attestationId);\n```\n\n## Public API\n\n```ts\nimport {\n  // High-level entry point\n  ApertureClient,\n\n  // HTTP clients\n  PolicyClient,\n  ProverClient,\n  ComplianceClient,\n\n  // Flows\n  X402Flow,\n  MppFlow,\n  AttestationFlow,\n  OperatorAdmin,\n\n  // Helpers\n  Audit,\n  policyIdToBytes,\n\n  // On-chain primitives\n  buildVerifyPaymentProofV2WithTransferIx,\n  buildVerifyMppPaymentProofIx,\n  buildEd25519VerifyIx,\n  buildInitializeOperatorIx,\n  buildRegisterPolicyIx,\n  buildUpdatePolicyIx,\n  buildDeactivatePolicyIx,\n  buildVerifyBatchAttestationIx,\n  deriveOperatorPDA,\n  derivePolicyPDA,\n  deriveProofRecordPDA,\n  deriveComplianceStatusPDA,\n  deriveOperatorStatePDA,\n  deriveAttestationRecordPDA,\n  readOperatorState,\n  readEffectiveDailySpentLamports,\n} from '@aperturerwa/sdk';\n```\n\n## Lifecycle reference\n\n```text\n┌───────────────────────── onboarding (one-time) ─────────────────────────┐\n│ client.operator.initializeOperator()       initialize_operator ix       │\n│ client.policy.createPolicy({rules})        POST /api/v1/policies        │\n│ client.operator.anchorPolicy(id)           register_policy ix +         │\n│                                            PATCH /onchain-confirmation  │\n│   (or use the convenience createAndAnchorPolicy({rules}) to do all 3)   │\n└──────────────────────────────────────────────────────────────────────────┘\n                                  │\n                                  ▼\n┌──────────────────────────── runtime (per payment) ─────────────────────────┐\n│ const policy = await client.loadActivePolicy()                              │\n│ client.payX402(endpoint, policy)                                            │\n│   ├─ GET 402 challenge                                                      │\n│   ├─ read OperatorState.daily_spent                                         │\n│   ├─ prover-service POST /prove                Circom + Groth16             │\n│   ├─ verify_payment_proof_v2_with_transfer    (atomic verify + transfer)   │\n│   ├─ replay GET with proof header              (merchant unlocks resource) │\n│   ├─ POST /api/v1/proofs                       (compliance row recorded)    │\n│   └─ POST /compress-attestation                (Light Protocol, optional)   │\n│ client.payMpp(endpoint, policy)                                             │\n│   ├─ GET 402 challenge (Stripe PaymentIntent)                               │\n│   ├─ Stripe off_session confirm                                             │\n│   ├─ poll compliance-api for signed Poseidon receipt                        │\n│   ├─ prover-service POST /prove (stripe_receipt_hash bound)                 │\n│   └─ Ed25519 verify + verify_mpp_payment_proof (single tx)                 │\n└─────────────────────────────────────────────────────────────────────────────┘\n                                  │\n                                  ▼\n┌──────────────────────────── audit + attestation ────────────────────────────┐\n│ client.createBatchAttestation({periodStart, periodEnd})                     │\n│   ├─ POST /api/v1/attestations/batch                                        │\n│   └─ verify_batch_attestation ix on-chain                                   │\n│ client.audit.proofUrl(recording.proofRowId)                                 │\n│ client.audit.attestationUrl(batchResult.attestationId)                      │\n│ client.audit.explorerTx(result.txSignature)                                 │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## Public input layout (the ZK circuit)\n\nThe payment circuit emits ten 32-byte public inputs in this fixed order; the on-chain verifier reads them at these exact indices.\n\n```\n[0] is_compliant\n[1] policy_data_hash\n[2] recipient_high           // upper 16 bytes of recipient pubkey\n[3] recipient_low            // lower 16 bytes\n[4] amount_lamports\n[5] token_mint_high\n[6] token_mint_low\n[7] daily_spent_before\n[8] current_unix_timestamp\n[9] stripe_receipt_hash      // '0' for x402\n```\n\n`PAYMENT_PUBLIC_INPUTS = 10`. Instruction builders validate this strictly; passing a different count surfaces as `Error: public_inputs must have exactly 10 entries` rather than silently corrupting on-chain payloads.\n\n## Configuration\n\n| Option | Required | Default |\n|--------|----------|---------|\n| `wallet` | yes | none |\n| `policyServiceUrl` | yes | none |\n| `proverServiceUrl` | yes | none |\n| `complianceApiUrl` | yes | none |\n| `rpcUrl` | no | `https://api.devnet.solana.com` |\n| `connection` | no | built from `rpcUrl` |\n| `dashboardUrl` | no | unset; audit URL helpers fall back to Solana Explorer |\n| `cluster` | no | `'devnet'` |\n| `programs.verifier` | no | `AzKirEv7h5PstLNYNqLj7fCXU9EFA6nSnuoed3QkmUfU` |\n| `programs.policyRegistry` | no | `FXD7ycSguBQw7o3DXqq4VUBHtdx5ZQpu9P2zb4KG4ZEU` |\n| `stripeSecretKey` | MPP only | none |\n| `stripeCredentialsResolver` | MPP only | dashboard lookup against compliance-api |\n| `stripeConfirmer` | MPP only | off_session direct confirm via Stripe REST |\n| `hookAccountsResolver` | Token-2022 mints with TransferHook | none |\n| `fetch` | no | global `fetch` |\n\n## Examples and tests (require cloning the repo)\n\nThe runnable example scripts and Vitest suites live in this package's `examples/` and `tests/` folders. When you `npm install @aperturerwa/sdk`, only the built `dist/` is shipped, so to run these you should clone the source repository at https://github.com/wienerlabs/aperture and work from inside `sdk/aperture-sdk/`.\n\n| Script | What it does |\n|--------|--------------|\n| `examples/policy-cli.mjs` | Interactive CLI. Prompts for every policy rule, validates input, creates + anchors on-chain. No defaults. |\n| `examples/pay-x402.mjs` | Loads the active policy and pays an x402 endpoint. |\n| `examples/pay-mpp.mjs` | Same flow over Stripe + on-chain MPP attestation. |\n| `examples/onboard-fresh-wallet.mjs` | End-to-end: new keypair, policy, x402, batch. |\n\nAfter cloning, run any of them from the repo root:\n\n```bash\nnode --env-file=.env sdk/aperture-sdk/examples/onboard-fresh-wallet.mjs\n```\n\nThe test suites are split into two:\n\n```bash\n# Pure unit tests: byte encoding, PDA derivation, hash + poll utilities.\n# No I/O, no env required. 42 tests in ~1s.\ncd sdk/aperture-sdk\nnpm test\n\n# Live tests against real services + Solana devnet + Stripe.\n# Auto-loads .env from the repo root.\n# Required env: SOLANA_RPC_URL, AGENT_WALLET_PRIVATE_KEY (a funded wallet).\n# Optional:    APERTURE_TEST_MPP_ENABLED=1 + STRIPE_SECRET_KEY\nnpm run test:live\n\n# Run a specific live test\nnpm run test:live -- tests/integration/full-lifecycle.live.test.ts\n```\n\nThe full-lifecycle test creates a brand new Solana keypair every run and drives the entire flow end-to-end (operator init, policy, on-chain anchor, x402 payment, batch attestation, audit URLs) through the SDK only. The Aperture dashboard is never touched.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}