veilix-sdk 0.0.10 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 TypeScript SDK for interacting with the Veilix privacy protocol on Solana — deposits, withdrawals, private transfers, and fee quotes.
 
+Veilix uses a UTXO note model: a deposit can be **any amount** (up to the pool's per-deposit cap), and a withdrawal can take the whole note or only part of it — the remainder comes back as a new *change note*.
+
 **Third-party partners** integrating Private Send into their own website or app (quote → wallet sign → deposit → `/submit`): see [`docs/partner-private-send.md`](./docs/partner-private-send.md).
 
 ## Installation
@@ -18,10 +20,10 @@ npm install @solana/wallet-adapter-react react
 
 ## Prerequisites
 
-- A Solana wallet (`Keypair` for backend/scripts, or a wallet adapter with `signMessage` / `signAllTransactions` for frontend)
+- A Solana wallet (`Keypair` for backend/scripts, or a wallet adapter with `signMessage` / `signTransaction` / `signAllTransactions` for frontend)
 - An RPC endpoint or existing `@solana/web3.js` `Connection`
 
-Supported networks: `mainnet` and `devnet` (inferred from the RPC URL, or set explicitly via `network`).
+Supported networks: `mainnet` and `devnet` (set via `network`).
 
 ---
 
@@ -29,244 +31,216 @@ Supported networks: `mainnet` and `devnet` (inferred from the RPC URL, or set ex
 
 Create one SDK instance per configuration (network, RPC, wallet). Initialization loads active relayers for the target network.
 
-```ts, tsx
-import { VeilixSDK  } from "veilix-sdk";
+```ts
+import { VeilixSDK } from "veilix-sdk";
 
-VeilixSDK.create({
-  rpcEndpoint: RPC_URL,
+const sdk = await VeilixSDK.create({
+  rpcEndpoint: RPC_URL, // or `connection`
   wallet,
-  network: NETWORK,
-})
-.then((sdk) => {
-  ...
-})
+  network: "mainnet",
+});
 ```
 
 ### Init options
 
 | Option | Required | Description |
 |--------|----------|-------------|
-| `wallet` | yes | Anchor-compatible wallet (`Keypair` or wallet adapter) |
-| `rpcEndpoint` | yes | Solana JSON-RPC URL |
-| `network` | yes | `"mainnet"` or `"devnet"` — override when the RPC URL has no cluster hint |
+| `wallet` | yes | Anchor-compatible wallet (`Keypair` wrapper or wallet adapter) |
+| `rpcEndpoint` / `connection` | one of | Solana JSON-RPC URL, or an existing `Connection` |
+| `network` | yes | `"mainnet"` or `"devnet"` |
+| `circuitPathsBase` | no | Self-hosted location of `withdraw.wasm` / `withdraw.zkey` |
+| `indexerUrl` | no | Indexer override (defaults to the Veilix indexer of `network`) |
+| `riskApiUrl` | no | Address-risk API override |
 
 After creation, inspect runtime config via `sdk.config` or helpers like `sdk.getNetwork()`, `sdk.relayers`, and `sdk.getTokenMints()`.
 
 ---
 
-## `getEncryptionKey`
+## Notes
+
+A note is the secret needed to spend deposited funds:
+
+```
+vx2-<amountHex>-<privateKeyHex>-<blindingHex>[-<mint>]
+```
+
+The mint suffix is omitted for SOL. Anyone holding the note can withdraw it, so store it safely. Notes from the previous (fixed-denomination) pool are not compatible; `sdk.isLegacyNote(note)` detects them.
 
-Derives a note-encryption key from a wallet signature and stores it on the SDK instance (`sdk.encryptKey`). **Required before any deposit that uses on-chain note backup** (`onChainBackup: true`, including `veilixTransfer`).
+```ts
+const parsed = sdk.parseSecretNote(note); // { amount, mint, commitment, commitmentHex, ... }
+const status = await sdk.getNoteStatus(note); // { deposited, index, spent, spentIn, ... }
+```
 
-The wallet signs the message `veilix:notes:v1`. Accepts a backend `Keypair` or a frontend wallet adapter with `signMessage`.
+---
+
+## `getEncryptionKey`
+
+Derives a note-encryption key from a wallet signature and stores it on the SDK instance (`sdk.encryptKey`). The wallet signs the message `veilix:notes:v1`. Accepts a backend `Keypair` or a frontend wallet adapter with `signMessage`.
 
 ```ts
 await sdk.getEncryptionKey(wallet);
-// sdk.encryptKey is now set
 ```
 
-The key is used to encrypt secret notes before they are stored on-chain via `backupNotes`, so you can recover notes later from the same wallet.
+The key is used to:
 
----
+- seal a deposit's note into its on-chain encrypted output (`onChainBackup: true`), and
+- seal the change note of a partial withdrawal,
 
-## `buildDepositTx`
+so that `sdk.scanOwnedNotes()` can recover every unspent note of the wallet later.
+
+---
 
-Builds an unsigned deposit transaction for a pre-generated secret note.
+## Deposit
 
-### 1. Generate deposit parameters
+### 1. Generate a note
 
 ```ts
-// 1 SOL deposit (lamports)
-const { note } = sdk.generateDepositParams(1_000_000_000n, null);
+// 1.5 SOL (lamports)
+const { note } = sdk.generateDepositParams(1_500_000_000n, null);
 
-// SPL token deposit — pass the token mint
+// SPL token — pass the token mint and base units
 const usdcMint = sdk.getTokenMint("USDC");
-const { note: usdcNote } = sdk.generateDepositParams(1_000_000n, usdcMint);
+const { note: usdcNote } = sdk.generateDepositParams(
+  sdk.parseAmountToBaseUnits("25.5", 6),
+  usdcMint
+);
 ```
 
-Deposit amounts must match [supported pool denominations](#supported-deposit-denominations) for each token.
-
-### 2. Build the transaction
+### 2. Build, sign and send
 
 ```ts
 await sdk.getEncryptionKey(wallet); // required when onChainBackup is true
 
-const { tx, note } = await sdk.buildDepositTx({
+const tx = await sdk.buildDepositTx({
   senderPublicKey: wallet.publicKey,
   note,
-  onChainBackup: true,       // encrypt and store note on-chain (recommended)
-  computeUnitPrice: 50_000,  // optional priority fee
-  tempSigner: tempSignerPublicKey // to prevent ix assertion in browser
+  onChainBackup: true,      // recover the note later with scanOwnedNotes (recommended)
+  computeUnitPrice: 50_000, // optional priority fee (micro-lamports / CU)
 });
+
+const signed = await wallet.signTransaction(tx); // VersionedTransaction
+const signature = await connection.sendRawTransaction(signed.serialize());
 ```
 
-Sign and send the returned `tx` with your wallet. **Save the returned `note`** — it is required to withdraw later.
+`buildDepositTx` generates the deposit ZK proof (a few seconds) and returns an unsigned `VersionedTransaction`. **Save the `note` before sending** — it is required to withdraw.
 
 | Parameter | Description |
 |-----------|-------------|
 | `senderPublicKey` | Depositor's public key |
 | `note` | Secret note from `generateDepositParams` |
-| `onChainBackup` | When `true`, encrypts the note and adds a `backupNotes` instruction (requires `getEncryptionKey`) |
-| `computeUnitPrice` | Priority fee in micro-lamports (default `50000`) |
+| `onChainBackup` | Seal the note into the deposit's encrypted output (requires `getEncryptionKey`) |
+| `computeUnitPrice` | Priority fee in micro-lamports (default `5000`) |
+| `computeUnitLimit` | Compute unit limit override |
+
+The pool's per-deposit cap is available via `(await sdk.fetchTreeAccount(mint)).maxDepositAmount`.
 
 ---
 
 ## `withdraw`
 
-Withdraws funds from the privacy pool to a recipient using a secret note from a prior deposit. The SDK:
+Withdraws a note (or part of it) to a recipient through a relayer. The SDK:
 
 1. Validates the recipient against the risk API
-2. Fetches Merkle commitments from the indexer
-3. Generates a ZK withdraw proof
-4. Submits the proof to a relayer (chosen at random, or by index)
+2. Locates the note in the indexer and checks it is unspent
+3. Rebuilds the Merkle tree and generates the ZK proof
+4. Submits the proof to a relayer (random, by index, or by URL)
 5. Polls until the relayer confirms the on-chain transaction
 
 ```ts
-const result = await sdk.withdraw({
-    note: "veilix-1-...",           // secret note from deposit
-    recipient: "RecipientPubkey...", // withdrawal destination
-  },
-  relayerIdx: -1,                   // optional — random relayer when omitted
-);
+// Full note
+const result = await sdk.withdraw({ note, recipient: "RecipientPubkey..." });
+
+// Partial: withdraw 0.4 SOL, keep the rest as a change note
+const partial = await sdk.withdraw({
+  note,
+  recipient: "RecipientPubkey...",
+  amount: 400_000_000n,
+});
+console.log(partial.changeNote); // save it — it holds the remaining funds
 
-console.log(result.txHash);  // on-chain transaction signature
-console.log(result.status);  // "success" | "failed"
+console.log(result.status); // "success" | "failed"
+console.log(result.txHash); // withdraw transaction signature
+console.log(result.fee);    // total fee in base units (relayer + platform)
 ```
 
 | Parameter | Description |
 |-----------|-------------|
-| `note` | Secret note from the original deposit |
+| `note` | Secret note to spend |
 | `recipient` | Recipient public key (`PublicKey` or base58 string) |
-| `relayerIdx` | Optional index into `sdk.relayers` |
+| `amount` | Optional base-unit amount before fees; defaults to the full note |
+| `relayerUrl` | Optional relayer URL (otherwise `relayerIdx` or random) |
+| second argument `relayerIdx` | Optional index into `sdk.relayers` |
+
+The recipient receives `amount - fee`. When `sdk.encryptKey` is set, the change note is also sealed on-chain so `scanOwnedNotes` can find it.
+
+---
+
+## `scanOwnedNotes`
+
+Recovers the wallet's notes by trial-decrypting the pool's encrypted outputs with `sdk.encryptKey`:
+
+```ts
+await sdk.getEncryptionKey(wallet);
+const notes = await sdk.scanOwnedNotes(); // unspent notes, SOL + configured tokens
+// options: { mints: [null, usdcMint], includeSpent: true }
+```
 
-Withdraw fees are calculated automatically from the relayer fee and on-chain platform fee.
+Each entry is a `NoteStatus` with the re-encoded `note`, `amount`, `mint`, `index` and spend state.
 
 ---
 
 ## `veilixTransfer`
 
-End-to-end private transfer: deposit into the pool (split across supported denominations), then withdraw each successful note to the recipient. Handles signing, sending, and settlement automatically.
+End-to-end private transfer: deposits one note per item, then withdraws each note to its recipient via the indexer `/submit` queue. Handles proving, signing, sending, and settlement.
 
-**Requires keep open the window till get response for correct work**
+**Keep the window open until it resolves.**
 
 ```ts
 import { PublicKey } from "@solana/web3.js";
 
 const result = await sdk.veilixTransfer(
   [
-    {
-      mint: new PublicKey(sdk.getTokenMint("USDC")),
-      amount: "25",                              // human-readable amount
-      recipient: new PublicKey("RecipientPubkey..."),
-    },
-    {
-      mint: new PublicKey(sdk.getTokenMints().Solana),
-      amount: "1.5",
-      recipient: new PublicKey("AnotherRecipient..."),
-    },
+    { mint: new PublicKey(sdk.getTokenMint("USDC")), amount: "25", recipient: new PublicKey("Recipient...") },
+    { mint: new PublicKey(sdk.getTokenMints().Solana), amount: "1.5", recipient: new PublicKey("Another...") },
   ],
+  { uniqueRelayer: false, onChainBackup: true, downloadNotes: true }
 );
 
 if (result.error) {
   console.log("Deposit failures:", result.depositFailed);
-  console.log("Withdraw failures:", result.withdrawFailed);
+  console.log("Withdraw failures:", result.withdrawFailed); // include the note, still spendable
 }
 ```
 
-| Field | Description |
-|-------|-------------|
-| `items[].mint` | Token mint to transfer |
-| `items[].amount` | Human-readable amount (e.g. `"1.5"` SOL) |
-| `items[].recipient` | Withdrawal destination for that transfer |
+| Option | Default | Description |
+|--------|---------|-------------|
+| `uniqueRelayer` | `false` | Use one random relayer for every withdraw |
+| `onChainBackup` | `true` when `encryptKey` is set | Seal each note into its deposit |
+| `downloadNotes` | `true` | Download the notes as CSV (browser) before sending |
 
-The SDK splits each amount into the nearest supported deposit denominations, builds and sends deposit transactions, waits for settlement, then withdraws each note to its recipient. Partial failures are reported in `depositFailed` and `withdrawFailed` without throwing.
+Partial failures are reported without throwing; `result.notes` lists every note created.
 
 ---
 
 ## `getQuote`
 
-Fetches a withdraw fee quote from the Veilix indexer before executing a withdrawal. Returns estimated relayer fees, recipient amount, ETA, and how the amount splits across denominations.
+Fetches a withdraw fee quote from the indexer.
 
 ```ts
 const { quote } = await sdk.getQuote({
-  amount: 1.5,                    // human-readable amount
-  amountLamports: 1_500_000_000,  // same amount in smallest units
-  recipient: "RecipientPubkey...",
-  asset: "SOL",                   // optional — default "SOL"
-});
-
-console.log(quote.recipientAmount);  // amount recipient receives after fees
-console.log(quote.totalRelayerFee);
-console.log(quote.etaSeconds);
-console.log(quote.splits);           // per-denomination breakdown
-console.log(quote.platformFee);      // platform fee (added by SDK)
-```
-
-| Parameter | Description |
-|-----------|-------------|
-| `amount` | Human-readable transfer/withdraw amount |
-| `amountLamports` | Amount in smallest token units |
-| `recipient` | Intended withdrawal recipient |
-| `asset` | Indexer asset label (default `"SOL"`) |
-| `network` | Optional cluster override |
-
-`getQuote` is also exported as a standalone function but requires an initialized SDK context.
-
----
-
-## Typical flows
-
-### Deposit and withdraw
-
-```ts
-const sdk = await VeilixSDK.create({ rpcEndpoint, wallet, network: "mainnet" });
-
-await sdk.getEncryptionKey(wallet);
-
-const { note } = sdk.generateDepositParams(1_000_000_000n, null);
-const { tx } = await sdk.buildDepositTx({
-  senderPublicKey: wallet.publicKey,
-  note,
-  onChainBackup: true,
+  amount: "1.5",          // or amountRaw: "1500000000"
+  asset: "SOL",           // "SOL" or a token mint
+  recipient: "Recipient...",
 });
 
-// sign and send tx...
-
-const { txHash } = await sdk.withdraw({
-  note,
-  recipient: "RecipientPubkey...",
-});
+console.log(quote.recipientAmount, quote.fee, quote.relayerFee, quote.platformFee);
+console.log(quote.relayer.url, quote.etaSeconds);
 ```
 
-### Quote before withdraw
-
-```ts
-const { quote } = await sdk.getQuote({
-  amount: 1,
-  amountLamports: 1_000_000_000,
-  recipient: "RecipientPubkey...",
-});
-
-console.log(`Recipient receives ~${quote.recipientAmount} SOL`);
-
-await sdk.withdraw({ note, recipient: "RecipientPubkey..." });
-```
+For the exact fee the program will enforce, use `sdk.computeWithdrawFee(amount, relayerFeePercent, await sdk.fetchPlatformFeeWallets())`.
 
 ---
 
-## Supported deposit denominations
-
-Amounts must decompose exactly into these pool denominations:
-
-| Token | Denominations | Mint Address (mainnet) |
-|-------|---------------|---------------|
-| SOL | 0.1, 1, 5, 10, 50, 100, 500 | |
-| USDC | 1, 10, 50, 100, 1000, 10000, 100000, 1000000 | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
-| Veilix | 10000,50000,100000,500000,1000000,10000000 |  |
-| Bitcoin | 0.01, 0.05, 0.1, 0.5, 1, 5 | 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh |
-| Ethereum (coming soon) | 0.1, 1, 10, 50, 100, 500 | 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs |
-
-Use `sdk.getDepositAmounts("Solana")` (or another symbol) to retrieve the list programmatically.
-
----
+## Circuit artifacts
 
+In the browser the SDK loads `withdraw.wasm` / `withdraw.zkey` from the pinned CDN (SHA-256 verified) unless `circuitPathsBase` points elsewhere. With Vite, `veilix-sdk/vite` serves them from `node_modules` during development. In Node the files are read from the package's `dist/circuits`.