@veilo/sdk-core 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veilo/sdk-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeScript SDK for the Veilo Privacy Pool - UTXO-based privacy protocol on Solana with ZK-SNARKs",
   "homepage": "https://github.com/VeiloSolana/veilo-sdk#readme",
   "bugs": {
@@ -77,6 +77,106 @@
         "default": "./dist/cjs/shield/index.js"
       }
     },
+    "./accounts": {
+      "import": {
+        "types": "./dist/esm/accounts/index.d.ts",
+        "default": "./dist/esm/accounts/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/accounts/index.d.ts",
+        "default": "./dist/cjs/accounts/index.js"
+      }
+    },
+    "./transactions": {
+      "import": {
+        "types": "./dist/esm/transactions/index.d.ts",
+        "default": "./dist/esm/transactions/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/transactions/index.d.ts",
+        "default": "./dist/cjs/transactions/index.js"
+      }
+    },
+    "./notes": {
+      "import": {
+        "types": "./dist/esm/notes/index.d.ts",
+        "default": "./dist/esm/notes/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/notes/index.d.ts",
+        "default": "./dist/cjs/notes/index.js"
+      }
+    },
+    "./relayer": {
+      "import": {
+        "types": "./dist/esm/relayer/index.d.ts",
+        "default": "./dist/esm/relayer/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/relayer/index.d.ts",
+        "default": "./dist/cjs/relayer/index.js"
+      }
+    },
+    "./cloak": {
+      "import": {
+        "types": "./dist/esm/cloak.d.ts",
+        "default": "./dist/esm/cloak.js"
+      },
+      "require": {
+        "types": "./dist/cjs/cloak.d.ts",
+        "default": "./dist/cjs/cloak.js"
+      }
+    },
+    "./identity": {
+      "import": {
+        "types": "./dist/esm/identity/index.d.ts",
+        "default": "./dist/esm/identity/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/identity/index.d.ts",
+        "default": "./dist/cjs/identity/index.js"
+      }
+    },
+    "./positions": {
+      "import": {
+        "types": "./dist/esm/positions/index.d.ts",
+        "default": "./dist/esm/positions/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/positions/index.d.ts",
+        "default": "./dist/cjs/positions/index.js"
+      }
+    },
+    "./perps": {
+      "import": {
+        "types": "./dist/esm/perps/index.d.ts",
+        "default": "./dist/esm/perps/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/perps/index.d.ts",
+        "default": "./dist/cjs/perps/index.js"
+      }
+    },
+    "./predictions": {
+      "import": {
+        "types": "./dist/esm/predictions/index.d.ts",
+        "default": "./dist/esm/predictions/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/predictions/index.d.ts",
+        "default": "./dist/cjs/predictions/index.js"
+      }
+    },
+    "./idl": {
+      "import": {
+        "types": "./dist/esm/idl/index.d.ts",
+        "default": "./dist/esm/idl/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/idl/index.d.ts",
+        "default": "./dist/cjs/idl/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -85,28 +185,48 @@
   "sideEffects": false,
   "files": [
     "dist/",
+    "accounts.js",
+    "cloak.js",
     "config.js",
-    "config.d.ts",
+    "identity.js",
+    "idl.js",
+    "notes.js",
+    "perps.js",
     "poseidon.js",
-    "poseidon.d.ts",
+    "positions.js",
+    "predictions.js",
     "proof.js",
-    "proof.d.ts",
     "prover.js",
-    "prover.d.ts",
+    "relayer.js",
     "shield.js",
+    "transactions.js",
+    "accounts.d.ts",
+    "cloak.d.ts",
+    "config.d.ts",
+    "identity.d.ts",
+    "idl.d.ts",
+    "notes.d.ts",
+    "perps.d.ts",
+    "poseidon.d.ts",
+    "positions.d.ts",
+    "predictions.d.ts",
+    "proof.d.ts",
+    "prover.d.ts",
+    "relayer.d.ts",
     "shield.d.ts",
+    "transactions.d.ts",
     "README.md",
-    "SHIELD_INTEGRATION.md",
     "LICENSE"
   ],
-  "directories": {
-    "test": "tests"
-  },
   "scripts": {
+    "check:cycles": "node scripts/check-dependency-cycles.mjs",
     "gen:idl": "node scripts/gen-idl.mjs",
+    "copy:circuits": "node scripts/copy-circuits.mjs",
     "verify:cipher-parity": "npm run build && node scripts/verify-compact-cipher-parity.mjs",
-    "build": "rm -rf dist/ && tsc -p tsconfig.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
-    "test": "rm -rf dist/ && export ANCHOR_PROVIDER_URL=https://api.devnet.solana.com && export ANCHOR_WALLET=$HOME/.config/solana/id.json && tsc -p test-tsconfig.json && mocha -t 1000000 \"dist/tests/**/*.js\""
+    "build": "rm -rf dist/ && tsc -p tsconfig.json && tsc -p tsconfig.esm.json && node scripts/copy-idls.mjs && node scripts/gen-subpath-stubs.mjs && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "test": "rm -rf dist/ && tsc -p test-tsconfig.json && mocha -t 1000000 \"dist/tests/**/*.js\"",
+    "test:integration": "export VEILO_RUN_INTEGRATION=1 && export ANCHOR_PROVIDER_URL=https://api.devnet.solana.com && export ANCHOR_WALLET=$HOME/.config/solana/id.json && npm test",
+    "gen:stubs": "node scripts/gen-subpath-stubs.mjs"
   },
   "dependencies": {
     "@coral-xyz/anchor": "^0.30.0",

package/perps.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/perps/index";

package/perps.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/perps" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/perps/index.js");

package/poseidon.d.ts

@@ -1,2 +1,2 @@
-// Stub for legacy resolvers — see poseidon.js
-export * from "./dist/cjs/poseidon.js";
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/poseidon";

package/poseidon.js

@@ -1,4 +1,3 @@
-// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
-// that ignore the "exports" map. Modern resolvers use "./poseidon" from package.json
-// exports and never reach this file.
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/poseidon" for legacy moduleResolution: "node".
 module.exports = require("./dist/cjs/poseidon.js");

package/positions.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/positions/index";

package/positions.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/positions" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/positions/index.js");

package/predictions.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/predictions/index";

package/predictions.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/predictions" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/predictions/index.js");

