@viwoapp/sdk 0.1.7 → 2.0.0

package/dist/index.mjs

@@ -19,7 +19,18 @@ var PROGRAM_IDS = {
   governanceProtocol: new PublicKey("3R256kBN9iXozjypQFRAmegBhd6HJqXWqdNG7Th78HYe"),
   sscreProtocol: new PublicKey("6AJNcQSfoiE2UAeUDyJUBumS9SBwhAdSznoAeYpXrxXZ"),
   vilinkProtocol: new PublicKey("CFGXTS2MueQwTYTMMTBQbRWzJtSTC2p4ZRuKPpLDmrv7"),
-  gaslessProtocol: new PublicKey("FcXJAjzJs8eVY2WTRFXynQBpC7WZUqKZppyp9xS6PaB3")
+  gaslessProtocol: new 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 PublicKey("11111111111111111111111111111111")
+  // Placeholder - override in config
 };
 var SEEDS = {
   // VCoin
@@ -193,9 +204,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
@@ -230,8 +254,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;
@@ -668,6 +705,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"];
@@ -779,11 +820,14 @@ var GovernanceClient = class {
       if (!accountInfo) {
         return null;
       }
+      const data = accountInfo.data;
       return {
-        authority: new PublicKey4(accountInfo.data.slice(8, 40)),
-        proposalCount: new BN3(accountInfo.data.slice(40, 48), "le"),
-        vevcoinMint: new PublicKey4(accountInfo.data.slice(48, 80)),
-        paused: accountInfo.data[80] !== 0
+        authority: new PublicKey4(data.slice(8, 40)),
+        proposalCount: new BN3(data.slice(40, 48), "le"),
+        vevcoinMint: new PublicKey4(data.slice(48, 80)),
+        paused: data[80] !== 0,
+        pendingAuthority: new PublicKey4(data.slice(81, 113)),
+        pendingAuthorityActivatedAt: new BN3(data.slice(113, 121), "le")
       };
     } catch {
       return null;
@@ -856,7 +900,11 @@ var GovernanceClient = class {
         proposal: new PublicKey4(data.slice(40, 72)),
         votePower: new BN3(data.slice(72, 80), "le"),
         support: data[80] !== 0,
-        votedAt: new BN3(data.slice(81, 89), "le")
+        votedAt: new BN3(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;
@@ -871,6 +919,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;
@@ -913,6 +964,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);
@@ -936,7 +990,7 @@ var GovernanceClient = class {
       timeRemaining
     };
   }
-  // ============ Transaction Building ============
+  // ============ Transaction Building (Public Voting) ============
   /**
    * Build create proposal transaction
    */
@@ -952,12 +1006,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)
    */
@@ -987,6 +1041,148 @@ var GovernanceClient = class {
     const tx = new Transaction3();
     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 Transaction3();
+    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 Transaction3();
+    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 Transaction3();
+    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 Transaction3();
+    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
@@ -1126,9 +1322,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;
   }
   /**
@@ -1185,6 +1388,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) {
@@ -1193,6 +1399,9 @@ var RewardsClient = class {
     if (params.amount.lt(new BN4(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");
@@ -1211,6 +1420,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 {
@@ -1222,16 +1434,18 @@ var ViLinkClient = class {
       const data = accountInfo.data;
       return {
         authority: new PublicKey6(data.slice(8, 40)),
-        vcoinMint: new PublicKey6(data.slice(40, 72)),
-        treasury: new PublicKey6(data.slice(72, 104)),
-        enabledActions: data[200],
-        totalActionsCreated: new BN5(data.slice(201, 209), "le"),
-        totalActionsExecuted: new BN5(data.slice(209, 217), "le"),
-        totalTipVolume: new BN5(data.slice(217, 225), "le"),
-        paused: data[225] !== 0,
-        platformFeeBps: data.readUInt16LE(226)
+        pendingAuthority: new PublicKey6(data.slice(40, 72)),
+        vcoinMint: new PublicKey6(data.slice(72, 104)),
+        treasury: new PublicKey6(data.slice(104, 136)),
+        enabledActions: data[296],
+        totalActionsCreated: new BN5(data.slice(297, 305), "le"),
+        totalActionsExecuted: new BN5(data.slice(305, 313), "le"),
+        totalTipVolume: new BN5(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;
     }
   }
@@ -1261,7 +1475,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;
     }
   }
@@ -1295,7 +1510,8 @@ var ViLinkClient = class {
         vcoinSent: new BN5(data.slice(72, 80), "le"),
         vcoinReceived: new BN5(data.slice(80, 88), "le")
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] vilink.getUserStats failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1347,9 +1563,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)
@@ -1431,6 +1654,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) {
@@ -1469,6 +1699,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 {
@@ -1480,16 +1714,26 @@ var GaslessClient = class {
       const data = accountInfo.data;
       return {
         authority: new PublicKey7(data.slice(8, 40)),
-        feePayer: new PublicKey7(data.slice(40, 72)),
-        vcoinMint: new PublicKey7(data.slice(72, 104)),
-        dailySubsidyBudget: new BN6(data.slice(136, 144), "le"),
-        solFeePerTx: new BN6(data.slice(144, 152), "le"),
-        vcoinFeeMultiplier: new BN6(data.slice(152, 160), "le"),
-        totalSubsidizedTx: new BN6(data.slice(168, 176), "le"),
-        totalVcoinCollected: new BN6(data.slice(184, 192), "le"),
-        paused: data[192] !== 0
+        pendingAuthority: new PublicKey7(data.slice(40, 72)),
+        feePayer: new PublicKey7(data.slice(72, 104)),
+        vcoinMint: new PublicKey7(data.slice(104, 136)),
+        feeVault: new PublicKey7(data.slice(136, 168)),
+        sscreProgram: new PublicKey7(data.slice(168, 200)),
+        dailySubsidyBudget: new BN6(data.slice(200, 208), "le"),
+        solFeePerTx: new BN6(data.slice(208, 216), "le"),
+        vcoinFeeMultiplier: new BN6(data.slice(216, 224), "le"),
+        sscreDeductionBps: data.readUInt16LE(224),
+        maxSubsidizedPerUser: data.readUInt32LE(226),
+        totalSubsidizedTx: new BN6(data.slice(230, 238), "le"),
+        totalSolSpent: new BN6(data.slice(238, 246), "le"),
+        totalVcoinCollected: new BN6(data.slice(246, 254), "le"),
+        paused: data[254] !== 0,
+        currentDay: data.readUInt32LE(255),
+        daySpent: new BN6(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;
     }
   }
@@ -1517,12 +1761,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;
@@ -1542,9 +1790,11 @@ var GaslessClient = class {
         totalSubsidized: new BN6(data.slice(48, 56), "le"),
         totalVcoinFees: new BN6(data.slice(56, 64), "le"),
         sessionsCreated: data.readUInt32LE(72),
-        activeSession: new PublicKey7(data.slice(76, 108))
+        activeSessions: data[76],
+        activeSession: new PublicKey7(data.slice(77, 109))
       };
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] gasless.getUserStats failed:", error instanceof Error ? error.message : error);
       return null;
     }
   }
@@ -1678,6 +1928,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) {
@@ -1689,6 +1942,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 BN6(GASLESS_CONSTANTS.maxSessionSpend * 1e9);
@@ -1799,6 +2056,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 Transaction7();
+    return tx;
+  }
   /**
    * Build create identity transaction
    */
@@ -1951,6 +2225,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) {
@@ -1993,6 +2273,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) {
@@ -2161,6 +2447,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);
@@ -2180,6 +2469,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) {
@@ -2319,6 +2611,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;
@@ -2328,7 +2623,7 @@ var ViWoClient = class {
     try {
       const tokenAccounts = await this.connection.connection.getTokenAccountsByOwner(
         target,
-        { programId: TOKEN_2022_PROGRAM_ID }
+        { mint: this.programIds.vcoinMint, programId: TOKEN_2022_PROGRAM_ID }
       );
       let balance = new BN10(0);
       for (const { account } of tokenAccounts.value) {
@@ -2337,7 +2632,8 @@ var ViWoClient = class {
         balance = balance.add(new BN10(amount, "le"));
       }
       return balance;
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] getVCoinBalance failed:", error instanceof Error ? error.message : error);
       return new BN10(0);
     }
   }
@@ -2352,7 +2648,8 @@ var ViWoClient = class {
     try {
       const stakeData = await this.staking.getUserStake(target);
       return stakeData?.vevcoinBalance || new BN10(0);
-    } catch {
+    } catch (error) {
+      console.warn("[ViWoSDK] getVeVCoinBalance failed:", error instanceof Error ? error.message : error);
       return new BN10(0);
     }
   }
@@ -2367,7 +2664,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 };
     }
   }