solvrn-sdk 1.0.0

package/README.md

@@ -0,0 +1,172 @@
+# solvrn-sdk
+
+**Solvrn SDK** — Privacy SDK for Solana Governance
+
+A TypeScript SDK for building private, encrypted voting applications on Solana using zero-knowledge proofs and confidential computing.
+
+## Installation
+
+```bash
+npm install solvrn-sdk
+```
+
+## Quick Start
+
+```typescript
+import { SolvrnClient } from 'solvrn-sdk';
+import { AnchorProvider, Wallet } from '@coral-xyz/anchor';
+import { Connection, Keypair } from '@solana/web3.js';
+
+// Initialize the client
+const solvrn = new SolvrnClient(
+  'http://localhost:3000',  // Relayer URL
+  'DBCtofDd6f3U342nwz768FXbH6K5QyGxZUGLjFeb9JTS',  // Arcium Program ID (optional)
+  'AL2krCFs4WuzAdjZJbiYJCUnjJ2gmzQdtQuh7YJ3LXcv'   // Solvrn Program ID (optional)
+);
+
+// Initialize ZK backend (must be called once)
+await solvrn.init(circuitJson); // Pass compiled Noir circuit JSON
+
+// Create a proposal
+const { proposalId, txid } = await solvrn.createProposal(
+  provider,      // AnchorProvider
+  authority,     // PublicKey
+  votingMint,    // Token mint address
+  metadata,      // { title, desc, duration }
+  gasBufferSol  // SOL amount for gas (e.g., 0.05)
+);
+
+// Cast a vote (full flow)
+const result = await solvrn.castVote(
+  provider,      // AnchorProvider
+  walletPubkey,  // string (base58)
+  proposalId,    // number
+  choice         // 0 = NO, 1 = YES
+);
+
+console.log('Vote submitted:', result.tx);
+```
+
+## API
+
+### `SolvrnClient`
+
+#### Constructor
+```typescript
+constructor(
+  relayerUrl: string, 
+  arciumProgramId?: string, 
+  programId?: string
+)
+```
+
+#### Methods
+
+- **`init(circuitJson: any): Promise<void>`** — Initialize ZK backend with Noir circuit
+- **`createProposal(provider, authority, votingMint, metadata, gasBufferSol, proposalIdOverride?): Promise<{proposalId, txid}>`** — Create voting proposal and snapshot
+- **`castVote(provider, walletPubkey, proposalId, choice): Promise<{success, tx, error}>`** — Full voting flow (proof + encryption + submission)
+- **`api.getNextProposalId(): Promise<{nextId, success}>`** — Get next available proposal ID
+- **`api.initializeSnapshot(proposalId, votingMint, metadata, creator): Promise<SnapshotResponse>`** — Initialize voting snapshot
+- **`api.getProposal(proposalId): Promise<ProposalResponse>`** — Get proposal data
+- **`api.getProof(proposalId, userPubkey): Promise<ProofResponse>`** — Get Merkle proof for voter
+- **`api.submitVote(proposalId, nullifier, encryptedBallot): Promise<SubmitVoteResponse>`** — Submit encrypted vote
+- **`api.getVoteCounts(proposalId): Promise<VoteCountsResponse>`** — Get vote counts
+- **`api.proveTally(proposalId, yesVotes, noVotes, threshold, quorum): Promise<TallyProofResponse>`** — Generate ZK tally proof
+
+### Sub-modules
+
+- **`prover.generateVoteProof(secret, proofData, proposalId)`** — Generate ZK proof of eligibility
+- **`encryption.encryptVote(provider, voteChoice, votingWeight)`** — Encrypt vote using Arcium MPC
+
+## Requirements
+
+- Relayer running at `relayerUrl` (see [Solvrn Relayer](https://github.com/solvrn-labs/solvrn-relayer))
+- Compiled Noir circuit JSON (from `frontend/circuit/target/circuit.json`)
+- Solana wallet connected via AnchorProvider
+
+## How It Works
+
+1. **Snapshot** — Relayer fetches token holders and builds Merkle tree
+2. **Proof** — SDK gets Merkle proof + voter secret from relayer
+3. **ZK Proof** — SDK generates zero-knowledge proof proving eligibility
+4. **Encryption** — Vote choice encrypted using Arcium MPC
+5. **Submission** — Encrypted vote + ZK proof sent to relayer → Solana
+6. **Tally** — Relayer decrypts votes and generates ZK tally proof
+7. **Verification** — Tally proof verifies quorum & majority thresholds
+
+## What's Real
+
+✅ **Real ZK Proofs** - Uses Barretenberg WASM + Noir circuits  
+✅ **Real Encryption** - Arcium MPC encryption  
+✅ **Real On-Chain** - Actual Solana transactions  
+✅ **Real Merkle Trees** - Built from actual token holders  
+✅ **Real Nullifiers** - Prevents double voting  
+✅ **Real Vote Storage** - Encrypted votes stored on-chain
+
+## Current Limitations
+
+⚠️ **Vote Decryption** - Currently simulated (relayer-side). Real Arcium MPC decryption coming soon.  
+⚠️ **Vote Count Breakdown** - `getVoteCounts()` returns simulated yes/no breakdown. The total vote count (`realVoteCount`) is accurate.  
+✅ **Tally Proofs** - Work perfectly with user-provided vote counts. ZK proofs are 100% real.
+
+## Important: Using Tally in Production
+
+**⚠️ CRITICAL:** `proveTally()` generates REAL ZK proofs, but if you use `getVoteCounts()` for vote counts, you'll be proving SIMULATED data.
+
+### ✅ Full Flow (With Limitation):
+
+```typescript
+// 1. Create proposal ✅ REAL
+const { proposalId } = await solvrn.createProposal(...);
+
+// 2. Cast vote ✅ REAL  
+await solvrn.castVote(provider, wallet, proposalId, 1);
+
+// 3. Get vote counts ⚠️ PARTIALLY REAL
+const counts = await solvrn.api.getVoteCounts(proposalId);
+// counts.realVoteCount ✅ - Accurate total
+// counts.yesVotes/noVotes ⚠️ - Simulated breakdown
+
+// 4. Prove tally ⚠️ REAL PROOF, BUT PROVING SIMULATED DATA
+const tallyProof = await solvrn.api.proveTally(
+  proposalId,
+  counts.yesVotes,  // ⚠️ Simulated!
+  counts.noVotes,   // ⚠️ Simulated!
+  51, 10
+);
+// Returns: Real ZK proof ✅
+// But proving: Simulated vote counts ⚠️
+```
+
+### ✅ Recommended: Provide Your Own Vote Counts
+
+For production, decrypt votes yourself or wait for relayer decryption:
+
+```typescript
+// Get accurate total vote count
+const counts = await solvrn.api.getVoteCounts(proposalId);
+console.log(`Total votes: ${counts.realVoteCount}`); // ✅ Accurate
+
+// Provide your own yes/no breakdown (from your own decryption)
+const tallyProof = await solvrn.api.proveTally(
+  proposalId,
+  yourDecryptedYesVotes,  // ✅ Your own decryption
+  yourDecryptedNoVotes,   // ✅ Your own decryption
+  51, 10
+);
+// Returns: Real ZK proof of REAL data ✅
+```
+
+**What's Real:**
+- ✅ Total vote count (`realVoteCount`) - Accurate
+- ✅ ZK proof generation - 100% real
+- ✅ Vote encryption - 100% real
+- ✅ On-chain storage - 100% real
+- ✅ Tally proof generation - 100% real
+
+**What's Simulated:**
+- ⚠️ Yes/No breakdown from `getVoteCounts()` - Until Arcium MPC decryption is implemented  
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import * as _aztec_bb_js from '@aztec/bb.js';
+import { Buffer } from 'buffer';
+import { AnchorProvider } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+
+interface ProofResponse {
+    proof: {
+        path: string[];
+        index: number;
+        root: string;
+        balance: string;
+        weight: string;
+        secret: string;
+        leaf: string;
+    };
+    success: boolean;
+    error?: string;
+}
+interface ProposalMetadata {
+    title: string;
+    desc: string;
+    duration: number;
+}
+declare class SolvrnApi {
+    private baseUrl;
+    constructor(baseUrl: string);
+    initializeSnapshot(proposalId: number, votingMint: string, metadata?: ProposalMetadata, creator?: string): Promise<any>;
+    getNextProposalId(): Promise<{
+        nextId: number;
+        success: boolean;
+    }>;
+    getProposal(proposalId: number): Promise<any>;
+    getProof(proposalId: number, userPubkey: string): Promise<ProofResponse>;
+    submitVote(proposalId: number, nullifierHex: string, encryptedBallot: {
+        ciphertext: Uint8Array;
+        public_key: number[];
+        nonce: number[];
+    }): Promise<any>;
+    proveTally(proposalId: number, yesVotes: number, noVotes: number, threshold: number, quorum: number): Promise<any>;
+    getVoteCounts(proposalId: number): Promise<any>;
+    private post;
+    private get;
+}
+
+declare class SolvrnProver {
+    private backend;
+    private noir;
+    init(circuitJson: any): Promise<void>;
+    generateVoteProof(secret: string, proofRes: any, proposalId: number): Promise<_aztec_bb_js.ProofData>;
+}
+
+declare class SolvrnEncryption {
+    private programId;
+    constructor(programId?: string);
+    encryptVote(provider: AnchorProvider, voteChoice: number, votingWeight: number): Promise<{
+        ciphertext: Buffer<ArrayBuffer>;
+        nonce: number[];
+        public_key: number[];
+    }>;
+}
+
+declare class SolvrnClient {
+    api: SolvrnApi;
+    prover: SolvrnProver;
+    encryption: SolvrnEncryption;
+    constructor(relayerUrl: string, arciumProgramId?: string, programId?: string);
+    init(circuitJson: any): Promise<void>;
+    createProposal(provider: AnchorProvider, authorityPubkey: PublicKey, votingMint: string, metadata: ProposalMetadata, gasBufferSol: number, proposalIdOverride?: number): Promise<{
+        proposalId: number;
+        txid: string;
+    }>;
+    castVote(provider: AnchorProvider, walletPubkey: string, proposalId: number, choice: number): Promise<{
+        success: any;
+        tx: any;
+        error: any;
+    }>;
+}
+
+export { SolvrnClient };

package/dist/index.js

@@ -0,0 +1,960 @@
+import { Buffer } from "buffer";
+global.Buffer = Buffer;
+
+// src/utils.ts
+import { PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";
+import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token";
+var SYSTEM_PROGRAM_ID = new PublicKey("11111111111111111111111111111111");
+var LEGACY_TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+var hexToBytes = (hex) => {
+  let cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (cleanHex.length % 2 !== 0) cleanHex = "0" + cleanHex;
+  const bytes = [];
+  for (let i = 0; i < cleanHex.length; i += 2) bytes.push(parseInt(cleanHex.substr(i, 2), 16));
+  return bytes;
+};
+
+// src/api.ts
+var SolvrnApi = class {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+  // --- UPDATED: Accepts Creator Argument ---
+  async initializeSnapshot(proposalId, votingMint, metadata, creator) {
+    if (process.env.NODE_ENV !== "development") {
+    }
+    return this.post("initialize-snapshot", {
+      proposalId,
+      votingMint,
+      metadata,
+      creator
+      // <--- THIS MUST BE SENT TO THE RELAYER
+    });
+  }
+  async getNextProposalId() {
+    return this.get("next-proposal-id");
+  }
+  async getProposal(proposalId) {
+    return this.get(`proposal/${proposalId}`);
+  }
+  async getProof(proposalId, userPubkey) {
+    const res = await this.post("get-proof", { proposalId: proposalId.toString(), userPubkey });
+    if (!res.success) throw new Error(res.error || "Failed to fetch merkle proof");
+    return res;
+  }
+  async submitVote(proposalId, nullifierHex, encryptedBallot) {
+    return this.post("relay-vote", {
+      nullifier: hexToBytes(nullifierHex),
+      ciphertext: Array.from(encryptedBallot.ciphertext),
+      pubkey: encryptedBallot.public_key,
+      nonce: encryptedBallot.nonce,
+      proposalId
+    });
+  }
+  async proveTally(proposalId, yesVotes, noVotes, threshold, quorum) {
+    return this.post("prove-tally", { proposalId, yesVotes, noVotes, threshold, quorum });
+  }
+  async getVoteCounts(proposalId) {
+    return this.get(`vote-counts/${proposalId}`);
+  }
+  async post(endpoint, body) {
+    const allowedEndpoints = [
+      "initialize-snapshot",
+      "get-proof",
+      "relay-vote",
+      "prove-tally"
+    ];
+    if (!allowedEndpoints.includes(endpoint)) {
+      throw new Error(`Endpoint '${endpoint}' is not accessible through SDK. Use direct API calls for admin functionality.`);
+    }
+    const res = await fetch(`${this.baseUrl}/${endpoint}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    return await res.json();
+  }
+  async get(endpoint) {
+    const allowedEndpoints = [
+      "next-proposal-id",
+      "proposal",
+      "vote-counts"
+    ];
+    const isAllowed = allowedEndpoints.some(
+      (allowed) => endpoint === allowed || endpoint.startsWith(`${allowed}/`)
+    );
+    if (!isAllowed) {
+      throw new Error(`Endpoint '${endpoint}' is not accessible through SDK. Use direct API calls for admin functionality.`);
+    }
+    const res = await fetch(`${this.baseUrl}/${endpoint}`);
+    return await res.json();
+  }
+};
+
+// src/prover.ts
+import { Barretenberg, UltraHonkBackend } from "@aztec/bb.js";
+import { Noir } from "@noir-lang/noir_js";
+var SolvrnProver = class {
+  constructor() {
+    this.backend = null;
+    this.noir = null;
+  }
+  async init(circuitJson) {
+    const bb = await Barretenberg.new();
+    this.backend = new UltraHonkBackend(circuitJson.bytecode, bb);
+    this.noir = new Noir(circuitJson);
+  }
+  async generateVoteProof(secret, proofRes, proposalId) {
+    if (!this.noir || !this.backend) throw new Error("Prover not initialized. Call init() first.");
+    const weightVal = BigInt(proofRes.proof.weight);
+    const balanceVal = BigInt(proofRes.proof.balance);
+    const inputs = {
+      user_secret: "0x" + secret.replace("0x", "").padStart(64, "0"),
+      balance: "0x" + balanceVal.toString(16).padStart(64, "0"),
+      weight: "0x" + weightVal.toString(16).padStart(64, "0"),
+      merkle_path: proofRes.proof.path,
+      // Pass as-is, no padding
+      merkle_index: Number(proofRes.proof.index),
+      merkle_root: proofRes.proof.root,
+      // Pass as-is, no padding
+      proposal_id: "0x" + BigInt(proposalId).toString(16).padStart(64, "0")
+    };
+    console.log("Noir inputs:", JSON.stringify(inputs, null, 2));
+    const { witness } = await this.noir.execute(inputs);
+    const proof = await this.backend.generateProof(witness);
+    return proof;
+  }
+};
+
+// src/encryption.ts
+import { getMXEPublicKey, RescueCipher, x25519 } from "@arcium-hq/client";
+import { PublicKey as PublicKey2 } from "@solana/web3.js";
+import { Buffer as Buffer2 } from "buffer";
+var SolvrnEncryption = class {
+  constructor(programId = process.env.ARCIUM_PROGRAM_ID || "DBCtofDd6f3U342nwz768FXbH6K5QyGxZUGLjFeb9JTS") {
+    this.programId = new PublicKey2(programId);
+  }
+  async encryptVote(provider, voteChoice, votingWeight) {
+    let mxePublicKey = null;
+    let attempts = 0;
+    while (!mxePublicKey && attempts < 20) {
+      try {
+        mxePublicKey = await getMXEPublicKey(provider, this.programId);
+        if (mxePublicKey) break;
+      } catch (err) {
+      }
+      await new Promise((r) => setTimeout(r, 2e3));
+      attempts++;
+    }
+    if (!mxePublicKey) throw new Error("Arcium MXE Public Key not found.");
+    const ephemeralSecret = x25519.utils.randomSecretKey();
+    const ephemeralPublic = x25519.getPublicKey(ephemeralSecret);
+    const sharedSecret = x25519.getSharedSecret(ephemeralSecret, mxePublicKey);
+    const cipher = new RescueCipher(sharedSecret);
+    const inputs = [BigInt(votingWeight), BigInt(voteChoice)];
+    const nonce = x25519.utils.randomSecretKey().slice(0, 16);
+    const encrypted = cipher.encrypt(inputs, nonce);
+    return {
+      ciphertext: Buffer2.from(new Uint8Array(encrypted.flat().map((n) => Number(n)))),
+      nonce: Array.from(nonce),
+      public_key: Array.from(ephemeralPublic)
+    };
+  }
+};
+
+// src/index.ts
+import { Program } from "@coral-xyz/anchor";
+import BN from "bn.js";
+import { PublicKey as PublicKey3, SystemProgram, LAMPORTS_PER_SOL as LAMPORTS_PER_SOL2 } from "@solana/web3.js";
+
+// src/idl.json
+var idl_default = {
+  address: "AL2krCFs4WuzAdjZJbiYJCUnjJ2gmzQdtQuh7YJ3LXcv",
+  metadata: {
+    name: "solvote_chain",
+    version: "0.1.0",
+    spec: "0.1.0",
+    description: "Created with Anchor"
+  },
+  instructions: [
+    {
+      name: "finalize_proposal",
+      discriminator: [
+        23,
+        68,
+        51,
+        167,
+        109,
+        173,
+        187,
+        164
+      ],
+      accounts: [
+        {
+          name: "proposal",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  115,
+                  118,
+                  114,
+                  110,
+                  95,
+                  118,
+                  53
+                ]
+              },
+              {
+                kind: "account",
+                path: "proposal.proposal_id",
+                account: "Proposal"
+              }
+            ]
+          }
+        },
+        {
+          name: "proposal_token_account",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "account",
+                path: "proposal"
+              },
+              {
+                kind: "const",
+                value: [
+                  6,
+                  221,
+                  246,
+                  225,
+                  215,
+                  101,
+                  161,
+                  147,
+                  217,
+                  203,
+                  225,
+                  70,
+                  206,
+                  235,
+                  121,
+                  172,
+                  28,
+                  180,
+                  133,
+                  237,
+                  95,
+                  91,
+                  55,
+                  145,
+                  58,
+                  140,
+                  245,
+                  133,
+                  126,
+                  255,
+                  0,
+                  169
+                ]
+              },
+              {
+                kind: "account",
+                path: "treasury_mint"
+              }
+            ],
+            program: {
+              kind: "const",
+              value: [
+                140,
+                151,
+                37,
+                143,
+                78,
+                36,
+                137,
+                241,
+                187,
+                61,
+                16,
+                41,
+                20,
+                142,
+                13,
+                131,
+                11,
+                90,
+                19,
+                153,
+                218,
+                255,
+                16,
+                132,
+                4,
+                142,
+                123,
+                216,
+                219,
+                233,
+                248,
+                89
+              ]
+            }
+          }
+        },
+        {
+          name: "target_token_account",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "account",
+                path: "target_wallet"
+              },
+              {
+                kind: "const",
+                value: [
+                  6,
+                  221,
+                  246,
+                  225,
+                  215,
+                  101,
+                  161,
+                  147,
+                  217,
+                  203,
+                  225,
+                  70,
+                  206,
+                  235,
+                  121,
+                  172,
+                  28,
+                  180,
+                  133,
+                  237,
+                  95,
+                  91,
+                  55,
+                  145,
+                  58,
+                  140,
+                  245,
+                  133,
+                  126,
+                  255,
+                  0,
+                  169
+                ]
+              },
+              {
+                kind: "account",
+                path: "treasury_mint"
+              }
+            ],
+            program: {
+              kind: "const",
+              value: [
+                140,
+                151,
+                37,
+                143,
+                78,
+                36,
+                137,
+                241,
+                187,
+                61,
+                16,
+                41,
+                20,
+                142,
+                13,
+                131,
+                11,
+                90,
+                19,
+                153,
+                218,
+                255,
+                16,
+                132,
+                4,
+                142,
+                123,
+                216,
+                219,
+                233,
+                248,
+                89
+              ]
+            }
+          }
+        },
+        {
+          name: "target_wallet",
+          relations: [
+            "proposal"
+          ]
+        },
+        {
+          name: "treasury_mint",
+          relations: [
+            "proposal"
+          ]
+        },
+        {
+          name: "authority",
+          signer: true,
+          relations: [
+            "proposal"
+          ]
+        },
+        {
+          name: "token_program",
+          address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        }
+      ],
+      args: [
+        {
+          name: "proof",
+          type: "bytes"
+        },
+        {
+          name: "yes_votes",
+          type: "u64"
+        },
+        {
+          name: "no_votes",
+          type: "u64"
+        },
+        {
+          name: "threshold",
+          type: "u64"
+        },
+        {
+          name: "quorum",
+          type: "u64"
+        }
+      ]
+    },
+    {
+      name: "initialize_proposal",
+      discriminator: [
+        50,
+        73,
+        156,
+        98,
+        129,
+        149,
+        21,
+        158
+      ],
+      accounts: [
+        {
+          name: "proposal",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  115,
+                  118,
+                  114,
+                  110,
+                  95,
+                  118,
+                  53
+                ]
+              },
+              {
+                kind: "arg",
+                path: "proposal_id"
+              }
+            ]
+          }
+        },
+        {
+          name: "proposal_token_account",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "account",
+                path: "proposal"
+              },
+              {
+                kind: "const",
+                value: [
+                  6,
+                  221,
+                  246,
+                  225,
+                  215,
+                  101,
+                  161,
+                  147,
+                  217,
+                  203,
+                  225,
+                  70,
+                  206,
+                  235,
+                  121,
+                  172,
+                  28,
+                  180,
+                  133,
+                  237,
+                  95,
+                  91,
+                  55,
+                  145,
+                  58,
+                  140,
+                  245,
+                  133,
+                  126,
+                  255,
+                  0,
+                  169
+                ]
+              },
+              {
+                kind: "account",
+                path: "treasury_mint"
+              }
+            ],
+            program: {
+              kind: "const",
+              value: [
+                140,
+                151,
+                37,
+                143,
+                78,
+                36,
+                137,
+                241,
+                187,
+                61,
+                16,
+                41,
+                20,
+                142,
+                13,
+                131,
+                11,
+                90,
+                19,
+                153,
+                218,
+                255,
+                16,
+                132,
+                4,
+                142,
+                123,
+                216,
+                219,
+                233,
+                248,
+                89
+              ]
+            }
+          }
+        },
+        {
+          name: "voting_mint"
+        },
+        {
+          name: "treasury_mint"
+        },
+        {
+          name: "target_wallet"
+        },
+        {
+          name: "authority",
+          writable: true,
+          signer: true
+        },
+        {
+          name: "token_program",
+          address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+        },
+        {
+          name: "associated_token_program",
+          address: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "proposal_id",
+          type: "u64"
+        },
+        {
+          name: "merkle_root",
+          type: {
+            array: [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          name: "execution_amount",
+          type: "u64"
+        }
+      ]
+    },
+    {
+      name: "submit_vote",
+      discriminator: [
+        115,
+        242,
+        100,
+        0,
+        49,
+        178,
+        242,
+        133
+      ],
+      accounts: [
+        {
+          name: "proposal",
+          writable: true
+        },
+        {
+          name: "nullifier_account",
+          writable: true,
+          pda: {
+            seeds: [
+              {
+                kind: "const",
+                value: [
+                  110,
+                  117,
+                  108,
+                  108,
+                  105,
+                  102,
+                  105,
+                  101,
+                  114
+                ]
+              },
+              {
+                kind: "account",
+                path: "proposal"
+              },
+              {
+                kind: "arg",
+                path: "nullifier"
+              }
+            ]
+          }
+        },
+        {
+          name: "relayer",
+          writable: true,
+          signer: true
+        },
+        {
+          name: "system_program",
+          address: "11111111111111111111111111111111"
+        }
+      ],
+      args: [
+        {
+          name: "nullifier",
+          type: {
+            array: [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          name: "ciphertext",
+          type: "bytes"
+        },
+        {
+          name: "pubkey",
+          type: {
+            array: [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          name: "nonce",
+          type: "u128"
+        }
+      ]
+    }
+  ],
+  accounts: [
+    {
+      name: "NullifierAccount",
+      discriminator: [
+        250,
+        31,
+        238,
+        177,
+        213,
+        98,
+        48,
+        172
+      ]
+    },
+    {
+      name: "Proposal",
+      discriminator: [
+        26,
+        94,
+        189,
+        187,
+        116,
+        136,
+        53,
+        33
+      ]
+    }
+  ],
+  errors: [
+    {
+      code: 6e3,
+      name: "AlreadyExecuted",
+      msg: "Already executed."
+    },
+    {
+      code: 6001,
+      name: "ProposalNotPassed",
+      msg: "Proposal did not pass (State)."
+    },
+    {
+      code: 6002,
+      name: "InvalidProof",
+      msg: "Invalid ZK Proof."
+    },
+    {
+      code: 6003,
+      name: "QuorumNotMet",
+      msg: "Quorum not met."
+    },
+    {
+      code: 6004,
+      name: "MajorityNotMet",
+      msg: "Majority threshold not met."
+    }
+  ],
+  types: [
+    {
+      name: "NullifierAccount",
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "proposal",
+            type: "pubkey"
+          },
+          {
+            name: "nullifier",
+            type: {
+              array: [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            name: "ciphertext",
+            type: "bytes"
+          },
+          {
+            name: "pubkey",
+            type: {
+              array: [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            name: "nonce",
+            type: "u128"
+          }
+        ]
+      }
+    },
+    {
+      name: "Proposal",
+      type: {
+        kind: "struct",
+        fields: [
+          {
+            name: "proposal_id",
+            type: "u64"
+          },
+          {
+            name: "vote_count",
+            type: "u64"
+          },
+          {
+            name: "authority",
+            type: "pubkey"
+          },
+          {
+            name: "merkle_root",
+            type: {
+              array: [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            name: "voting_mint",
+            type: "pubkey"
+          },
+          {
+            name: "treasury_mint",
+            type: "pubkey"
+          },
+          {
+            name: "execution_amount",
+            type: "u64"
+          },
+          {
+            name: "target_wallet",
+            type: "pubkey"
+          },
+          {
+            name: "tally_result",
+            type: "u8"
+          },
+          {
+            name: "is_executed",
+            type: "bool"
+          }
+        ]
+      }
+    }
+  ]
+};
+
+// src/index.ts
+var PROGRAM_ID = null;
+var getProgramId = () => {
+  if (PROGRAM_ID) return PROGRAM_ID;
+  const id = globalThis.process?.env?.PROGRAM_ID || process.env.PROGRAM_ID;
+  if (!id) {
+    throw new Error("PROGRAM_ID environment variable required. Please set process.env.PROGRAM_ID in your application or pass programId to SolvrnClient constructor.");
+  }
+  PROGRAM_ID = new PublicKey3(id);
+  return PROGRAM_ID;
+};
+var TOKEN_PROGRAM_ID = new PublicKey3("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+var ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey3("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+var SolvrnClient = class {
+  constructor(relayerUrl, arciumProgramId, programId) {
+    if (programId) {
+      globalThis.process = globalThis.process || {};
+      globalThis.process.env = globalThis.process.env || {};
+      globalThis.process.env.PROGRAM_ID = programId;
+    }
+    this.api = new SolvrnApi(relayerUrl);
+    this.prover = new SolvrnProver();
+    this.encryption = new SolvrnEncryption(arciumProgramId);
+  }
+  async init(circuitJson) {
+    await this.prover.init(circuitJson);
+  }
+  async createProposal(provider, authorityPubkey, votingMint, metadata, gasBufferSol, proposalIdOverride) {
+    let proposalId = proposalIdOverride;
+    if (!proposalId) {
+      const { nextId, success } = await this.api.getNextProposalId();
+      if (!success) throw new Error("Failed to get ID");
+      proposalId = nextId;
+    }
+    const snap = await this.api.initializeSnapshot(
+      proposalId,
+      votingMint,
+      metadata,
+      authorityPubkey.toBase58()
+      // <--- Force Creator into Snapshot
+    );
+    if (!snap.success) throw new Error(snap.error || "Snapshot failed.");
+    const program = new Program(idl_default, provider);
+    console.log("SDK CALLING PROGRAM ID:", program.programId.toBase58());
+    const [pda] = PublicKey3.findProgramAddressSync(
+      [Buffer.from("svrn_v5"), new BN(proposalId).toArrayLike(Buffer, "le", 8)],
+      getProgramId()
+    );
+    const [vault] = PublicKey3.findProgramAddressSync(
+      [
+        pda.toBuffer(),
+        TOKEN_PROGRAM_ID.toBuffer(),
+        // Legacy
+        new PublicKey3(votingMint).toBuffer()
+      ],
+      ASSOCIATED_TOKEN_PROGRAM_ID
+    );
+    const tx = await program.methods.initializeProposal(new BN(proposalId), hexToBytes(snap.root), new BN(1e3)).accounts({
+      proposal: pda,
+      proposalTokenAccount: vault,
+      authority: authorityPubkey,
+      votingMint: new PublicKey3(votingMint),
+      treasuryMint: new PublicKey3(votingMint),
+      targetWallet: authorityPubkey,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      // Strict Legacy
+      associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId
+    }).transaction();
+    tx.add(SystemProgram.transfer({
+      fromPubkey: authorityPubkey,
+      toPubkey: pda,
+      lamports: gasBufferSol * LAMPORTS_PER_SOL2
+    }));
+    const { blockhash } = await provider.connection.getLatestBlockhash();
+    tx.recentBlockhash = blockhash;
+    tx.feePayer = authorityPubkey;
+    const signedTx = await provider.wallet.signTransaction(tx);
+    const txid = await provider.connection.sendRawTransaction(signedTx.serialize());
+    await provider.connection.confirmTransaction(txid);
+    return { proposalId, txid };
+  }
+  async castVote(provider, walletPubkey, proposalId, choice) {
+    if (!walletPubkey || typeof walletPubkey !== "string") {
+      throw new Error("Invalid wallet public key");
+    }
+    if (!Number.isInteger(proposalId) || proposalId < 0) {
+      throw new Error("Invalid proposal ID");
+    }
+    if (!Number.isInteger(choice) || choice !== 0 && choice !== 1) {
+      throw new Error("Invalid vote choice: must be 0 (NO) or 1 (YES)");
+    }
+    const proofData = await this.api.getProof(proposalId, walletPubkey);
+    const relayerSecret = proofData.proof.secret;
+    const zkProof = await this.prover.generateVoteProof(relayerSecret, proofData, proposalId);
+    const weight = Number(proofData.proof.weight);
+    const encrypted = await this.encryption.encryptVote(provider, choice, weight);
+    const nullifier = zkProof.publicInputs[zkProof.publicInputs.length - 1];
+    const relayResponse = await this.api.submitVote(proposalId, nullifier, encrypted);
+    return { success: relayResponse.success, tx: relayResponse.tx, error: relayResponse.error };
+  }
+};
+export {
+  SolvrnClient
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "solvrn-sdk",
+  "version": "1.0.0",
+  "description": "Privacy SDK for Solana governance using zero-knowledge proofs and confidential computing",
+  "type": "module",
+  "keywords": [
+    "solana",
+    "governance",
+    "zk",
+    "zero-knowledge",
+    "privacy",
+    "voting",
+    "noir",
+    "arcium",
+    "mpc",
+    "blockchain"
+  ],
+  "author": "Solvrn Labs",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solvrn-labs/solvrn-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/solvrn-labs/solvrn-sdk/issues"
+  },
+  "homepage": "https://github.com/solvrn-labs/solvrn-sdk#readme",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage"
+  },
+  "dependencies": {
+    "@arcium-hq/client": "^0.6.2",
+    "@aztec/bb.js": "^3.0.0-nightly.20260102",
+    "@coral-xyz/anchor": "^0.32.1",
+    "@noir-lang/noir_js": "1.0.0-beta.15",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.95.0",
+    "bn.js": "^5.2.2",
+    "buffer": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/bn.js": "^5.2.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3"
+  }
+}