{"_id":"stellar-private-payments","_rev":"8-d91e261c88dffade0ee236ac3f2d8c63","name":"stellar-private-payments","dist-tags":{"alpha":"0.1.0-alpha.1","latest":"0.3.0"},"versions":{"0.0.0":{"name":"stellar-private-payments","version":"0.0.0","_id":"stellar-private-payments@0.0.0","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"}],"dist":{"shasum":"0654daa838b93a31c2927406cf99d6e07f9873de","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.0.0.tgz","fileCount":1,"integrity":"sha512-75LUR+3Assgtwyl+BaMJjKnpqD7A8AQUZgmL98WAyrNyrNrZ8ZQYJTJpqWxr+u1ulITFNe2LeBn/4XRdFun8mg==","signatures":[{"sig":"MEUCIBpfLv3DFfUFIRUAmj2RlH2npm1fLSyygOc4W0MgoDnfAiEA/Vz3rIvjtnNHvES0unZuFPlKCp4OpQpwrN8JzMPdodY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70},"private":false,"_npmUser":{"name":"v0-e","email":"xyz.vieira@gmail.com"},"_npmVersion":"11.17.0","directories":{},"_nodeVersion":"26.5.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/stellar-private-payments_0.0.0_1785404288216_0.6174878884891288","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.0":{"name":"stellar-private-payments","version":"0.1.0-alpha.0","license":"Apache-2.0","_id":"stellar-private-payments@0.1.0-alpha.0","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"dist":{"shasum":"ee09b22482a82fd352c677bce9425c565622ff83","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.1.0-alpha.0.tgz","fileCount":52,"integrity":"sha512-JrdMM9Xqs0zHxROwoQ6yf6diKwbpnCwbHPjgmwExJq0Akn649SlsjMnr5AorrRWn8m/4X0gZFqMAHMwl1I8fdw==","signatures":[{"sig":"MEUCIQCXjYwGhzbG3dpyPaWVt/RkHya2RmxcQiTuwaIJLyN65QIgGby8mrlLQUwx7N5xN1JH77wrqHIeQkYJtVUhPB+UT7Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/stellar-private-payments@0.1.0-alpha.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":70905471},"main":"./js/index.js","type":"module","types":"./js/types/index.d.ts","exports":{".":{"types":"./js/types/index.d.ts","import":"./js/index.js"},"./wasm":{"types":"./dist/stellar_private_payments_sdk_web.d.ts","import":"./dist/stellar_private_payments_sdk_web.js"},"./freighter":{"types":"./js/types/freighter.d.ts","import":"./js/freighter.js"},"./workers/*":"./dist/workers/*","./circuits/*":"./dist/circuits/*"},"gitHead":"68a4df9085cff3852481a08946205dbe9e8de091","scripts":{"build":"bash scripts/build.sh","check:types":"tsc -p tsconfig.json","prepublishOnly":"npm run build && npm run check:artifacts","check:artifacts":"node scripts/check-wasm-types.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6a73fb31-01d1-464c-b229-ca65c7b42789"}},"repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"_npmVersion":"11.16.0","description":"Stellar Private Payments browser SDK (alpha)","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"tag":"alpha","access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"typescript":"^5.5.4"},"peerDependencies":{"@stellar/freighter-api":"^6.0.1"},"peerDependenciesMeta":{"@stellar/freighter-api":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/stellar-private-payments_0.1.0-alpha.0_1785423697875_0.35161662500550817","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.1":{"name":"stellar-private-payments","version":"0.1.0-alpha.1","license":"Apache-2.0","_id":"stellar-private-payments@0.1.0-alpha.1","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"dist":{"shasum":"46bdaa9bf3ba7ec7a591a9576fe0395720e9f89a","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.1.0-alpha.1.tgz","fileCount":52,"integrity":"sha512-1+BKGXMuimRT3BsMW1u2IkcjkdFsEy/O6zf9xwkxFK04XW+y4giOay8WGys70nVOMepKL5t8oSIitOcZxVWW1w==","signatures":[{"sig":"MEUCIFAzczHvGndFmdovpzzVRdSdCYTPgRVsSXJud1d4AtxaAiEApHKq51MuKMPHiDNX2t9Frp3u+t/G5TxxqHPjumTUKlA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/stellar-private-payments@0.1.0-alpha.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":70905565},"main":"./js/index.js","type":"module","types":"./js/types/index.d.ts","exports":{".":{"types":"./js/types/index.d.ts","import":"./js/index.js"},"./wasm":{"types":"./dist/stellar_private_payments_sdk_web.d.ts","import":"./dist/stellar_private_payments_sdk_web.js"},"./freighter":{"types":"./js/types/freighter.d.ts","import":"./js/freighter.js"},"./workers/*":"./dist/workers/*","./circuits/*":"./dist/circuits/*"},"gitHead":"9e40585d28cd733a928b026539f6a45cef8b5dba","scripts":{"build":"bash scripts/build.sh","check:types":"tsc -p tsconfig.json","prepublishOnly":"npm run build && npm run check:artifacts","check:artifacts":"node scripts/check-wasm-types.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6a73fb31-01d1-464c-b229-ca65c7b42789"}},"repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"_npmVersion":"11.16.0","description":"Stellar Private Payments browser SDK (alpha)","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"tag":"alpha","access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"typescript":"^5.5.4"},"peerDependencies":{"@stellar/freighter-api":"^6.0.1"},"peerDependenciesMeta":{"@stellar/freighter-api":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/stellar-private-payments_0.1.0-alpha.1_1785434461840_0.5845163845363053","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"stellar-private-payments","version":"0.1.0","license":"Apache-2.0","_id":"stellar-private-payments@0.1.0","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"dist":{"shasum":"4c6d56e038702d14d5d63051928a8046a1ebfea2","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.1.0.tgz","fileCount":54,"integrity":"sha512-AqeiZZSSLplPn1YVquWd+ivTzf8FTJ2UKYk+hGXM7Sh5vleX7ue4oq1L1wob+Bs8VJxOICZA28uxWDwQdHQtJw==","signatures":[{"sig":"MEYCIQCRQ+kEiwmtLpzL4mLIhHgPmiYBSVYbFaK28v0G6TjS+wIhAJzjzyNfstnafpeifHIENs6lRy1/960GIMmo8rpX4ZOO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":94556142},"main":"./js/index.js","type":"module","types":"./js/types/index.d.ts","exports":{".":{"types":"./js/types/index.d.ts","import":"./js/index.js"},"./wasm":{"types":"./js/types/crates/stellar_private_payments_web.d.ts","import":"./dist/stellar_private_payments_web.js"},"./freighter":{"types":"./js/types/freighter.d.ts","import":"./js/freighter.js"},"./workers/*":"./dist/workers/*","./circuits/*":"./dist/circuits/*"},"gitHead":"4027615d25fca513ba382408e615beb02d699c08","scripts":{"build":"bash scripts/build.sh","check:types":"tsc -p tsconfig.json","check:bindgen":"node scripts/check-bindgen-types.js","prepublishOnly":"npm run build && npm run check:artifacts && npm run check:bindgen && npm run check:types","check:artifacts":"node scripts/check-wasm-types.js"},"_npmUser":{"name":"v0-e","email":"xyz.vieira@gmail.com"},"repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"_npmVersion":"11.19.0","description":"Stellar Private Payments browser SDK","directories":{},"_nodeVersion":"26.8.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.4"},"peerDependencies":{"@stellar/freighter-api":"^6.0.1"},"peerDependenciesMeta":{"@stellar/freighter-api":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/stellar-private-payments_0.1.0_1788432445866_0.013618513272610322","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"stellar-private-payments","version":"0.2.1","license":"Apache-2.0","_id":"stellar-private-payments@0.2.1","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"dist":{"shasum":"14e260f0c8c2765354ad0c2a0773fd1482afcb55","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.2.1.tgz","fileCount":80,"integrity":"sha512-d4ABQKBB0DzLqM6v0sLpfGL7MdxnqXwhNIy5E3jtDgOI1S5jBhlJbkQxNl0g94MnGFyKZ1bl90thMTdSOOkhuQ==","signatures":[{"sig":"MEUCIGmaZqtuqeOZ3wvh3aT+jKMItYSMeUnpDlmqFTxOrokXAiEA55lr9lquXiiWarhn/2/6hKbcVTOvVZ632f5PvaV8TXE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCOrAVn6q5++6umpGg0ZtWjZ8xyNpEkN3np+P2YPduxBAIgCVoW96EnOHI2pYXAidazixwyixSqvzgZz5vQIRG5jMU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/stellar-private-payments@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":292521409},"main":"./js/index.js","type":"module","_from":"file:package/stellar-private-payments-0.2.1.tgz","types":"./js/types/index.d.ts","exports":{".":{"types":"./js/types/index.d.ts","import":"./js/index.js"},"./wasm":{"types":"./js/types/crates/stellar_private_payments_web.d.ts","import":"./dist/stellar_private_payments_web.js"},"./freighter":{"types":"./js/types/freighter.d.ts","import":"./js/freighter.js"},"./workers/*":"./dist/workers/*","./circuits/*":"./dist/circuits/*"},"scripts":{"build":"bash scripts/build.sh","check:types":"tsc -p tsconfig.json","test:amounts":"node --test tests/amounts.test.mjs","check:bindgen":"node scripts/check-bindgen-types.js","prepublishOnly":"npm run build && npm run check:artifacts && npm run check:bindgen && npm run check:types","check:artifacts":"node scripts/check-wasm-types.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d7bec177-497c-4189-a379-fb61be79145e"}},"_resolved":"/home/runner/work/stellar-private-payments/stellar-private-payments/package/stellar-private-payments-0.2.1.tgz","_integrity":"sha512-d4ABQKBB0DzLqM6v0sLpfGL7MdxnqXwhNIy5E3jtDgOI1S5jBhlJbkQxNl0g94MnGFyKZ1bl90thMTdSOOkhuQ==","repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"_npmVersion":"11.19.0","description":"Stellar Private Payments browser SDK","directories":{},"_nodeVersion":"24.21.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3"},"peerDependencies":{"@stellar/freighter-api":"^6.0.1"},"peerDependenciesMeta":{"@stellar/freighter-api":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/stellar-private-payments_0.2.1_1792153771939_0.7087437403408192","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"stellar-private-payments@0.3.0","bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"dist":{"shasum":"beb6ef90df83508a74a22f6df563ec62b76d4e1c","tarball":"https://registry.npmjs.org/stellar-private-payments/-/stellar-private-payments-0.3.0.tgz","fileCount":83,"integrity":"sha512-kfIlsq5EQncePxBwdNUK5x9KqMJiNtQ8JT0m/3Av0LBEvsv8l1/E8FgADO7w+xSKz2IYXHkvSF1wVpE5kmXFJg==","signatures":[{"sig":"MEQCIDsdySZkFOdgSaJjH/+E2Qdrgyt/Ld8LrXo8TAfF+Qy5AiB+B9clw4n5wzSCUe2CObfVJqZ9auDGPFPueZfJDPlcaQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCday1PPY6LU2n5oCsj+k2ZJMlsB2mC4bgo0PDpw+viywIhAIIQ0BdsxbCS2NXgOt7bIM6ZpSo3aegK1knTTeyo9UMR"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/stellar-private-payments@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":293963518},"main":"./js/index.js","name":"stellar-private-payments","type":"module","_from":"file:package/stellar-private-payments-0.3.0.tgz","types":"./js/types/index.d.ts","exports":{".":{"types":"./js/types/index.d.ts","import":"./js/index.js"},"./wasm":{"types":"./js/types/crates/stellar_private_payments_web.d.ts","import":"./dist/stellar_private_payments_web.js"},"./freighter":{"types":"./js/types/freighter.d.ts","import":"./js/freighter.js"},"./workers/*":"./dist/workers/*","./circuits/*":"./dist/circuits/*"},"license":"Apache-2.0","scripts":{"build":"bash scripts/build.sh","check:types":"tsc -p tsconfig.json","test:amounts":"node --test tests/amounts.test.mjs","check:bindgen":"node scripts/check-bindgen-types.js","check:package":"node scripts/check-sqlite3mc-package.js","prepublishOnly":"npm run build && npm run check:artifacts && npm run check:bindgen && npm run check:types && npm run check:package","check:artifacts":"node scripts/check-wasm-types.js"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d7bec177-497c-4189-a379-fb61be79145e"}},"homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","_resolved":"/home/runner/work/stellar-private-payments/stellar-private-payments/package/stellar-private-payments-0.3.0.tgz","_integrity":"sha512-kfIlsq5EQncePxBwdNUK5x9KqMJiNtQ8JT0m/3Av0LBEvsv8l1/E8FgADO7w+xSKz2IYXHkvSF1wVpE5kmXFJg==","repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"_npmVersion":"11.19.1","description":"Stellar Private Payments browser SDK","directories":{},"maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"_nodeVersion":"24.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^6.0.3"},"peerDependencies":{"@stellar/freighter-api":"^6.0.1"},"peerDependenciesMeta":{"@stellar/freighter-api":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stellar-private-payments_0.3.0_1794242012172_0.9924692374948472"}}},"time":{"created":"2026-07-30T09:38:08.049Z","modified":"2026-11-09T16:33:34.307Z","0.0.0":"2026-07-30T09:38:08.328Z","0.1.0-alpha.0":"2026-07-30T15:01:38.446Z","0.1.0-alpha.1":"2026-07-30T18:01:02.437Z","0.1.0":"2026-09-03T10:47:26.525Z","0.2.1":"2026-10-16T12:29:33.535Z","0.3.0":"2026-11-09T16:33:33.825Z"},"bugs":{"url":"https://github.com/NethermindEth/stellar-private-payments/issues"},"license":"Apache-2.0","homepage":"https://github.com/NethermindEth/stellar-private-payments#readme","repository":{"url":"git+https://github.com/NethermindEth/stellar-private-payments.git","type":"git","directory":"sdk/web"},"description":"Stellar Private Payments browser SDK","maintainers":[{"name":"v0-e","email":"xyz.vieira@gmail.com"},{"name":"cupicmarko","email":"marko@cupic.dev"},{"name":"fantonio","email":"antonio.larriba@nethermind.io"}],"readme":"# Stellar Private Payments Browser SDK\n\nTransact Stellar assets privately, from JavaScript/TypeScript. See the project\n[README](../../README.md) for how the protocol works.\n\n> **Work in progress**: not audited and not production-ready.\n\n[![npm](https://img.shields.io/npm/v/stellar-private-payments.svg)](https://www.npmjs.com/package/stellar-private-payments)\n\n```bash\nnpm install stellar-private-payments\n```\n\n## Quick start\n\n```js\nimport init, { Storage, Client, bootnodeRequired } from 'stellar-private-payments';\nimport { FreighterSigner } from 'stellar-private-payments/freighter';\n\nconst networkPassphrase = 'Test SDF Network ; September 2015';\nconst rpcUrl = 'https://soroban-testnet.stellar.org';\nconst contractConfig = await fetch('/deployments.json').then((r) => r.json());\nconst circuitsBaseUrl = new URL('./circuits/', import.meta.url).href;\n// Bundle trusted fingerprints with your application using your bundler's JSON loader.\nimport circuitLock from './trusted-deployment/circuits.json';\n// Fetching the lock beside the artifacts only detects corruption or mismatches;\n// it cannot authenticate artifacts if that server can replace both.\nconst signer = new FreighterSigner();\n\nawait init();\n\n// keyProvider must return the same recoverable 32-byte key on later opens.\nconst storage = await Storage.open({ keyProvider, createNew: false });\n\nif (await bootnodeRequired(rpcUrl, storage, { contractConfig })) {\n  // load or prompt for a bootnode URL, then pass it to Client.new\n}\n\nconst client = await Client.new({ rpcUrl, storage, contractConfig, circuitsBaseUrl, circuitLock });\nawait client.backgroundSync();\n\nconst account = await client.account({ networkPassphrase }, signer);\nawait account.derivePrivacyKeys(); // idempotent; prompts the wallet only the first time\n\nconst pool = await account.pool({ poolContract: 'CA2TZ...' });\nawait pool.deposit(10_000_000n); // token base units (1 token if its decimals are 7)\nconst balance = await pool.balance(); // bigint token base units\nawait pool.transfer('G...', 5_000_000n);\nawait pool.withdraw(3_000_000n); // defaults to connected wallet\n```\n\n### Walletless verification\n\nVerify a selective-disclosure receipt without a `Storage` / `Client` session:\n\n```js\nimport { verifySelectiveDisclosure } from 'stellar-private-payments';\n\nconst report = await verifySelectiveDisclosure(rpcUrl, receiptJson, expectedVkHash, {\n  contractConfig,\n  circuitsBaseUrl,\n  circuitLock,\n});\n```\n\nThe same package supports any compatible deployment. Supply its configuration,\nartifact base URL, and expected fingerprints at runtime; no network-specific\npackage build is required. Each prover worker uses one bundle. To change bundles,\ncreate a new client/prover instead of reconfiguring an active worker.\n\n## Operator API\n\nAdmins reach their contracts through one handle per contract, as in the\n[Rust SDK](../native/README.md#operator-api). None needs a `Storage` or a\n`Client`:\n\n```js\nimport init, { AllowlistOperator, BlocklistOperator, PoolAdmin } from 'stellar-private-payments';\n\nawait init();\nconst tree = AllowlistOperator.open(rpcUrl, contractConfig, contractConfig.asp_membership);\nconst { admin, pendingAdmin } = await tree.admin();\nconst leaf = AllowlistOperator.deriveUserLeaf(notePublicKey, aspSecret);\nconst { envelopeXdr, call } = await tree.insertLeaf(leaf);\n// Each signer of call.source adds a signature to envelopeXdr, then anyone sends it.\n```\n\n`BlocklistOperator` builds `insertKeys(noteKeys)` and `deleteKey(noteKey)`, and\n`PoolAdmin` builds `pauseDeposits()`, `unpauseDeposits()`,\n`claimFees(to, amount)`, `repointAllowlist(tree)`, and `repointBlocklist(tree)`. All three build\n`proposeAdmin(newAdmin)`, `cancelAdminTransfer()`, and `acceptAdmin()`, and\nreport `listed`: whether the deployment config names the contract. A builder\nthat refuses a call over entries about to archive throws an `Error` whose\n`extendCommands` holds the `stellar contract extend` commands that fix it.\n\nA `Client` opens the same handles with `allowlistOperator(id)`,\n`blocklistOperator(id)`, and `poolAdmin(id)`, lists the deployment's contracts\nwith `allowlistIds()`, `blocklistIds()`, and `poolIds()`, and opens a GVK audit\nwith `gvkAuthority(keyHex).audit(poolContractId)`.\n\nMigrating:\n\n| Removed | Use |\n| --- | --- |\n| `deriveAspUserLeaf(noteKey, secret)` | `AllowlistOperator.deriveUserLeaf(noteKey, secret)` |\n| `client.aspState()` | `client.allowlistOperator(id).state()` and `client.blocklistOperator(id).state()` |\n| `pool.audit(keyHex)` | `client.gvkAuthority(keyHex).audit(poolContractId)` |\n\n## API reference\n\nMethod names mirror the [Rust SDK](../native/README.md). Full signatures live in\nthe generated types: [`js/types/api-types.d.ts`](./js/types/api-types.d.ts)\n(`Client`, `Account`, `PrivatePool`, options) and\n[`js/types/index.d.ts`](./js/types/index.d.ts) (package entry).\n\n### Errors\n\nWhen the SDK refuses a deposit or a spend before proving, the call rejects with\nan `Error` that carries a `code` and the amounts the refusal names (`PoolRefusal`\nin `api-types.d.ts`). Amounts are `bigint` base units.\n\n| `code` | Amount properties |\n| --- | --- |\n| `DEPOSITS_PAUSED` | none |\n| `DEPOSIT_BELOW_MINIMUM` | `minimum` |\n| `DEPOSIT_ABOVE_MAXIMUM` | `maximum`, `largestDeposit` |\n| `NO_COMBINATION` | `maxSpend` |\n| `NO_SPENDABLE_NOTES` | none |\n| `NOT_BALANCED` | `gap`, negative when more goes out than comes in |\n| `WITHDRAWAL_TO_CONTRACT` | none |\n\nA refusal after a payment's first transaction has confirmed resolves as a failed\nresult instead, so the confirmed transaction's hash is not lost.\n\n## Signer\n\nBound at `client.account()`. Must implement `signMessage`, `signTransaction`,\nand `signAuthEntry` (see [`js/types/signer.d.ts`](./js/types/signer.d.ts)).\nOptional Freighter adapter: `stellar-private-payments/freighter` (requires\npeer `@stellar/freighter-api`).\n\n## Logging & Diagnostics\n\nThe SDK emits `tracing` spans and events in Rust, controllable from JS:\n\n```js\nimport { configureTelemetry, dump_recent_logs, set_log_level } from 'stellar-private-payments';\n\nconfigureTelemetry({\n  level: 'debug',             // 'info' | 'debug' | 'trace'\n  sink: 'both',               // 'console' | 'ringBuffer' | 'both'\n  ringBufferBytes: 256 * 1024,\n  revealSensitive: true,      // reveal Tier-1 values (debug profile only)\n});\n\nconst logs = await dump_recent_logs(); // main thread + storage/prover workers\nset_log_level('info');\n```\n\n## TypeScript\n\nPublic types live under [`js/types/`](./js/types/): `api-types.d.ts` (JS\nfacade), `index.d.ts` (package entry), and the gitignored, build-staged\n`crates/stellar_private_payments_web.d.ts` (wasm-bindgen domain types). The\npackage entry re-exports the low-level wasm types as `WasmClient`,\n`WasmAccount`, and `WasmStorage` (types only); import the runtime classes from\n`stellar-private-payments/wasm`.\n\nAfter building WASM:\n\n```bash\nnpm run build\nnpm run check:bindgen   # wasm exports ⊆ public .d.ts; staged crates/ === dist/\nnpm run check:types\n```\n\nBoth checks need a full build first — `crates/stellar_private_payments_web.d.ts`\nonly exists once `scripts/stage-wasm-types.sh` has staged it from `dist/`.\n\n## Workers\n\nWeb Workers run the OPFS SQLite storage backend and Groth16 prover off the main thread. `Storage.open()` and `Client.new()` resolve default worker URLs relative to `import.meta.url` (overridable via `workerUrl`, `storageWorkerUrl`, and `proverWorkerUrl`). When `Client.new()` opens storage itself instead of receiving a `storage` handle, pass `keyProvider` in its options.\n\n## Build & publish (maintainers)\n\nBrowser builds compile SQLite3MC through `sqlite-wasm-rs` (`sqlite3mc` feature), which requires Clang and `llvm-ar` (or `ar`). Building the npm package from source also requires `wasm-bindgen-cli` and [Binaryen](https://github.com/WebAssembly/binaryen) `wasm-opt` (see [CONTRIBUTING.md](../../CONTRIBUTING.md)):\n\n```bash\nmake circuits\nnpm run build\nnpm pack\n```\n\nPublished tarball: `dist/` (WASM, workers, **bundled circuits** + LGPL source bundle) and `js/` (entry + types).\n\nCI publishes from `main` when `version` in `package.json` is bumped (see `.github/workflows/release.yml`).\n\n### Storage features\n\nOPFS storage is selected with Cargo features; at least one must be enabled.\n\n- `encrypted-storage` (default): SQLite3MC-encrypted storage in `spp.encrypted.db`, opened with `Storage.open({ keyProvider })`.\n- `unencrypted-storage`: plaintext storage in `spp.db` under `.opfs-sahpool-plaintext`, separate from the legacy `.opfs-sahpool` directory, opened with `Storage.openPlaintext()`. No SQLite3MC is compiled when it is the only storage feature.\n\n`Storage.openPlaintext()` throws on a build without `unencrypted-storage`, and `Storage.open()` throws before calling `keyProvider` on a build without `encrypted-storage`. In a build with only `unencrypted-storage`, the WASM `Storage.open` opens plaintext storage when no key is supplied. Pass the features to the build through `SPP_WEB_CARGO_FEATURES`:\n\n```bash\nSPP_WEB_CARGO_FEATURES=\"--features unencrypted-storage\" npm run build\nSPP_WEB_CARGO_FEATURES=\"--no-default-features --features unencrypted-storage\" npm run build\n```\n\n### Binaryen / `wasm-opt`\n\nThe build script (`scripts/build.sh`) optimizes every shipped circuit witness\nmodule with `wasm-opt -Os`. It pins Binaryen `version_131` and downloads the\nmatching release tarball for `x86_64-linux`, `aarch64-linux`, `x86_64-macos`,\nor `arm64-macos` when `wasm-opt` isn't already on `PATH` (needs `curl`, `tar`,\n`sha256sum`/`shasum`).\n\nTo skip the download, install Binaryen 131 locally and set `WASM_OPT`:\n\n```bash\nexport WASM_OPT=/usr/local/bin/wasm-opt\nnpm run build\n```\n\nThe optimization cache lives under `target/tmp/witness-opt-cache/`, keyed by\nthe `wasm-opt` version, cargo profile, and enabled feature flags — safe to\ndelete at any time.\n\n## Licensing (compiled circuits)\n\nCompiled `.graph.bin` / `.r1cs` files incorporate [iden3/circomlib](https://github.com/iden3/circomlib) (LGPL-3.0). The npm package includes:\n\n| Path | Purpose |\n|------|---------|\n| `dist/circuits/NOTICE.txt` | Circuit licensing notice |\n| `dist/circuits/source-bundle.tar.gz` | Corresponding source to rebuild artifacts |\n| `dist/licenses/LGPL-3.0.txt`, `GPL-3.0.txt` | License texts |\n| `dist/LICENSE.txt` | Apache-2.0 (this SDK) |\n\nThe Pool Stellar web app uses the same legal layout via Trunk (`deployments/scripts/stage-dist-legal.sh`). If you redistribute the compiled circuits, comply with LGPL-3.0 (see NOTICE).\n\n## Mandatory storage encryption\n\nIn the default build, `Storage.open` requires a `keyProvider` before starting the storage worker. Passing `createNew: true` initializes a fresh encrypted database in OPFS (`spp.encrypted.db`), while `createNew: false` opens an existing one and fails if it is missing. Every table, including synced chain events and app settings, lives inside that encrypted database; there is no plaintext fallback or automatic browser migration.\n\nIn the web app, `keyProvider` seals a random 32-byte database key in `localStorage` under `AES-256-GCM`, using a wrapping key derived via `HKDF-SHA-256` from a verified Freighter signature in a dedicated storage domain. Enrolling a new database requests two signatures over the unlock message to confirm the wallet signs deterministically before sealing the key; later opens need one signature. When the user locks storage manually or the inactivity timer expires, the app closes the storage worker and reloads the page so decrypted state in WASM and JavaScript memory is discarded.\n\n### Encrypted backups and recovery\n\nBecause the database key is random and only its wrapped envelope lives in `localStorage`, the OPFS database files and the `localStorage` envelope depend on each other. The **Local storage backup and recovery** controls in the app's settings drawer package both together into a single backup archive (up to 256 MiB). Export, import, and reset work whether storage is locked or unlocked. When it is unlocked, the app first closes the worker so the files are consistent, and the tab then reloads into the locked state. Exporting locked storage copies the files without a signature or reload. The archive holds only ciphertext and the wrapped key envelope, so restoring it still requires signing with the original unlocking wallet account.\n\nImporting accepts backups from the same origin (`scheme`, `host`, and `port`). Rather than overwriting the live database in place, the app stages the archive into a fresh OPFS directory, asks the enrolled wallet to unlock it, and runs SQLite integrity and foreign-key checks against the staged files. Only after those checks pass does a single `localStorage` write switch the active envelope and directory pointer; if anything fails along the way, the existing storage remains untouched. After a successful import, the reloaded tab asks the wallet to unlock the restored storage. Restoring a backup replaces local state with the snapshot from export time and does not merge later local changes.\n\nIf `localStorage` is cleared while encrypted OPFS files remain on disk, signing again with Freighter cannot reconstruct the lost random key. In that state, the app stops before enrollment so the user can either import a backup or wipe local storage cleanly. Separately, if an unencrypted `.opfs-sahpool` directory from an earlier build is still on disk, the app warns that legacy plaintext files are present and offers to remove them. **Reset local storage** (confirmed by typing `DELETE` with other app tabs closed) removes this origin's encrypted and legacy OPFS directories, key envelope, and legacy signer associations without affecting on-chain funds. The next wallet connection then enrolls new storage.\n\nTo run the browser backup round-trip test after building the SDK:\n\n```sh\nnode integration-tests-app/scripts/test-storage-backup.mjs\n```\n\nThe test drives a temporary Chromium profile with ephemeral signing keys (`E2E_CHROMIUM_PATH` overrides the browser binary) and does not need a Stellar network.\n\n### Token amounts\n\nTransaction methods accept `bigint` base units. After SDK initialization, use\n`parseTokenAmount` with the pool token's precision:\n\n```js\nimport { parseTokenAmount } from 'stellar-private-payments';\nconst decimals = await pool.tokenDecimals();\nawait pool.deposit(parseTokenAmount('1.25', decimals));\n```\n\nThe parser rejects invalid input, excess precision, negative nonzero values, and\n`u128` overflow. It never rounds or converts through JavaScript `Number`.\n","readmeFilename":"README.md"}