@cloak.dev/sdk 0.2.0 → 0.2.2-staging.9ffa9f5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -5,13 +5,13 @@ per-mint pool, send privately inside the pool, withdraw to any address, or swap
 USDC/USDT with the output landing in a public token account. Groth16 proofs are generated
 client-side (snarkjs) and verified on-chain by the Cloak program.
 
-Version 0.2.0 targets the mainnet program deployed on 2026-08-24 and the ceremony-frozen
+Version 0.2.2 targets the mainnet program deployed on 2026-08-24 and the ceremony-frozen
 `cloak-transaction-0.2.0` circuit bundle. See [Version and compatibility](#version-and-compatibility).
 
 ## Installation
 
 ```bash
-npm install @cloak.dev/sdk @solana/web3.js
+npm install @cloak.dev/sdk@^0.2.2 @solana/web3.js
 # swaps and SPL pools also need:
 npm install @solana/spl-token
 ```
@@ -26,25 +26,44 @@ Node >= 18. Ships ESM and CJS builds with type declarations. Runs in Node and in
 | Setting | Value |
 | --- | --- |
 | Program | `zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW` (`CLOAK_PROGRAM_ID`) |
-| Relay | `https://api.cloak.ag`, passed as `relayUrl` or via `CLOAK_RELAY_URL` (see below) |
+| Cloak endpoint | `https://api.cloak.ag` — pinned into the build, not configurable (see below) |
 | Circuits | `https://storage.googleapis.com/cloak-circuits/circuits/0.2.0` (the SDK default) |
 | Pools | WSOL (`NATIVE_SOL_MINT`), USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, USDT `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` |
 | RPC | any mainnet RPC; use `new Connection(url, "confirmed")` |
 
-The relay URL is never defaulted. `transact` resolves it from the `relayUrl` option, then from
-`CLOAK_RELAY_URL`, and with neither set it throws before anything is signed or sent. This is
-deliberate: a script that forgets the option must not ship its proof to production. Name production
-explicitly:
+The endpoint is fixed when the SDK is built and cannot be changed by a consumer. A published build
+carries `RELAY_ORIGIN_ALLOWLIST` as a compiled-in constant, every request is checked against it
+before it leaves the process, and there is no option, environment variable, or bundler define that
+moves it. Name it by importing the constant rather than typing a host:
 
 ```ts
-relayUrl: "https://api.cloak.ag"
+import { CLOAK_PRODUCTION_RELAY_URL } from "@cloak.dev/sdk";
+
+relayUrl: CLOAK_PRODUCTION_RELAY_URL
+```
+
+It is still never defaulted: omitting the option throws before anything is signed or sent, so a
+script that forgets it cannot ship its proof anywhere. `relayUrl: ""` means the opposite — no
+endpoint at all, so a deposit is signed and submitted by the caller.
+
+A build pinned somewhere else is made by editing source and rebuilding, which is also what makes a
+published build unrepointable:
+
+```bash
+# in a checkout of this repo
+$ $EDITOR src/config/relay.ts     # replace the RELAY_ORIGIN_ALLOWLIST entry, do not append
+$ npm run build                   # only needed by consumers that import dist/
 ```
 
+The same edit unlocks the second half of the lock: a build pinned to a non-local origin refuses to
+run against an RPC served by the local machine, and a build pinned to a local origin does not. One
+constant, both behaviours.
+
 Every flow needs it, deposits included: the SDK registers the wallet's viewing key through the relay
 before its first transaction (see [Recovery and discovery](#recovery-and-discovery-viewing-key)),
 deposits fetch the signed risk quote the program requires from `<relayUrl>/range-quote`, and sends,
 withdrawals and swaps are submitted through it. `enforceViewingKeyRegistration: false` skips only the
-registration step (the shipped examples set it on a local fork); it is not a no-relay mode.
+registration step (some of the shipped examples set it on a local fork); it is not a no-relay mode.
 
 Do not expose `programId`, the relay URL or the circuits base as end-user input. Wallet adapters are
 the in-app signer; keypair files belong to scripts only.
@@ -55,10 +74,14 @@ The same SDK runs against a devnet or local deployment by pointing the three coo
 
 ```bash
 SOLANA_RPC_URL=https://api.devnet.solana.com   # or http://127.0.0.1:8899 for a local fork
-CLOAK_RELAY_URL=<relay serving that deployment>
+CLOAK_RELAY_URL=<endpoint serving that deployment>  # read by examples/ and scripts/, NOT by the SDK
 CLOAK_PROGRAM_ID=<program id of that deployment>   # examples read this; pass it as programId in your code
 ```
 
+`CLOAK_RELAY_URL` configures the shipped examples and scripts, which pass its value as `relayUrl`.
+The SDK itself does not read it: the endpoint a build may talk to comes from `src/config/relay.ts`,
+so pointing at a devnet or local deployment means editing that file in a checkout and building it.
+
 The shipped examples default to a local fork (`http://127.0.0.1:8899`) with a local relay
 (`http://127.0.0.1:5500`); see [Examples](#examples).
 
@@ -188,11 +211,104 @@ address lookup tables); deposits use either depending on the path taken. `signMe
 unless `enforceViewingKeyRegistration: false` is set; without it the call fails with
 "Viewing key registration is mandatory: signMessage (wallet) or depositorKeypair is required."
 
+A deposit is signed by the wallet and goes straight to chain. A private send, a withdrawal and a
+swap are submitted for you, and each one carries an authenticated sender — so those three need
+`signMessage` and `walletPublicKey` even when `enforceViewingKeyRegistration` is off:
+
+```ts
+// Private send (externalAmount 0) from a wallet adapter. Same for fullWithdraw / partialWithdraw
+// (externalAmount < 0) and swapUtxo / swapWithChange.
+await transact(
+  { inputUtxos, outputUtxos, externalAmount: BigInt(0) },
+  {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    relayUrl,
+    signMessage: (message) => wallet.signMessage(message),
+    walletPublicKey: wallet.publicKey, // becomes the authenticated sender
+    chainNoteViewingKeyNk: nk,
+  },
+);
+```
+
+`signMessage` must return the raw 64-byte ed25519 detached signature over the bytes it is given;
+adapters that re-encode or wrap the result are rejected by name. `walletPublicKey` must be the end
+user's own wallet — it is the identity the transaction is authenticated as. Passing neither a
+`depositorKeypair` nor both of these fails immediately, before any proof is generated.
+
+`depositorKeypair`, `walletPublicKey` and `depositorPublicKey` are three names for the SAME end
+user. That one key is the request's authenticated sender, the key screened for sanctions, and the
+wallet a viewing key is registered against, so setting two of the names to two different keys would
+screen one person and authenticate another. Passing two different wallets is refused at the call.
+
+### The approval window
+
+The request's timestamp is stamped when the bytes are built, because it is part of what the wallet
+signs, and the relay accepts a first-use request for 300 seconds from that moment. An approval left
+sitting in a hardware wallet past that window cannot be rescued by re-stamping it, so the SDK stops
+there and says so instead of shipping a request that can only come back as a 401. Retry the
+operation and approve the prompt when it appears.
+
+`auth_issued_at` comes from the machine's own clock, and the relay rejects anything more than 30
+seconds ahead of its own. A user whose clock is fast cannot authenticate at all until it is
+corrected; `explainRelayAuthRejection` turns that rejection, and the rest of the relay's 401s, into
+a sentence that names the cause. The SDK applies it to its own relay errors already.
+
+A private send or withdrawal signs exactly ONCE: every network retry re-POSTs the same signed
+bytes, so the user sees one prompt. A swap re-proves on every retry, so each retry needs its own
+approval; `maxWalletApprovals` (default 5) bounds how many times one swap may interrupt the user,
+independently of `maxRootRetries`. A `depositorKeypair` signs silently and is unaffected.
+
+### Authenticating a call you build yourself
+
+To authenticate a call you build yourself (a swap retry that posts only `retry_request_id`, for
+example), use the exported primitives rather than re-deriving the scheme:
+
+```ts
+import { buildRelayAuthPreimage, TRANSACT_SWAP_AUTH_FIELDS } from "@cloak.dev/sdk";
+
+const body = { retry_request_id: requestId, slippage_bps: 500 };
+const preimage = buildRelayAuthPreimage(
+  "/transact_swap",
+  CLOAK_PROGRAM_ID,
+  body,
+  wallet.publicKey,
+  undefined,
+  TRANSACT_SWAP_AUTH_FIELDS,
+);
+const signature = await wallet.signMessage(preimage.message);
+
+const payload = {
+  ...body,
+  sender: preimage.sender,
+  auth_issued_at: preimage.auth_issued_at,
+  auth_nonce: preimage.auth_nonce,
+  auth_signature: Buffer.from(signature).toString("base64"),
+};
+```
+
+Reuse one `preimage` for every retry of the same logical request; rebuilding it produces a new
+nonce and a new request.
+
+`slippage_bps` in that snippet is not decoration. Every other field in both lists is optional on
+the relay side, so omitting one and signing it as `null` matches what the relay signs. `slippage_bps`
+is the exception: it is not optional, and a request that omits it is read by the relay as **500**.
+Omit it and you sign `null` while the relay signs `500`, the digests differ, and the answer is a 401
+that points at nothing. Set it explicitly, to the same value the body carries. The SDK's own swap
+path always does; a hand-built body that leaves it out is refused before it is signed.
+
+`canonicalJson` is exported for the same reason, and it is the SDK's half of a byte-for-byte
+agreement with one Rust function over one fixed schema: ASCII keys over strings, small unsigned
+integers, booleans, nulls, arrays and plain objects. Amounts travel as decimal strings, not numbers,
+because JavaScript and `serde_json` do not spell every number the same way. Anything outside that
+schema that could serialize differently on the two sides is refused rather than silently signed.
+
 ## The UTXO model
 
 - A shielded balance is a set of notes (`Utxo`): `{ amount, keypair, blinding, mintAddress, index?, commitment? }`.
   Amounts are `bigint` in base units (lamports, or 10^-6 for USDC/USDT).
-- Every transaction is 2-in / 2-out. Pad unused slots with `createZeroUtxo(mint)`.
+- Every transaction is 2-in / 2-out; `transact` pads unused slots with zero notes for you.
+  `createZeroUtxo(mint)` is exported if you want to pass them explicitly.
 - `externalAmount > 0` is a deposit (funds enter from `depositor`), `< 0` is a withdrawal to
   `recipient`, `0` is a private send inside the pool.
 - Pools are per mint. All inputs and outputs of one transaction live in the same pool;
@@ -260,8 +376,11 @@ await transact(
 ```
 
 Minimum SPL deposit is 1.00 token. SOL deposits fit in a single v0 packet with the production
-lookup table; SPL deposits currently still create a small supplemental lookup table
-(about 0.0056 SOL rent, reclaimable by the depositor). Details: [docs/DEPOSIT-SIZE-NOTES.md](docs/DEPOSIT-SIZE-NOTES.md).
+lookup table; SPL deposits by default create a small depositor-signed supplemental lookup table
+(about 0.0056 SOL rent, reclaimable by the depositor), which costs a second wallet signature. Set
+`relaySupplementalAlt: true` in `TransactOptions` to ask the relay to extend its own shared lookup
+table instead, cutting an SPL deposit to one signature; off by default, and any relay-side failure
+falls back automatically to the depositor-signed path above with no caller action needed.
 
 ### Shielded swap (SOL to USDC/USDT)
 
@@ -343,10 +462,10 @@ notes also derive their secrets from it, which is what makes key-only recovery p
 it with the same care as the spend key.
 
 Before a wallet's first transaction the SDK registers `nk` with the relay for compliance scanning:
-it requests a challenge from `<relayUrl>/viewing-key/challenge`, signs it with `signMessage` (wallet)
-or `depositorKeypair`, and posts `nk` with the signature to `<relayUrl>/viewing-key/register`.
-Nothing viewing-key related is written on-chain. The step is on by default;
-`enforceViewingKeyRegistration: false` disables it.
+it signs a one-time challenge with `signMessage` (wallet) or `depositorKeypair` and submits `nk`
+with that signature. Nothing viewing-key related is written on-chain. The step is on by default;
+`enforceViewingKeyRegistration: false` disables it. `registerViewingKey(relayUrl, userPubkey, nk,
+signMessage)` performs the same registration on its own.
 
 ```ts
 import { scanTransactions, fetchCommitments, type Utxo } from "@cloak.dev/sdk";
@@ -365,8 +484,9 @@ scan.deliveredNotes;        // notes sent to this wallet (amount + blinding; the
 scan.transactions;          // history rows for compliance reporting
 ```
 
-`scanRecipientDeliveryNotes` returns only the delivered notes. Deposit recovery applies to deposits
-built with `createRecoverableDepositUtxo` (the default in the examples); a deposit built with
+`scanRecipientDeliveryNotes` does the delivery sweep alone, returning `{ notes, rpcCalls }`
+instead of a full scan result. Deposit recovery applies to deposits built with
+`createRecoverableDepositUtxo` (the default in the examples); a deposit built with
 `createUtxo` has a random blinding that is written nowhere and appears as history only.
 
 A recovered or delivered note needs its leaf index before it can be spent. Look it up by commitment.
@@ -417,14 +537,12 @@ const deliveredNote: Utxo = {
 
 ## Nullifiers and spent checks
 
-Two exports share a name and are not interchangeable:
-
-- `computeUtxoNullifier(utxo)` is the circuit's scheme: `Poseidon(commitment, index, signature)`.
-  This is the value the program records when a note is spent. Use it for spent checks.
-- `computeNullifier(skSpend, leafIndex)` is `Poseidon(sk0, sk1, leafIndex)` from the legacy
-  `withdraw_regular` circuit. It does not match anything the 0.2.0 program stores.
+The nullifier export is `computeUtxoNullifier(utxo)`, the circuit's scheme:
+`Poseidon(commitment, index, signature)`. This is the value the program records when a note is
+spent, so it is what a spent check compares against. It is async and requires `utxo.index` to be
+set.
 
-Prefer the helpers, which use the UTXO scheme:
+Prefer the helpers, which derive the nullifier and check the on-chain PDA for you:
 
 ```ts
 import { verifyUtxos, preflightNullifiers } from "@cloak.dev/sdk";
@@ -450,7 +568,7 @@ Deposits and private sends carry no protocol fee.
 A withdrawal or swap must exceed its fee or the program rejects it; deposits below the minimum are
 rejected with `DepositTooSmall`.
 
-`utils/fees.ts` mirrors the SOL pool for estimates in the UI:
+`src/shared/fees.ts` mirrors the SOL pool for estimates in the UI:
 
 ```ts
 import { calculateFeeBigint, getDistributableAmount, isWithdrawAmountSufficient } from "@cloak.dev/sdk";
@@ -462,78 +580,105 @@ isWithdrawAmountSufficient(6_000_000n);  // true: 0.006 SOL covers the 0.005018
 
 For USDC/USDT compute `450_000n + amount * 3n / 1000n`. Treat these as estimates: the deployed
 `PoolConfig` is the source of truth. Solana transaction fees and, for SPL deposits, the supplemental
-lookup-table rent are separate.
+lookup-table rent are separate (see `relaySupplementalAlt` under [SPL pools](#spl-pools-usdc-usdt)
+for cutting that rent's signature cost).
 
 ## Circuit artifacts
 
 Proving uses the `transaction` circuit from bundle `cloak-transaction-0.2.0` (multi-party ceremony,
 6 contributors plus a public final beacon; 42,672 constraints, 9 public inputs). The verifying key is
-embedded in the program.
+embedded in the program, so the SDK never fetches it; for the record, the exported
+`transaction.vkey.json` from the same ceremony is SHA-256
+`deb40e7b94eae17db2975d23dcf26c26db2a36a4f02d14a25830dee3e88fb93c`.
 
 | Artifact | SHA-256 |
 | --- | --- |
 | `transaction_js/transaction.wasm` | `02ec02e954ae3932827ad9de51afa597ca95569aa97fec8410879c937a58aa2b` |
 | `transaction_final.zkey` | `9da7db8cb1370fc497d36a0365f1f107ab0b0c13ca66fa9f0287e5f96ee68d25` |
-| `transaction.vkey.json` | `deb40e7b94eae17db2975d23dcf26c26db2a36a4f02d14a25830dee3e88fb93c` |
 
-The SDK downloads the artifacts once per process from
+The SDK downloads both artifacts once per process from
 `DEFAULT_TRANSACTION_CIRCUITS_URL` (`https://storage.googleapis.com/cloak-circuits/circuits/0.2.0`),
 hashes them, and refuses to prove if any digest differs from the pinned values. No configuration is
 needed for mainnet.
 
-To serve the artifacts yourself (a mirror or a local directory containing
-`transaction_js/transaction.wasm` and `transaction_final.zkey` with the same digests):
+To load the artifacts from a local directory instead (an air-gapped machine, a React Native bundle,
+or the ceremony output — the directory must contain `transaction_js/transaction.wasm` and
+`transaction_final.zkey` with the same digests):
 
 ```ts
 import { resolveCircuitsBase, setCircuitsPath } from "@cloak.dev/sdk";
 
-// explicit argument, else CLOAK_CIRCUITS_PATH / CLOAK_CIRCUITS, else the pinned default
+// explicit argument, else the pinned default; no environment variable is consulted
 setCircuitsPath(resolveCircuitsBase());
+setCircuitsPath("/opt/cloak/ceremony-0.2.0"); // or a local directory you control
 ```
 
 Never write the artifact URL out by hand: the version segment and the digests are declared together
-in `src/config/circuit-release.ts` so they cannot drift.
+in `src/proving/circuits.ts` so they cannot drift.
+
+Where the artifacts may be read from is fixed when the SDK is built. `transaction.wasm` is the
+witness generator, so it is handed your spend key, your note secrets, the amounts and the recipient
+— a mirror on another host is therefore not accepted, and the SHA-256 check over the bytes cannot be
+switched off by any option or environment variable. A local directory is accepted (nothing leaves
+the machine, and the digest check still decides whether the bytes are usable); an `http(s)` base
+must be the bundle base this build pins. To point a build somewhere else, edit
+`RELAY_ORIGIN_ALLOWLIST` in `src/config/relay.ts` and rebuild — the one edit that also unlocks the
+relay endpoint and the localhost-RPC check.
 
 ## Version and compatibility
 
-- SDK 0.2.0 pairs with the mainnet program at `zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW`
-  (deployed 2026-08-24) and the 0.2.0 circuit bundle. All flows in this README were exercised on
+- SDK 0.2.2 pairs with the mainnet program at `zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW`
+  (deployed 2026-08-24) and the 0.2.0 circuit bundle — the program and circuit bundle are unchanged
+  since 0.2.0; only the SDK package version has moved. All flows in this README were exercised on
   mainnet on 2026-08-25: deposit, private send and withdraw on SOL, USDC and USDT; swaps SOL to
   USDC and USDT; viewing-key discovery followed by a spend; keypair-only deposit recovery.
+- 0.2.2 adds the opt-in `TransactOptions.relaySupplementalAlt` (see [SPL pools](#spl-pools-usdc-usdt)):
+  off by default, and existing behavior is unchanged when it is left unset.
 - Proofs generated with the 0.1.x circuits are rejected by the mainnet program. SDK 0.1.x builds
-  (which ship the 0.1.0 bundle) are not usable against it; upgrade to 0.2.0.
-- The note-based `CloakSDK` class (`deposit` / `withdraw` / `send` / `swap` on `CloakNote`) targets
-  the pre-0.2.0 instruction layout and the unpublished 0.1.0 `withdraw_*` circuits. It is still
-  exported but does not work against the current program. Use the UTXO API above.
+  (which ship the 0.1.0 bundle) are not usable against it; upgrade to 0.2.x.
+- The note-based `CloakSDK` class is removed in 0.2.0. It targeted the pre-0.2.0 instruction layout
+  and the unpublished 0.1.0 `withdraw_*` circuits, so it could not work against the current program.
+  Use the UTXO API above: `transact`, `transfer`, `partialWithdraw`, `fullWithdraw`, `swapUtxo`.
 
 ## Examples
 
 ```bash
-npm run example:fast-send          # deposit SOL, withdraw to a recipient
-npm run example:transfer           # deposit, private send, recipient withdraw
-npm run example:fast-usdc-send     # deposit SOL, swap to USDC, deposit USDC, withdraw USDC
-npm run example:usdc-pool-transfer # USDC pool: A deposits, sends to B, B spends
-npm run example:swap               # SOL -> USDC swap with interactive route retry
-npm run example:swap-usdc          # same, with the canonical swap markers
+# SOL pool
+npm run example:deposit            # move lamports into the shielded SOL pool
+npm run example:private-send       # shield-to-shield send the recipient can discover
+npm run example:withdraw           # partial withdraw, then full withdraw of the change
+npm run example:swap               # SOL to USDC through Jupiter
+
+# SPL pools (USDC, USDT). There is no SPL swap: swap input is wSOL-locked.
+npm run example:spl-deposit
+npm run example:spl-private-send
+npm run example:spl-withdraw
+
+# Not pool specific
+npm run example:viewing-keys       # derive a viewing key, register it, read your history
+
+# Swap variants
+npm run example:swap-usdc          # same swap, with the canonical swap markers
 npm run example:swap-brz           # BRZ with automatic USDC fallback
-npm run example:swap-recovery      # pending / timed-out swap handling
-npm run example:history-scan       # every flow, then full and incremental viewing-key scans
-npm run test:examples              # dry-run all of the above (no wallet, no RPC)
+
+npm run test:examples              # dry-run all eight (no wallet, no RPC)
 ```
 
+Examples log by default. Set `CLOAK_DEBUG=0` to silence them.
+
 Environment read by the examples:
 
 | Variable | Default |
 | --- | --- |
 | `SOLANA_RPC_URL` | `http://127.0.0.1:8899` (local fork) |
-| `CLOAK_RELAY_URL` | `http://127.0.0.1:5500` (local relay) |
+| `CLOAK_RELAY_URL` | `http://127.0.0.1:5500` (local endpoint) — read by the examples, not by the SDK; it must name an origin the SDK build is pinned to |
 | `CLOAK_PROGRAM_ID` | `CLOAK_PROGRAM_ID` |
-| `CLOAK_CIRCUITS_PATH` | the pinned 0.2.0 bundle |
 | `CLOAK_ALT_ADDRESSES` | unset; the production lookup tables are resolved automatically |
 
 The examples fund throwaway keypairs from `~/.config/solana/id.json` and print stable
-`FULL_SIG|<example>|<step>|<signature>` markers. They import `@cloak.ag/sdk`, which
-`tsconfig.json` maps to `src/index.ts`; outside this repo import `@cloak.dev/sdk`.
+`FULL_SIG|<example>|<step>|<signature>` markers. They import `@cloak.dev/sdk`, the published
+package name; inside this repo `tsconfig.json` maps that specifier to `src/index.ts` so the
+examples run against source.
 
 ## Error handling
 
@@ -573,14 +718,13 @@ npm run verify:dist    # dist is byte-identical to a fresh build
 npm run test:examples  # dry-run the examples
 ```
 
-Notes: [docs/DEPOSIT-SIZE-NOTES.md](docs/DEPOSIT-SIZE-NOTES.md) (deposit transaction size,
-confirmed-tree reads, supplemental lookup tables).
+Notes: `docs/DEPOSIT-SIZE-NOTES.md` (deposit transaction size, confirmed-tree reads,
+supplemental lookup tables), `docs/transact-split.md` (how `flows/transact.ts` is split).
 
 ## Links
 
 - Website: [https://cloak.ag](https://cloak.ag)
 - Documentation: [https://docs.cloak.ag](https://docs.cloak.ag)
-- GitHub: [https://github.com/cloak-ag/sdk](https://github.com/cloak-ag/sdk)
 
 ## License