package/proof.d.ts

@@ -1,2 +1,2 @@
-// Stub for legacy resolvers — see proof.js
-export * from "./dist/cjs/proof.js";
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/proof";

package/proof.js

@@ -1,4 +1,3 @@
-// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
-// that ignore the "exports" map. Modern resolvers use "./proof" from package.json
-// exports and never reach this file.
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/proof" for legacy moduleResolution: "node".
 module.exports = require("./dist/cjs/proof.js");

package/prover.d.ts

@@ -1,2 +1,2 @@
-// Stub for legacy resolvers — see prover.js
-export * from "./dist/cjs/prover.js";
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/prover";

package/prover.js

@@ -1,4 +1,3 @@
-// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
-// that ignore the "exports" map. Modern resolvers use "./prover" from package.json
-// exports and never reach this file.
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/prover" for legacy moduleResolution: "node".
 module.exports = require("./dist/cjs/prover.js");

package/relayer.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/relayer/index";

package/relayer.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/relayer" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/relayer/index.js");

package/shield.d.ts

@@ -1,2 +1,2 @@
-// Stub for legacy resolvers — see shield.js
-export * from "./dist/cjs/shield/index.js";
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/shield/index";

package/shield.js

@@ -1,4 +1,3 @@
-// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
-// that ignore the "exports" map. Modern resolvers use "./shield" from package.json
-// exports and never reach this file.
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/shield" for legacy moduleResolution: "node".
 module.exports = require("./dist/cjs/shield/index.js");

package/transactions.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/transactions/index";

package/transactions.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/transactions" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/transactions/index.js");

package/SHIELD_INTEGRATION.md

