@cloak.dev/sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,4 +1,4 @@
-# @cloak.ag/sdk
+# @cloak.dev/sdk
 
 TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zero-knowledge proofs.
 
@@ -14,11 +14,11 @@ TypeScript SDK for the Cloak Protocol - Private transactions on Solana using zer
 ## Installation
 
 ```bash
-npm install @cloak.ag/sdk @solana/web3.js
+npm install @cloak.dev/sdk @solana/web3.js
 # or
-yarn add @cloak.ag/sdk @solana/web3.js
+yarn add @cloak.dev/sdk @solana/web3.js
 # or
-pnpm add @cloak.ag/sdk @solana/web3.js
+pnpm add @cloak.dev/sdk @solana/web3.js
 ```
 
 **Note**: For swap functionality, you'll also need `@solana/spl-token`:
@@ -28,12 +28,101 @@ npm install @solana/spl-token
 
 ## Quick Start
 
-### Risk Quote Configuration (Recommended)
+### SDK Defaults (Recommended)
 
-- Default production flow: set `CLOAK_RELAY_URL` and let relay handle Range quoting.
-- Keep `RANGE_API_KEY` only in relay/service backend, not in SDK clients.
-- SDK auto-uses `${CLOAK_RELAY_URL}/range-quote` when `relayUrl` is provided.
-- SDK-side `rangeApiKey` exists only as a server-side fallback (no-relay scenarios).
+- Standard integrations should use SDK defaults for program, relay, and circuits.
+- Do not expose protocol-level config (`programId`, relay URL, circuits URL) as end-user input.
+- `transact`, `partialWithdraw`, and `fullWithdraw` already include stale-root retry handling.
+- For simple CLI sends, require only `SOLANA_RPC_URL` and `KEYPAIR_PATH`.
+
+### Minimal Private SOL Send (Single File, Keypair)
+
+Use this contract for one-shot scripts and AI-generated snippets.
+
+```ts
+import { readFileSync } from "fs";
+import {
+  CLOAK_PROGRAM_ID,
+  NATIVE_SOL_MINT,
+  createUtxo,
+  createZeroUtxo,
+  fullWithdraw,
+  generateUtxoKeypair,
+  transact,
+} from "@cloak.dev/sdk";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+
+async function main() {
+  const [recipientArg, lamportsArg] = process.argv.slice(2);
+  if (!recipientArg || !lamportsArg) {
+    throw new Error("Usage: npx tsx send-sol-private.ts <recipientPubkey> <lamports>");
+  }
+
+  const rpcUrl = process.env.SOLANA_RPC_URL;
+  const keypairPath = process.env.KEYPAIR_PATH;
+  if (!rpcUrl || !keypairPath) {
+    throw new Error("Set SOLANA_RPC_URL and KEYPAIR_PATH");
+  }
+
+  const connection = new Connection(rpcUrl, "confirmed");
+  const signer = Keypair.fromSecretKey(
+    Uint8Array.from(JSON.parse(readFileSync(keypairPath, "utf8"))),
+  );
+
+  const recipient = new PublicKey(recipientArg);
+  const amountLamports = BigInt(lamportsArg);
+
+  const owner = await generateUtxoKeypair();
+  const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
+
+  const deposited = await transact(
+    {
+      inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],
+      outputUtxos: [output],
+      externalAmount: amountLamports,
+      depositor: signer.publicKey,
+    },
+    {
+      connection,
+      programId: CLOAK_PROGRAM_ID,
+      depositorKeypair: signer,
+      walletPublicKey: signer.publicKey,
+      enforceViewingKeyRegistration: false,
+    },
+  );
+
+  const withdrawn = await fullWithdraw(deposited.outputUtxos, recipient, {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    depositorKeypair: signer,
+    walletPublicKey: signer.publicKey,
+    cachedMerkleTree: deposited.merkleTree,
+    enforceViewingKeyRegistration: false,
+  });
+
+  console.log(withdrawn.signature);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});
+```
+
+Run:
+
+```bash
+SOLANA_RPC_URL="https://api.mainnet-beta.solana.com" \
+KEYPAIR_PATH="/absolute/path/to/id.json" \
+npx tsx send-sol-private.ts <recipientPubkey> <lamports>
+```
+
+Hard rules for minimal scripts:
+
+- Use lamports from CLI (`<lamports>`) and keep transaction math in `bigint`.
+- Use `KEYPAIR_PATH`; do not ask for raw private key env vars.
+- Do not parse SOL decimals with float math (`parseFloat`, `AMOUNT_SOL`).
+- Keep `programId` fixed to `CLOAK_PROGRAM_ID` (no end-user override).
 
 ### Maintained Examples
 
