@viwoapp/sdk 0.1.8 → 2.0.1

package/dist/index.mjs

@@ -204,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
@@ -241,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;
@@ -340,6 +366,22 @@ var PDAs = class {
     );
     return pda;
   }
+  /** H-NEW-03: Delegation PDA (one per delegator) */
+  getDelegation(delegator) {
+    const [pda] = PublicKey2.findProgramAddressSync(
+      [Buffer.from(SEEDS.delegation), delegator.toBuffer()],
+      this.programIds.governanceProtocol
+    );
+    return pda;
+  }
+  /** H-NEW-03: Delegate stats PDA (one per delegate) */
+  getDelegateStats(delegate) {
+    const [pda] = PublicKey2.findProgramAddressSync(
+      [Buffer.from("delegate-stats"), delegate.toBuffer()],
+      this.programIds.governanceProtocol
+    );
+    return pda;
+  }
   // SSCRE PDAs
   getRewardsPoolConfig() {
     const [pda] = PublicKey2.findProgramAddressSync(
@@ -679,6 +721,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"];
@@ -790,11 +836,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;
@@ -867,7 +916,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;
@@ -882,6 +935,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;
@@ -924,6 +980,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);
@@ -947,7 +1006,7 @@ var GovernanceClient = class {
       timeRemaining
     };
   }
-  // ============ Transaction Building ============
+  // ============ Transaction Building (Public Voting) ============
   /**
    * Build create proposal transaction
    */
@@ -963,12 +1022,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)
    */
@@ -998,6 +1057,217 @@ var GovernanceClient = class {
     const tx = new Transaction3();
     return tx;
   }
+  // ============ Vote Delegation (H-NEW-03) ============
+  /**
+   * Get delegation for a user
+   */
+  async getDelegation(delegator) {
+    const target = delegator || this.client.publicKey;
+    if (!target) {
+      throw new Error("No user specified and wallet not connected");
+    }
+    try {
+      const delegationPda = this.client.pdas.getDelegation(target);
+      const accountInfo = await this.client.connection.connection.getAccountInfo(delegationPda);
+      if (!accountInfo) {
+        return null;
+      }
+      const data = accountInfo.data;
+      return {
+        delegator: new PublicKey4(data.slice(8, 40)),
+        delegate: new PublicKey4(data.slice(40, 72)),
+        delegationType: data[72],
+        categories: data[73],
+        delegatedAmount: new BN3(data.slice(74, 82), "le"),
+        delegatedAt: new BN3(data.slice(82, 90), "le"),
+        expiresAt: new BN3(data.slice(90, 98), "le"),
+        revocable: data[98] !== 0
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Build delegate votes transaction
+   *
+   * H-NEW-03: Validates delegation amount against actual veVCoin balance on-chain.
+   * The delegated amount must be <= the delegator's veVCoin balance from the staking protocol.
+   *
+   * @param params - Delegation parameters
+   */
+  async buildDelegateVotesTransaction(params) {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    const delegationPda = this.client.pdas.getDelegation(this.client.publicKey);
+    const delegateStatsPda = this.client.pdas.getDelegateStats(params.delegate);
+    const configPda = this.client.pdas.getGovernanceConfig();
+    const userStakePda = this.client.pdas.getUserStake(this.client.publicKey);
+    const existing = await this.getDelegation();
+    if (existing) {
+      throw new Error("Active delegation already exists. Revoke it first.");
+    }
+    const tx = new Transaction3();
+    return tx;
+  }
+  /**
+   * Build revoke delegation transaction
+   */
+  async buildRevokeDelegationTransaction() {
+    if (!this.client.publicKey) {
+      throw new Error("Wallet not connected");
+    }
+    const existing = await this.getDelegation();
+    if (!existing) {
+      throw new Error("No active delegation to revoke");
+    }
+    const delegationPda = this.client.pdas.getDelegation(this.client.publicKey);
+    const delegateStatsPda = this.client.pdas.getDelegateStats(existing.delegate);
+    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
@@ -1137,9 +1407,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;
   }
   /**
@@ -1196,6 +1473,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) {
@@ -1204,6 +1484,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");
@@ -1365,9 +1648,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)
@@ -1449,6 +1739,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) {
@@ -1556,6 +1853,9 @@ var GaslessClient = class {
   }
   /**
    * 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;
@@ -1575,7 +1875,8 @@ 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 (error) {
       console.warn("[ViWoSDK] gasless.getUserStats failed:", error instanceof Error ? error.message : error);
@@ -1712,6 +2013,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) {
@@ -1723,6 +2027,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);
@@ -1833,6 +2141,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
    */
@@ -1985,6 +2310,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) {
@@ -2027,6 +2358,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) {
@@ -2195,6 +2532,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);
@@ -2214,6 +2554,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) {