@viwoapp/sdk 0.1.7 → 2.0.0

package/dist/index.js

@@ -88,7 +88,18 @@ var PROGRAM_IDS = {
   governanceProtocol: new import_web3.PublicKey("3R256kBN9iXozjypQFRAmegBhd6HJqXWqdNG7Th78HYe"),
   sscreProtocol: new import_web3.PublicKey("6AJNcQSfoiE2UAeUDyJUBumS9SBwhAdSznoAeYpXrxXZ"),
   vilinkProtocol: new import_web3.PublicKey("CFGXTS2MueQwTYTMMTBQbRWzJtSTC2p4ZRuKPpLDmrv7"),
-  gaslessProtocol: new import_web3.PublicKey("FcXJAjzJs8eVY2WTRFXynQBpC7WZUqKZppyp9xS6PaB3")
+  gaslessProtocol: new import_web3.PublicKey("FcXJAjzJs8eVY2WTRFXynQBpC7WZUqKZppyp9xS6PaB3"),
+  /**
+   * VCoin Token Mint Address (Token-2022)
+   * 
+   * NOTE: This is a placeholder. Override via ViWoClient config.programIds.vcoinMint
+   * after deploying your VCoin mint on devnet/mainnet.
+   * 
+   * Finding #2 Fix: SDK now filters token accounts by mint address to prevent
+   * summing balances from other Token-2022 tokens.
+   */
+  vcoinMint: new import_web3.PublicKey("11111111111111111111111111111111")
+  // Placeholder - override in config
 };
 var SEEDS = {
   // VCoin
@@ -262,9 +273,22 @@ var GOVERNANCE_CONSTANTS = {
   vetoWindow: 24 * 3600,
   // 1 day
   quorumBps: 400,
-  // 4%
-  zkVotingEnabled: false
-  // C-01: Disabled until proper ZK infrastructure
+  // 4% (C-03: abstains no longer count toward quorum)
+  /** Authority transfer timelock (H-02) */
+  authorityTransferTimelock: 24 * 3600,
+  // 24 hours
+  /** ZK private voting constants */
+  zk: {
+    /** Vote validity proof size (3 OR proofs + 1 sum proof) */
+    voteProofSize: 352,
+    /** ElGamal ciphertext size (R || C) */
+    ciphertextSize: 64,
+    /** Max committee members */
+    maxCommitteeSize: 5,
+    /** Account sizes */
+    privateVotingConfigSize: 680,
+    decryptionShareSize: 242
+  }
 };
 var SECURITY_CONSTANTS = {
   // H-02: Two-step authority transfer
@@ -299,8 +323,21 @@ var SECURITY_CONSTANTS = {
   // H-NEW-02: Max proof levels (supports 4B+ users)
   maxEpochBitmap: 1023,
   // H-NEW-04: Max epoch with bitmap storage (85+ years)
-  votingPowerVerifiedOnChain: true
+  votingPowerVerifiedOnChain: true,
   // C-NEW-01: Params read from chain, not passed
+  // Audit remediation additions
+  /** H-AUDIT-12: Maximum concurrent sessions per user */
+  maxSessionsPerUser: 5,
+  /** C-AUDIT-15: Maximum day delta for daily budget reset (clock skew protection) */
+  maxDayDelta: 2,
+  /** H-AUDIT-09: Maximum daily activity score for transfer hook */
+  maxDailyActivityScore: 5e3,
+  /** M-AUDIT-10: Wash flag decay period (7 days) */
+  washFlagDecayPeriod: 7 * 24 * 3600,
+  /** M-18: Maximum vouch age before expiry (1 year) */
+  maxVouchAge: 365 * 24 * 3600,
+  /** C-AUDIT-11: Valid content energy tiers (1-4) */
+  maxContentTier: 4
 };
 var VALID_URI_PREFIXES = ["ipfs://", "https://", "ar://"];
 var MAX_URI_LENGTH = 128;
@@ -737,6 +774,10 @@ var StakingClient = class {
   }
   /**
    * Get tier name
+   *
+   * M-05: The on-chain update_tier instruction will reject no-op tier updates
+   * with TierUnchanged error. Only call updateTier when the user's stake amount
+   * actually qualifies for a different tier.
    */
   getTierName(tier) {
     const names = ["None", "Bronze", "Silver", "Gold", "Platinum"];
@@ -848,11 +889,14 @@ var GovernanceClient = class {
       if (!accountInfo) {
         return null;
       }
+      const data = accountInfo.data;
       return {
-        authority: new import_web34.PublicKey(accountInfo.data.slice(8, 40)),
-        proposalCount: new import_anchor3.BN(accountInfo.data.slice(40, 48), "le"),
-        vevcoinMint: new import_web34.PublicKey(accountInfo.data.slice(48, 80)),
-        paused: accountInfo.data[80] !== 0
+        authority: new import_web34.PublicKey(data.slice(8, 40)),
+        proposalCount: new import_anchor3.BN(data.slice(40, 48), "le"),
+        vevcoinMint: new import_web34.PublicKey(data.slice(48, 80)),
+        paused: data[80] !== 0,
+        pendingAuthority: new import_web34.PublicKey(data.slice(81, 113)),
+        pendingAuthorityActivatedAt: new import_anchor3.BN(data.slice(113, 121), "le")
       };
     } catch {
       return null;
@@ -925,7 +969,11 @@ var GovernanceClient = class {
         proposal: new import_web34.PublicKey(data.slice(40, 72)),
         votePower: new import_anchor3.BN(data.slice(72, 80), "le"),
         support: data[80] !== 0,
-        votedAt: new import_anchor3.BN(data.slice(81, 89), "le")
+        votedAt: new import_anchor3.BN(data.slice(81, 89), "le"),
+        // Private vote ciphertexts (if present, at byte offsets after public vote fields)
+        ctFor: new Uint8Array(data.slice(89, 153)),
+        ctAgainst: new Uint8Array(data.slice(153, 217)),
+        ctAbstain: new Uint8Array(data.slice(217, 281))
       };
     } catch {
       return null;
@@ -940,6 +988,9 @@ var GovernanceClient = class {
   }
   /**
    * Calculate user's voting power
+   *
+   * @note M-01 fix: 5A boost formula is now `1000 + ((five_a_score * 100) / 1000)`
+   * to fix precision loss for small scores.
    */
   async getVotingPower(user) {
     const target = user || this.client.publicKey;
@@ -982,6 +1033,9 @@ var GovernanceClient = class {
   }
   /**
    * Get proposal progress
+   *
+   * @note C-03: Quorum is now calculated as votesFor + votesAgainst only.
+   * Abstains do NOT count toward quorum.
    */
   async getProposalProgress(proposalId) {
     const proposal = await this.getProposal(proposalId);
@@ -1005,7 +1059,7 @@ var GovernanceClient = class {
       timeRemaining
     };
   }
-  // ============ Transaction Building ============
+  // ============ Transaction Building (Public Voting) ============
   /**
    * Build create proposal transaction
    */
@@ -1021,12 +1075,12 @@ var GovernanceClient = class {
     return tx;
   }
   /**
-   * Build vote transaction
-   * 
-   * @note v2.8.0 (C-NEW-01): Voting power parameters (vevcoin_balance, five_a_score, tier) 
+   * Build vote transaction (public)
+   *
+   * @note v2.8.0 (C-NEW-01): Voting power parameters (vevcoin_balance, five_a_score, tier)
    * are now read from on-chain state, not passed as parameters. This prevents vote manipulation.
    * The transaction only needs: proposal_id and choice (VoteChoice enum)
-   * 
+   *
    * @param proposalId - The proposal to vote on
    * @param support - true = For, false = Against (use VoteChoice for more options)
    */
@@ -1056,6 +1110,148 @@ var GovernanceClient = class {
     const tx = new import_web34.Transaction();
     return tx;
   }
+  // ============ ZK Private Voting ============
+  /**
+   * Build cast private vote transaction
+   *
+   * Uses Twisted ElGamal encryption on Ristretto255 with compressed sigma proofs.
+   * The voter encrypts their choice into 3 ciphertexts (for/against/abstain) and
+   * generates a validity proof that exactly one ciphertext encrypts their weight.
+   *
+   * Use the `zk-voting-sdk` crate to generate ciphertexts and proofs off-chain:
+   * ```rust
+   * let (ct_for, ct_against, ct_abstain, proof) = encrypt_and_prove(&pubkey, choice, weight);
+   * ```
+   *
+   * @param params - Private vote parameters with ciphertexts and proof
+   */
+  async buildCastPrivateVoteTransaction(params) {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    if (params.ctFor.length !== GOVERNANCE_CONSTANTS.zk.ciphertextSize) {
+      throw new Error(`ctFor must be ${GOVERNANCE_CONSTANTS.zk.ciphertextSize} bytes`);
+    }
+    if (params.ctAgainst.length !== GOVERNANCE_CONSTANTS.zk.ciphertextSize) {
+      throw new Error(`ctAgainst must be ${GOVERNANCE_CONSTANTS.zk.ciphertextSize} bytes`);
+    }
+    if (params.ctAbstain.length !== GOVERNANCE_CONSTANTS.zk.ciphertextSize) {
+      throw new Error(`ctAbstain must be ${GOVERNANCE_CONSTANTS.zk.ciphertextSize} bytes`);
+    }
+    if (params.proofData.length !== GOVERNANCE_CONSTANTS.zk.voteProofSize) {
+      throw new Error(`proofData must be ${GOVERNANCE_CONSTANTS.zk.voteProofSize} bytes`);
+    }
+    const hasVoted = await this.hasVoted(params.proposalId);
+    if (hasVoted) {
+      throw new Error("Already voted on this proposal");
+    }
+    const tx = new import_web34.Transaction();
+    return tx;
+  }
+  /**
+   * Build enable private voting transaction
+   *
+   * Called by the governance authority to enable ZK private voting on a proposal.
+   * Requires specifying the decryption committee and their ElGamal public keys.
+   *
+   * @param params - Private voting configuration
+   */
+  async buildEnablePrivateVotingTransaction(params) {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    if (params.encryptionPubkey.length !== 32) {
+      throw new Error("encryptionPubkey must be 32 bytes (Ristretto255 point)");
+    }
+    if (params.committeeSize > GOVERNANCE_CONSTANTS.zk.maxCommitteeSize) {
+      throw new Error(`Committee size exceeds max of ${GOVERNANCE_CONSTANTS.zk.maxCommitteeSize}`);
+    }
+    if (params.decryptionThreshold > params.committeeSize) {
+      throw new Error("Threshold cannot exceed committee size");
+    }
+    for (let i = 0; i < params.committeeSize; i++) {
+      if (!params.committeeElgamalPubkeys[i] || params.committeeElgamalPubkeys[i].length !== 32) {
+        throw new Error(`Committee member ${i} ElGamal pubkey must be 32 bytes`);
+      }
+    }
+    const tx = new import_web34.Transaction();
+    return tx;
+  }
+  /**
+   * Build submit decryption share transaction
+   *
+   * Called by a committee member during the reveal phase.
+   * Each member computes partial decryptions and a DLEQ proof off-chain:
+   * ```rust
+   * let partial = generate_partial_decryption(&secret_share, &pk, &r_for, &r_against, &r_abstain);
+   * ```
+   *
+   * @param params - Decryption share with DLEQ proof
+   */
+  async buildSubmitDecryptionShareTransaction(params) {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    const fields = [
+      { name: "partialFor", value: params.partialFor },
+      { name: "partialAgainst", value: params.partialAgainst },
+      { name: "partialAbstain", value: params.partialAbstain },
+      { name: "dleqChallenge", value: params.dleqChallenge },
+      { name: "dleqResponse", value: params.dleqResponse }
+    ];
+    for (const { name, value } of fields) {
+      if (value.length !== 32) {
+        throw new Error(`${name} must be 32 bytes`);
+      }
+    }
+    const tx = new import_web34.Transaction();
+    return tx;
+  }
+  /**
+   * Build aggregate revealed votes transaction (permissionless)
+   *
+   * Anyone can submit the aggregated tally since the on-chain program
+   * cryptographically verifies: tally * H == C_sum - D for each category.
+   * This prevents fabrication of results.
+   *
+   * Use the `zk-voting-sdk` to compute the tally off-chain:
+   * ```rust
+   * let lagrange = compute_lagrange_coefficients(&selected_indices);
+   * let d = combine_partials(&lagrange, &partials);
+   * let tally = recover_tally(&d, &accumulated_c, max_votes).unwrap();
+   * ```
+   *
+   * @param params - Tally values and Lagrange coefficients
+   */
+  async buildAggregateRevealedVotesTransaction(params) {
+    for (let i = 0; i < params.lagrangeCoefficients.length; i++) {
+      if (params.lagrangeCoefficients[i].length !== 32) {
+        throw new Error(`Lagrange coefficient ${i} must be 32 bytes`);
+      }
+    }
+    const tx = new import_web34.Transaction();
+    return tx;
+  }
+  /**
+   * Check if authority transfer timelock has elapsed (H-02)
+   */
+  async canAcceptAuthority() {
+    const config = await this.getConfig();
+    if (!config) {
+      return { canAccept: false, reason: "Config not found" };
+    }
+    if (!config.pendingAuthorityActivatedAt || config.pendingAuthorityActivatedAt.isZero()) {
+      return { canAccept: false, reason: "No pending authority transfer" };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const timelockEnd = config.pendingAuthorityActivatedAt.toNumber() + GOVERNANCE_CONSTANTS.authorityTransferTimelock;
+    if (now < timelockEnd) {
+      const remaining = timelockEnd - now;
+      const hours = Math.ceil(remaining / 3600);
+      return { canAccept: false, reason: `Timelock: ${hours} hours remaining` };
+    }
+    return { canAccept: true };
+  }
 };
 
 // src/rewards/index.ts
@@ -1195,9 +1391,16 @@ var RewardsClient = class {
   }
   /**
    * Calculate gasless fee for claim
+   *
+   * C-05: Uses ceiling division to prevent fee rounding to zero on small amounts.
+   * Formula: fee = ceil(amount * feeBps / 10000)
    */
   calculateGaslessFee(amount) {
-    const fee = amount.muln(SSCRE_CONSTANTS.gaslessFeeBps).divn(1e4);
+    const numerator = amount.muln(SSCRE_CONSTANTS.gaslessFeeBps).addn(9999);
+    let fee = numerator.divn(1e4);
+    if (fee.gt(amount)) {
+      fee = amount;
+    }
     return fee;
   }
   /**
@@ -1254,6 +1457,9 @@ var RewardsClient = class {
   // ============ Transaction Building ============
   /**
    * Build claim rewards transaction
+   *
+   * H-NEW-02: Merkle proof size is limited to 32 levels (supports 4B+ users).
+   * Proofs exceeding this limit will be rejected on-chain with MerkleProofTooLarge.
    */
   async buildClaimTransaction(params) {
     if (!this.client.publicKey) {
@@ -1262,6 +1468,9 @@ var RewardsClient = class {
     if (params.amount.lt(new import_anchor4.BN(SSCRE_CONSTANTS.minClaimAmount * 1e9))) {
       throw new Error(`Claim amount below minimum: ${SSCRE_CONSTANTS.minClaimAmount} VCoin`);
     }
+    if (params.merkleProof.length > 32) {
+      throw new Error("Merkle proof exceeds maximum size of 32 levels");
+    }
     const hasClaimed = await this.hasClaimedEpoch(params.epoch);
     if (hasClaimed) {
       throw new Error("Already claimed for this epoch");
@@ -1280,6 +1489,9 @@ var ViLinkClient = class {
   }
   /**
    * Get ViLink configuration
+   * 
+   * Finding #8 (related): Corrected byte offsets to match on-chain ViLinkConfig struct.
+   * Added pending_authority field that was missing after H-02 security fix.
    */
   async getConfig() {
     try {
@@ -1291,16 +1503,18 @@ var ViLinkClient = class {
       const data = accountInfo.data;
       return {
         authority: new import_web36.PublicKey(data.slice(8, 40)),
-        vcoinMint: new import_web36.PublicKey(data.slice(40, 72)),
-        treasury: new import_web36.PublicKey(data.slice(72, 104)),
-        enabledActions: data[200],
-        totalActionsCreated: new import_anchor5.BN(data.slice(201, 209), "le"),
-        totalActionsExecuted: new import_anchor5.BN(data.slice(209, 217), "le"),
-        totalTipVolume: new import_anchor5.BN(data.slice(217, 225), "le"),
-        paused: data[225] !== 0,
-        platformFeeBps: data.readUInt16LE(226)
+        pendingAuthority: new import_web36.PublicKey(data.slice(40, 72)),
+        vcoinMint: new import_web36.PublicKey(data.slice(72, 104)),
+        treasury: new import_web36.PublicKey(data.slice(104, 136)),
+        enabledActions: data[296],
+        totalActionsCreated: new import_anchor5.BN(data.slice(297, 305), "le"),
+        totalActionsExecuted: new import_anchor5.BN(data.slice(305, 313), "le"),
+        totalTipVolume: new import_anchor5.BN(data.slice(313, 321), "le"),
+        paused: data[321] !== 0,
+        platformFeeBps: data.readUInt16LE(322)
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] vilink.getConfig failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1330,7 +1544,8 @@ var ViLinkClient = class {
         actionNonce: nonce
         // M-04: Store nonce for reference
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] vilink.getAction failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1364,7 +1579,8 @@ var ViLinkClient = class {
         vcoinSent: new import_anchor5.BN(data.slice(72, 80), "le"),
         vcoinReceived: new import_anchor5.BN(data.slice(80, 88), "le")
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] vilink.getUserStats failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1416,9 +1632,16 @@ var ViLinkClient = class {
   }
   /**
    * Calculate platform fee for tip
+   *
+   * C-06: Uses ceiling division to prevent fee rounding to zero on small amounts.
+   * Formula: fee = ceil(amount * feeBps / 10000)
    */
   calculateFee(amount) {
-    const fee = amount.muln(VILINK_CONSTANTS.platformFeeBps).divn(1e4);
+    const numerator = amount.muln(VILINK_CONSTANTS.platformFeeBps).addn(9999);
+    let fee = numerator.divn(1e4);
+    if (fee.gt(amount)) {
+      fee = amount;
+    }
     return {
       fee,
       net: amount.sub(fee)
@@ -1500,6 +1723,13 @@ var ViLinkClient = class {
    * Build execute tip action transaction
    * @param creator - The action creator's public key
    * @param nonce - M-04: The action nonce (NOT timestamp)
+   *
+   * H-05: The on-chain handler validates that the executor's token account has
+   * no active delegation (delegate is None or delegated_amount is 0).
+   * This prevents delegated tokens from being spent without explicit approval.
+   *
+   * C-06: Platform fee uses ceiling division to prevent zero-fee exploitation on
+   * small amounts.
    */
   async buildExecuteTipAction(creator, nonce) {
     if (!this.client.publicKey) {
@@ -1538,6 +1768,10 @@ var GaslessClient = class {
   }
   /**
    * Get gasless configuration
+   * 
+   * Finding #8 Fix: Corrected byte offsets to match on-chain GaslessConfig struct.
+   * Added missing fields: pendingAuthority, feeVault, sscreProgram, sscreDeductionBps,
+   * maxSubsidizedPerUser, totalSolSpent, currentDay, daySpent, maxSlippageBps.
    */
   async getConfig() {
     try {
@@ -1549,16 +1783,26 @@ var GaslessClient = class {
       const data = accountInfo.data;
       return {
         authority: new import_web37.PublicKey(data.slice(8, 40)),
-        feePayer: new import_web37.PublicKey(data.slice(40, 72)),
-        vcoinMint: new import_web37.PublicKey(data.slice(72, 104)),
-        dailySubsidyBudget: new import_anchor6.BN(data.slice(136, 144), "le"),
-        solFeePerTx: new import_anchor6.BN(data.slice(144, 152), "le"),
-        vcoinFeeMultiplier: new import_anchor6.BN(data.slice(152, 160), "le"),
-        totalSubsidizedTx: new import_anchor6.BN(data.slice(168, 176), "le"),
-        totalVcoinCollected: new import_anchor6.BN(data.slice(184, 192), "le"),
-        paused: data[192] !== 0
+        pendingAuthority: new import_web37.PublicKey(data.slice(40, 72)),
+        feePayer: new import_web37.PublicKey(data.slice(72, 104)),
+        vcoinMint: new import_web37.PublicKey(data.slice(104, 136)),
+        feeVault: new import_web37.PublicKey(data.slice(136, 168)),
+        sscreProgram: new import_web37.PublicKey(data.slice(168, 200)),
+        dailySubsidyBudget: new import_anchor6.BN(data.slice(200, 208), "le"),
+        solFeePerTx: new import_anchor6.BN(data.slice(208, 216), "le"),
+        vcoinFeeMultiplier: new import_anchor6.BN(data.slice(216, 224), "le"),
+        sscreDeductionBps: data.readUInt16LE(224),
+        maxSubsidizedPerUser: data.readUInt32LE(226),
+        totalSubsidizedTx: new import_anchor6.BN(data.slice(230, 238), "le"),
+        totalSolSpent: new import_anchor6.BN(data.slice(238, 246), "le"),
+        totalVcoinCollected: new import_anchor6.BN(data.slice(246, 254), "le"),
+        paused: data[254] !== 0,
+        currentDay: data.readUInt32LE(255),
+        daySpent: new import_anchor6.BN(data.slice(259, 267), "le"),
+        maxSlippageBps: data.readUInt16LE(267)
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] gasless.getConfig failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1586,12 +1830,16 @@ var GaslessClient = class {
         isRevoked: data[114] !== 0,
         feeMethod: data[123]
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] gasless.getSessionKey failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
   /**
    * Get user gasless statistics
+   *
+   * H-AUDIT-12: Now includes active_sessions field for per-user session limit tracking.
+   * The protocol enforces a maximum of 5 concurrent active sessions per user.
    */
   async getUserStats(user) {
     const target = user || this.client.publicKey;
@@ -1611,9 +1859,11 @@ var GaslessClient = class {
         totalSubsidized: new import_anchor6.BN(data.slice(48, 56), "le"),
         totalVcoinFees: new import_anchor6.BN(data.slice(56, 64), "le"),
         sessionsCreated: data.readUInt32LE(72),
-        activeSession: new import_web37.PublicKey(data.slice(76, 108))
+        activeSessions: data[76],
+        activeSession: new import_web37.PublicKey(data.slice(77, 109))
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] gasless.getUserStats failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1747,6 +1997,9 @@ var GaslessClient = class {
   // ============ Transaction Building ============
   /**
    * Build create session key transaction
+   *
+   * H-AUDIT-12: The protocol enforces a maximum of 5 concurrent active sessions per user.
+   * Creating a session when the limit is reached will fail with MaxSessionsReached error.
    */
   async buildCreateSessionTransaction(params) {
     if (!this.client.publicKey) {
@@ -1758,6 +2011,10 @@ var GaslessClient = class {
     if (!params.scope || params.scope === 0) {
       throw new Error("At least one scope required");
     }
+    const stats = await this.getUserStats();
+    if (stats && stats.activeSessions >= 5) {
+      throw new Error("Maximum active sessions reached (5). Revoke an existing session first.");
+    }
     const duration = params.durationSeconds || GASLESS_CONSTANTS.sessionDuration;
     const maxActions = params.maxActions || GASLESS_CONSTANTS.maxSessionActions;
     const maxSpend = params.maxSpend || new import_anchor6.BN(GASLESS_CONSTANTS.maxSessionSpend * 1e9);
@@ -1868,6 +2125,23 @@ var IdentityClient = class {
     return benefits[level] || [];
   }
   // ============ Transaction Building ============
+  /**
+   * Build subscribe transaction
+   *
+   * C-AUDIT-22: Non-free subscription tiers require actual USDC payment via SPL
+   * transfer_checked. The transaction must include the user's USDC token account,
+   * the USDC mint, and the treasury token account.
+   */
+  async buildSubscribeTransaction(tier) {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    if (tier < 0 || tier > 4) {
+      throw new Error("Invalid subscription tier (0-4)");
+    }
+    const tx = new import_web38.Transaction();
+    return tx;
+  }
   /**
    * Build create identity transaction
    */
@@ -2020,6 +2294,12 @@ var FiveAClient = class {
   }
   /**
    * Check if user can vouch for another
+   *
+   * C-08: Mutual vouching is prevented — if the target has already vouched for you,
+   * you cannot vouch for them. This is enforced on-chain via reverse_vouch_record check.
+   *
+   * M-18: Vouches expire after 1 year (MAX_VOUCH_AGE = 365 days). Expired vouches
+   * cannot be evaluated and must be re-created.
    */
   async canVouchFor(target) {
     if (!this.client.publicKey) {
@@ -2062,6 +2342,12 @@ var FiveAClient = class {
   // ============ Transaction Building ============
   /**
    * Build vouch transaction
+   *
+   * C-08: On-chain handler requires a reverse_vouch_record account to verify
+   * mutual vouching is not occurring. The transaction must include this PDA.
+   *
+   * M-18: Vouches have a maximum age of 1 year. After that, evaluate_vouch
+   * will reject with VouchExpired error.
    */
   async buildVouchTransaction(target) {
     if (!this.client.publicKey) {
@@ -2230,6 +2516,9 @@ var ContentClient = class {
   }
   /**
    * Get content stats
+   *
+   * C-AUDIT-10: Engagement scores can only increase — the on-chain update_engagement
+   * instruction enforces monotonic increase to prevent manipulation.
    */
   async getContentStats(contentId) {
     const content = await this.getContent(contentId);
@@ -2249,6 +2538,9 @@ var ContentClient = class {
   // ============ Transaction Building ============
   /**
    * Build create content transaction
+   *
+   * C-AUDIT-11: Energy tiers are validated on-chain (valid range: 1-4).
+   * Tier determines max energy and regen rate.
    */
   async buildCreateContentTransaction(contentHash) {
     if (!this.client.publicKey) {
@@ -2388,6 +2680,9 @@ var ViWoClient = class {
   }
   /**
    * Get VCoin balance
+   * 
+   * Finding #2 Fix: Now filters by VCoin mint address instead of summing all Token-2022 accounts.
+   * Make sure to set programIds.vcoinMint in your ViWoClient config.
    */
   async getVCoinBalance(user) {
     const target = user || this.publicKey;
@@ -2397,7 +2692,7 @@ var ViWoClient = class {
     try {
       const tokenAccounts = await this.connection.connection.getTokenAccountsByOwner(
         target,
-        { programId: import_spl_token.TOKEN_2022_PROGRAM_ID }
+        { mint: this.programIds.vcoinMint, programId: import_spl_token.TOKEN_2022_PROGRAM_ID }
       );
       let balance = new import_anchor10.BN(0);
       for (const { account } of tokenAccounts.value) {
@@ -2406,7 +2701,8 @@ var ViWoClient = class {
         balance = balance.add(new import_anchor10.BN(amount, "le"));
       }
       return balance;
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] getVCoinBalance failed:", error instanceof Error ? error.message : error);
       return new import_anchor10.BN(0);
     }
   }
@@ -2421,7 +2717,8 @@ var ViWoClient = class {
     try {
       const stakeData = await this.staking.getUserStake(target);
       return stakeData?.vevcoinBalance || new import_anchor10.BN(0);
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] getVeVCoinBalance failed:", error instanceof Error ? error.message : error);
       return new import_anchor10.BN(0);
     }
   }
@@ -2436,7 +2733,8 @@ var ViWoClient = class {
       ]);
       const blockTime = await this.connection.getBlockTime();
       return { connected, slot, blockTime };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] healthCheck failed:", error instanceof Error ? error.message : error);
       return { connected: false, slot: null, blockTime: null };
     }
   }