@cloak.dev/sdk 0.1.1 → 0.1.2

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloak.dev/sdk",
   "description": "TypeScript SDK for Cloak",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",