@@ -66,7 +155,7 @@ npm run test:examples
 ### Node.js (with Keypair)
 
 ```typescript
-import { CloakSDK } from "@cloak.ag/sdk";
+import { CloakSDK } from "@cloak.dev/sdk";
 import { Connection, Keypair, PublicKey } from "@solana/web3.js";
 
 // Initialize connection and keypair
@@ -96,7 +185,7 @@ console.log("Withdrawn! TX:", withdrawResult.signature);
 ### React/Next.js (with Wallet Adapter)
 
 ```typescript
-import { CloakSDK } from "@cloak.ag/sdk";
+import { CloakSDK } from "@cloak.dev/sdk";
 import { useWallet, useConnection } from "@solana/wallet-adapter-react";
 import { PublicKey } from "@solana/web3.js";
 
@@ -181,7 +270,7 @@ const result = await sdk.swap(connection, note, recipientPublicKey, {
 Use `getDistributableAmount()` to calculate the amount after fees:
 
 ```typescript
-import { getDistributableAmount } from "@cloak.ag/sdk";
+import { getDistributableAmount } from "@cloak.dev/sdk";
 
 const deposited = 100_000_000; // 0.1 SOL
 const afterFees = getDistributableAmount(deposited); // ~94,700,000 lamports
@@ -245,7 +334,7 @@ sequenceDiagram
 ## Error Handling
 
 ```typescript
-import { CloakError } from "@cloak.ag/sdk";
+import { CloakError } from "@cloak.dev/sdk";
 
 try {
   await sdk.withdraw(connection, note, recipient);

package/dist/index.cjs

@@ -6083,6 +6083,7 @@ function collectLookupCandidatesFromInstructions(instructions, payer, existingAl
 }
 async function createEphemeralALT(connection, depositor, onProgress, additionalAddresses = []) {
   const MAX_ALT_ADDRESSES = 20;
+  const MAX_ALT_CREATE_RETRIES = 3;
   const altAddresses = dedupePubkeys([
     ...getCommonALTAddresses(),
     ...additionalAddresses
@@ -6093,46 +6094,59 @@ async function createEphemeralALT(connection, depositor, onProgress, additionalA
       `ALT address set truncated (${addressesForCreate.length}/${altAddresses.length}); packet savings may be limited.`
     );
   }
-  const slot = await connection.getSlot();
-  const [createIx, altAddress] = import_web37.AddressLookupTableProgram.createLookupTable({
-    authority: depositor.publicKey,
-    payer: depositor.publicKey,
-    recentSlot: slot
-  });
-  const extendIx = import_web37.AddressLookupTableProgram.extendLookupTable({
-    payer: depositor.publicKey,
-    authority: depositor.publicKey,
-    lookupTable: altAddress,
-    addresses: addressesForCreate
-  });
-  const tx = new import_web37.Transaction().add(createIx).add(extendIx);
-  const { blockhash } = await connection.getLatestBlockhash();
-  tx.recentBlockhash = blockhash;
-  tx.feePayer = depositor.publicKey;
-  if (depositor.keypair) {
-    await (0, import_web37.sendAndConfirmTransaction)(connection, tx, [depositor.keypair], { commitment: "confirmed" });
-  } else if (depositor.signTransaction) {
-    const signedTx = await depositor.signTransaction(tx);
-    const sig = await connection.sendRawTransaction(signedTx.serialize());
-    const latestBH = await connection.getLatestBlockhash();
-    await connection.confirmTransaction({ signature: sig, blockhash: latestBH.blockhash, lastValidBlockHeight: latestBH.lastValidBlockHeight }, "confirmed");
-  } else {
-    throw new Error("Cannot create ALT: no signing method provided");
-  }
-  for (let i = 0; i < 30; i++) {
-    await new Promise((r) => setTimeout(r, 500));
-    const result = await connection.getAddressLookupTable(altAddress);
-    if (result.value && result.value.isActive()) {
-      onProgress?.(`ALT created and active: ${altAddress.toBase58()}`);
-      return [result.value];
+  for (let altAttempt = 0; altAttempt < MAX_ALT_CREATE_RETRIES; altAttempt++) {
+    try {
+      const slot = await connection.getSlot("finalized");
+      const [createIx, altAddress] = import_web37.AddressLookupTableProgram.createLookupTable({
+        authority: depositor.publicKey,
+        payer: depositor.publicKey,
+        recentSlot: slot
+      });
+      const extendIx = import_web37.AddressLookupTableProgram.extendLookupTable({
+        payer: depositor.publicKey,
+        authority: depositor.publicKey,
+        lookupTable: altAddress,
+        addresses: addressesForCreate
+      });
+      const tx = new import_web37.Transaction().add(createIx).add(extendIx);
+      const { blockhash } = await connection.getLatestBlockhash();
+      tx.recentBlockhash = blockhash;
+      tx.feePayer = depositor.publicKey;
+      if (depositor.keypair) {
+        await (0, import_web37.sendAndConfirmTransaction)(connection, tx, [depositor.keypair], { commitment: "confirmed" });
+      } else if (depositor.signTransaction) {
+        const signedTx = await depositor.signTransaction(tx);
+        const sig = await connection.sendRawTransaction(signedTx.serialize());
+        const latestBH = await connection.getLatestBlockhash();
+        await connection.confirmTransaction({ signature: sig, blockhash: latestBH.blockhash, lastValidBlockHeight: latestBH.lastValidBlockHeight }, "confirmed");
+      } else {
+        throw new Error("Cannot create ALT: no signing method provided");
+      }
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        const result = await connection.getAddressLookupTable(altAddress);
+        if (result.value && result.value.isActive()) {
+          onProgress?.(`ALT created and active: ${altAddress.toBase58()}`);
+          return [result.value];
+        }
+      }
+      const finalResult = await connection.getAddressLookupTable(altAddress);
+      if (finalResult.value) {
+        onProgress?.("ALT created (activation pending)");
+        return [finalResult.value];
+      }
+      throw new Error("Failed to create ALT: not active after 15 seconds");
+    } catch (err) {
+      const msg = err?.message ?? String(err);
+      if (msg.includes("not a recent slot") && altAttempt < MAX_ALT_CREATE_RETRIES - 1) {
+        onProgress?.(`ALT creation failed (stale slot), retrying (${altAttempt + 2}/${MAX_ALT_CREATE_RETRIES})...`);
+        await new Promise((r) => setTimeout(r, 2e3));
+        continue;
+      }
+      throw err;
     }
   }
-  const finalResult = await connection.getAddressLookupTable(altAddress);
-  if (finalResult.value) {
-    onProgress?.("ALT created (activation pending)");
-    return [finalResult.value];
-  }
-  throw new Error("Failed to create ALT: not active after 15 seconds");
+  throw new Error(`Failed to create ALT after ${MAX_ALT_CREATE_RETRIES} retries`);
 }
 async function submitTransactionDirect(connection, programId, depositor, proofBytes, publicInputsBytes, nullifiers, mint, recipient, riskOracleQueue, riskQuoteUrl, getRiskQuoteInstruction, onProgress, addressLookupTableAccounts, rangeApiKey, encryptedNoteBytes, relayUrl, altAddresses) {
   onProgress?.("Building transaction...");
@@ -6163,6 +6177,10 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     onProgress?.("Creating address lookup table (chain notes require v0 tx to fit)...");
     addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress);
   }
+  if (isDeposit && isSplPool && (!addressLookupTableAccounts || addressLookupTableAccounts.length === 0)) {
+    onProgress?.("Creating address lookup table (SPL deposit requires v0 tx)...");
+    addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress);
+  }
   const publicAmountBytes = publicInputsBytes.slice(32, 40);
   const publicAmountBuffer = Buffer.from(publicAmountBytes);
   const publicAmount = publicAmountBuffer.readBigInt64LE(0);

package/dist/index.js

@@ -5636,6 +5636,7 @@ function collectLookupCandidatesFromInstructions(instructions, payer, existingAl
 }
 async function createEphemeralALT(connection, depositor, onProgress, additionalAddresses = []) {
   const MAX_ALT_ADDRESSES = 20;
+  const MAX_ALT_CREATE_RETRIES = 3;
   const altAddresses = dedupePubkeys([
     ...getCommonALTAddresses(),
     ...additionalAddresses
@@ -5646,46 +5647,59 @@ async function createEphemeralALT(connection, depositor, onProgress, additionalA
       `ALT address set truncated (${addressesForCreate.length}/${altAddresses.length}); packet savings may be limited.`
     );
   }
-  const slot = await connection.getSlot();
-  const [createIx, altAddress] = AddressLookupTableProgram.createLookupTable({
-    authority: depositor.publicKey,
-    payer: depositor.publicKey,
-    recentSlot: slot
-  });
-  const extendIx = AddressLookupTableProgram.extendLookupTable({
-    payer: depositor.publicKey,
-    authority: depositor.publicKey,
-    lookupTable: altAddress,
-    addresses: addressesForCreate
-  });
-  const tx = new Transaction3().add(createIx).add(extendIx);
-  const { blockhash } = await connection.getLatestBlockhash();
-  tx.recentBlockhash = blockhash;
-  tx.feePayer = depositor.publicKey;
-  if (depositor.keypair) {
-    await sendAndConfirmTransaction(connection, tx, [depositor.keypair], { commitment: "confirmed" });
-  } else if (depositor.signTransaction) {
-    const signedTx = await depositor.signTransaction(tx);
-    const sig = await connection.sendRawTransaction(signedTx.serialize());
-    const latestBH = await connection.getLatestBlockhash();
-    await connection.confirmTransaction({ signature: sig, blockhash: latestBH.blockhash, lastValidBlockHeight: latestBH.lastValidBlockHeight }, "confirmed");
-  } else {
-    throw new Error("Cannot create ALT: no signing method provided");
-  }
-  for (let i = 0; i < 30; i++) {
-    await new Promise((r) => setTimeout(r, 500));
-    const result = await connection.getAddressLookupTable(altAddress);
-    if (result.value && result.value.isActive()) {
-      onProgress?.(`ALT created and active: ${altAddress.toBase58()}`);
-      return [result.value];
+  for (let altAttempt = 0; altAttempt < MAX_ALT_CREATE_RETRIES; altAttempt++) {
+    try {
+      const slot = await connection.getSlot("finalized");
+      const [createIx, altAddress] = AddressLookupTableProgram.createLookupTable({
+        authority: depositor.publicKey,
+        payer: depositor.publicKey,
+        recentSlot: slot
+      });
+      const extendIx = AddressLookupTableProgram.extendLookupTable({
+        payer: depositor.publicKey,
+        authority: depositor.publicKey,
+        lookupTable: altAddress,
+        addresses: addressesForCreate
+      });
+      const tx = new Transaction3().add(createIx).add(extendIx);
+      const { blockhash } = await connection.getLatestBlockhash();
+      tx.recentBlockhash = blockhash;
+      tx.feePayer = depositor.publicKey;
+      if (depositor.keypair) {
+        await sendAndConfirmTransaction(connection, tx, [depositor.keypair], { commitment: "confirmed" });
+      } else if (depositor.signTransaction) {
+        const signedTx = await depositor.signTransaction(tx);
+        const sig = await connection.sendRawTransaction(signedTx.serialize());
+        const latestBH = await connection.getLatestBlockhash();
+        await connection.confirmTransaction({ signature: sig, blockhash: latestBH.blockhash, lastValidBlockHeight: latestBH.lastValidBlockHeight }, "confirmed");
+      } else {
+        throw new Error("Cannot create ALT: no signing method provided");
+      }
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        const result = await connection.getAddressLookupTable(altAddress);
+        if (result.value && result.value.isActive()) {
+          onProgress?.(`ALT created and active: ${altAddress.toBase58()}`);
+          return [result.value];
+        }
+      }
+      const finalResult = await connection.getAddressLookupTable(altAddress);
+      if (finalResult.value) {
+        onProgress?.("ALT created (activation pending)");
+        return [finalResult.value];
+      }
+      throw new Error("Failed to create ALT: not active after 15 seconds");
+    } catch (err) {
+      const msg = err?.message ?? String(err);
+      if (msg.includes("not a recent slot") && altAttempt < MAX_ALT_CREATE_RETRIES - 1) {
+        onProgress?.(`ALT creation failed (stale slot), retrying (${altAttempt + 2}/${MAX_ALT_CREATE_RETRIES})...`);
+        await new Promise((r) => setTimeout(r, 2e3));
+        continue;
+      }
+      throw err;
     }
   }
-  const finalResult = await connection.getAddressLookupTable(altAddress);
-  if (finalResult.value) {
-    onProgress?.("ALT created (activation pending)");
-    return [finalResult.value];
-  }
-  throw new Error("Failed to create ALT: not active after 15 seconds");
+  throw new Error(`Failed to create ALT after ${MAX_ALT_CREATE_RETRIES} retries`);
 }
 async function submitTransactionDirect(connection, programId, depositor, proofBytes, publicInputsBytes, nullifiers, mint, recipient, riskOracleQueue, riskQuoteUrl, getRiskQuoteInstruction, onProgress, addressLookupTableAccounts, rangeApiKey, encryptedNoteBytes, relayUrl, altAddresses) {
   onProgress?.("Building transaction...");
@@ -5716,6 +5730,10 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     onProgress?.("Creating address lookup table (chain notes require v0 tx to fit)...");
     addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress);
   }
+  if (isDeposit && isSplPool && (!addressLookupTableAccounts || addressLookupTableAccounts.length === 0)) {
+    onProgress?.("Creating address lookup table (SPL deposit requires v0 tx)...");
+    addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress);
+  }
   const publicAmountBytes = publicInputsBytes.slice(32, 40);
   const publicAmountBuffer = Buffer.from(publicAmountBytes);
   const publicAmount = publicAmountBuffer.readBigInt64LE(0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloak.dev/sdk",
-  "description": "TypeScript SDK for Cloak",
-  "version": "0.1.1",
+  "description": "Shield, send, and swap on Solana privately — TypeScript SDK with UTXO-based zero-knowledge transactions",
+  "version": "0.1.3",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",