@@ -1,143 +0,0 @@
-# Wallet-agnostic shielding
-
-`shield()` builds an unsigned Solana v0 transaction that moves funds from any
-signing wallet into Veilo's privacy pool. The wallet that pays and the Veilo
-account that owns the resulting private note are independent.
-
-This is a build API, like Jupiter's transaction APIs. The SDK proves, encrypts,
-and assembles. Your application asks its wallet to sign, submits the signed
-bytes, confirms them, and handles retry.
-
-## Security model
-
-- `signer.publicKey` is the transaction fee payer and public funding source.
-- `owner.veiloPublicKey` controls spending the private note.
-- `owner.noteViewingKey` controls detecting and decrypting the note during a
-  chain scan.
-- The SDK never receives a signer secret key.
-- The compact note cipher is embedded in the on-chain instruction, so note
-  recovery does not depend on a webhook or a later relayer callback.
-
-The two owner keys must belong to the same Veilo account. If they do not, the
-note is spendable but invisible to its owner. Always use `resolveShieldOwner()`;
-construct an owner manually only when you can prove the pairing yourself.
-
-## Complete flow
-
-```ts
-import { Connection, PublicKey } from "@solana/web3.js";
-import {
-  createTransactionProver,
-  finalizeShield,
-  mapShieldError,
-  rebuild,
-  resolveShieldOwner,
-  shield,
-} from "@veilo/sdk-core";
-
-const connection = new Connection(RPC_URL, "confirmed");
-const owner = await resolveShieldOwner({ username: "alice" });
-const prover = createTransactionProver({
-  wasmPath: TRANSACTION_WASM_URL,
-  zkeyPath: TRANSACTION_ZKEY_URL,
-});
-
-let result = await shield({
-  connection,
-  amount: 5_000_000n, // base units
-  mint: new PublicKey(USDC_MINT),
-  owner,
-  signer: { publicKey: wallet.publicKey },
-  prover,
-});
-
-async function signAndSubmit() {
-  const signed = await wallet.signTransaction(result.transaction);
-  const signature = await connection.sendRawTransaction(signed.serialize(), {
-    maxRetries: 0,
-  });
-
-  const confirmation = await connection.confirmTransaction(
-    {
-      signature,
-      blockhash: result.blockhash,
-      lastValidBlockHeight: result.lastValidBlockHeight,
-    },
-    "confirmed",
-  );
-  if (confirmation.value.err) throw confirmation.value.err;
-  return signature;
-}
-
-let signature: string;
-try {
-  signature = await signAndSubmit();
-} catch (cause) {
-  const error = mapShieldError(cause);
-  if (error.retryable !== "rebuild") throw error;
-
-  // Reuses the proof and note; only the blockhash and deadline are refreshed.
-  result = await rebuild(result, { connection });
-  signature = await signAndSubmit(); // the rebuilt transaction needs a new signature
-}
-
-const finalized = await finalizeShield({
-  connection,
-  signature,
-  note: result.note,
-  owner,
-  commitment: "finalized",
-});
-
-console.log(finalized.leafIndex, finalized.treeId);
-```
-
-`predictedLeafIndex` is informational only. Concurrent deposits can move the
-actual index before your transaction lands. Persist `finalized.leafIndex`, which
-comes from this transaction's `CommitmentEvent`.
-
-## Preflight and wallet UX
-
-Preflight runs before the 10–30 second proof and checks pool limits, token
-ownership and balance, ATA state, and the SOL needed by the transaction. If an
-SPL token account has any delegate—even with a delegated amount of zero—the
-program rejects it. `TOKEN_ACCOUNT_DELEGATED` includes a `remedy` with the
-`Revoke` instruction the wallet can sign before retrying.
-
-The wallet may describe the Veilo instruction as an unknown program. Show the
-amount and destination in your own review screen before opening the wallet so
-the signer can verify what it is authorizing.
-
-## SOL requirements
-
-The signer pays:
-
-- the amount itself for native SOL shields;
-- the normal transaction and priority fees; and
-- rent for two nullifier-marker accounts (about 0.00192 SOL at current rent).
-
-The program fixes the marker payer to the signer. A zero-SOL wallet therefore
-cannot use this path, even for an SPL token shield and even if another service
-would sponsor the transaction fee. This API does not provide a gasless mode.
-
-## Retry decisions
-
-Use `mapShieldError()` and branch on `retryable`:
-
-| Error | Retry class | Action |
-|---|---|---|
-| `BLOCKHASH_EXPIRED`, `DEADLINE_EXPIRED` | `rebuild` | Call `rebuild()`, sign again, submit again. |
-| `ROOT_STALE` | `reshield` | Call `shield()` again; a fresh proof is required. |
-| `NULLIFIER_COLLISION` | `none` | Treat as already submitted and check the original signature. |
-| Preflight and configuration errors | `none` | Correct the stated condition before retrying. |
-
-`ShieldProofCache` is public and JSON-serializable. `ShieldNote` is secret. Do
-not store or transmit the note in the clear, and do not bundle it with the proof
-cache merely because the cache is safe to move between processes.
-
-## Optional mailbox delivery
-
-`finalizeShield()` returns an encrypted `blob` suitable for `/notes/save`.
-Supplying `recipientWalletPublicKey` gives faster mailbox delivery and push
-notifications, but records a sender-to-recipient association at the relayer.
-Omitting it keeps discovery chain-only and preserves that privacy boundary.