@viwoapp/sdk 0.1.8 → 2.0.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { PublicKey, Connection, Commitment, Transaction, VersionedTransaction, TransactionInstruction } from '@solana/web3.js';
+import { PublicKey, Commitment, Connection, Transaction, VersionedTransaction, TransactionInstruction } from '@solana/web3.js';
 import { BN, AnchorProvider } from '@coral-xyz/anchor';
 export { BN } from '@coral-xyz/anchor';
 
@@ -173,7 +173,20 @@ declare const GOVERNANCE_CONSTANTS: {
     executionDelay: number;
     vetoWindow: number;
     quorumBps: number;
-    zkVotingEnabled: boolean;
+    /** Authority transfer timelock (H-02) */
+    authorityTransferTimelock: number;
+    /** ZK private voting constants */
+    zk: {
+        /** Vote validity proof size (3 OR proofs + 1 sum proof) */
+        voteProofSize: number;
+        /** ElGamal ciphertext size (R || C) */
+        ciphertextSize: number;
+        /** Max committee members */
+        maxCommitteeSize: number;
+        /** Account sizes */
+        privateVotingConfigSize: number;
+        decryptionShareSize: number;
+    };
 };
 declare const SECURITY_CONSTANTS: {
     authorityTransferTimelock: number;
@@ -189,6 +202,18 @@ declare const SECURITY_CONSTANTS: {
     merkleProofMaxSize: number;
     maxEpochBitmap: number;
     votingPowerVerifiedOnChain: boolean;
+    /** H-AUDIT-12: Maximum concurrent sessions per user */
+    maxSessionsPerUser: number;
+    /** C-AUDIT-15: Maximum day delta for daily budget reset (clock skew protection) */
+    maxDayDelta: number;
+    /** H-AUDIT-09: Maximum daily activity score for transfer hook */
+    maxDailyActivityScore: number;
+    /** M-AUDIT-10: Wash flag decay period (7 days) */
+    washFlagDecayPeriod: number;
+    /** M-18: Maximum vouch age before expiry (1 year) */
+    maxVouchAge: number;
+    /** C-AUDIT-11: Valid content energy tiers (1-4) */
+    maxContentTier: number;
 };
 declare const VALID_URI_PREFIXES: readonly ["ipfs://", "https://", "ar://"];
 declare const MAX_URI_LENGTH = 128;
@@ -394,6 +419,12 @@ interface VoteRecord {
     votePower: BN;
     support: boolean;
     votedAt: BN;
+    /** ElGamal ciphertext for "for" vote (64 bytes: R || C) - only set for private votes */
+    ctFor?: Uint8Array;
+    /** ElGamal ciphertext for "against" vote (64 bytes: R || C) - only set for private votes */
+    ctAgainst?: Uint8Array;
+    /** ElGamal ciphertext for "abstain" vote (64 bytes: R || C) - only set for private votes */
+    ctAbstain?: Uint8Array;
 }
 interface CreateProposalParams {
     title: string;
@@ -574,6 +605,8 @@ interface UserGaslessStats {
     totalVcoinFees: BN;
     sessionsCreated: number;
     activeSession: PublicKey;
+    /** H-AUDIT-12: Number of active (non-revoked, non-expired) sessions */
+    activeSessions: number;
 }
 declare enum VerificationLevel {
     None = 0,// Wallet connected only
@@ -650,26 +683,52 @@ interface GovernanceConfig extends PendingAuthorityFields {
     vevcoinMint: PublicKey;
     paused: boolean;
     proposalCount: BN;
-    zkVotingEnabled: boolean;
+    /** H-02: Timestamp when pending authority transfer was initiated (for 24h timelock) */
+    pendingAuthorityActivatedAt: BN;
 }
-/** ZK voting decryption share storage (C-02) */
+/** ZK voting decryption share with per-category partials and DLEQ proof */
 interface DecryptionShare {
     proposal: PublicKey;
     committeeIndex: number;
     committeeMember: PublicKey;
-    share: Uint8Array;
+    /** Partial decryption: sk_j * R_for_sum (Ristretto255 point) */
+    partialFor: Uint8Array;
+    /** Partial decryption: sk_j * R_against_sum (Ristretto255 point) */
+    partialAgainst: Uint8Array;
+    /** Partial decryption: sk_j * R_abstain_sum (Ristretto255 point) */
+    partialAbstain: Uint8Array;
+    /** Batched DLEQ proof challenge (Scalar) */
+    dleqChallenge: Uint8Array;
+    /** Batched DLEQ proof response (Scalar) */
+    dleqResponse: Uint8Array;
     submittedAt: BN;
+    verified: boolean;
 }
-/** Private voting config with committee tracking (C-02) */
+/** Private voting config with ZK cryptographic verification */
 interface PrivateVotingConfig {
     proposal: PublicKey;
-    encryptionPubkey: PublicKey;
+    /** Joint ElGamal public key (Ristretto255 point, 32 bytes) */
+    encryptionPubkey: Uint8Array;
     decryptionThreshold: number;
     decryptionCommittee: PublicKey[];
+    /** Committee ElGamal public keys (Ristretto255 points) */
+    committeeElgamalPubkeys: Uint8Array[];
     sharesSubmitted: boolean[];
     revealCompleted: boolean;
     aggregatedFor: BN;
     aggregatedAgainst: BN;
+    aggregatedAbstain: BN;
+    /** Verification hash for audit trail */
+    verificationHash: Uint8Array;
+    /** Homomorphically accumulated ciphertext components */
+    accumulatedCtForR: Uint8Array;
+    accumulatedCtForC: Uint8Array;
+    accumulatedCtAgainstR: Uint8Array;
+    accumulatedCtAgainstC: Uint8Array;
+    accumulatedCtAbstainR: Uint8Array;
+    accumulatedCtAbstainC: Uint8Array;
+    /** Number of private votes cast */
+    totalPrivateVotes: number;
 }
 /** Delegation with expiry (M-07) */
 interface Delegation {
@@ -692,6 +751,8 @@ interface PendingScoreUpdate {
     submissionCount: number;
     createdAt: BN;
     expiresAt: BN;
+    /** C-07: Immutable consensus count stored at creation time */
+    requiredConsensus: number;
 }
 interface HookConfig extends PendingAuthorityFields {
     authority: PublicKey;
@@ -699,10 +760,82 @@ interface HookConfig extends PendingAuthorityFields {
     blockWashTrading: boolean;
     paused: boolean;
 }
+/** Pair tracking for wash trade detection */
+interface PairTracking {
+    sender: PublicKey;
+    receiver: PublicKey;
+    transferCount: number;
+    lastTransferTime: BN;
+    washFlags: number;
+    /** M-AUDIT-10: Timestamp of last wash flag for decay */
+    lastFlagTime: BN;
+}
+interface VeVCoinConfig extends PendingAuthorityFields {
+    authority: PublicKey;
+    vcoinMint: PublicKey;
+    vevcoinMint: PublicKey;
+    stakingProtocol: PublicKey;
+    totalHolders: BN;
+    totalMinted: BN;
+    paused: boolean;
+    /** C-01: Timestamp when pending authority transfer was initiated (for 24h timelock) */
+    pendingAuthorityActivatedAt: BN;
+}
+/** Parameters for casting a private vote */
+interface CastPrivateVoteParams {
+    proposalId: BN;
+    /** ElGamal ciphertext for "for" (64 bytes) */
+    ctFor: Uint8Array;
+    /** ElGamal ciphertext for "against" (64 bytes) */
+    ctAgainst: Uint8Array;
+    /** ElGamal ciphertext for "abstain" (64 bytes) */
+    ctAbstain: Uint8Array;
+    /** Vote validity proof (352 bytes) */
+    proofData: Uint8Array;
+}
+/** Parameters for enabling private voting on a proposal */
+interface EnablePrivateVotingParams {
+    proposalId: BN;
+    /** Joint ElGamal public key (Ristretto255 point, 32 bytes) */
+    encryptionPubkey: Uint8Array;
+    /** Committee member Solana pubkeys */
+    decryptionCommittee: PublicKey[];
+    committeeSize: number;
+    decryptionThreshold: number;
+    /** Committee member ElGamal public keys (Ristretto255 points, 32 bytes each) */
+    committeeElgamalPubkeys: Uint8Array[];
+}
+/** Parameters for submitting a decryption share */
+interface SubmitDecryptionShareParams {
+    proposalId: BN;
+    committeeIndex: number;
+    /** Partial decryption for "for" (Ristretto255 point, 32 bytes) */
+    partialFor: Uint8Array;
+    /** Partial decryption for "against" (Ristretto255 point, 32 bytes) */
+    partialAgainst: Uint8Array;
+    /** Partial decryption for "abstain" (Ristretto255 point, 32 bytes) */
+    partialAbstain: Uint8Array;
+    /** DLEQ proof challenge (Scalar, 32 bytes) */
+    dleqChallenge: Uint8Array;
+    /** DLEQ proof response (Scalar, 32 bytes) */
+    dleqResponse: Uint8Array;
+}
+/** Parameters for aggregating revealed votes (permissionless) */
+interface AggregateRevealedVotesParams {
+    proposalId: BN;
+    tallyFor: BN;
+    tallyAgainst: BN;
+    tallyAbstain: BN;
+    /** Lagrange interpolation coefficients (Scalars, 32 bytes each) */
+    lagrangeCoefficients: Uint8Array[];
+}
 
 /**
  * Governance Client for ViWoApp governance operations
  *
+ * Supports both public voting and ZK private voting with Twisted ElGamal
+ * encryption on Ristretto255.
+ *
  * @example
  * ```typescript
  * const govClient = client.governance;
@@ -715,8 +848,13 @@ interface HookConfig extends PendingAuthorityFields {
  *   durationDays: 7,
  * });
  *
- * // Vote on a proposal
- * await govClient.vote(proposalId, true); // Vote in favor
+ * // Public vote on a proposal
+ * await govClient.vote(proposalId, true);
+ *
+ * // Private vote (using zk-voting-sdk for encryption)
+ * await govClient.buildCastPrivateVoteTransaction({
+ *   proposalId, ctFor, ctAgainst, ctAbstain, proofData,
+ * });
  * ```
  */
 declare class GovernanceClient {
@@ -725,7 +863,7 @@ declare class GovernanceClient {
     /**
      * Get governance configuration
      */
-    getConfig(): Promise<any | null>;
+    getConfig(): Promise<GovernanceConfig | null>;
     /**
      * Get proposal by ID
      */
@@ -744,6 +882,9 @@ declare class GovernanceClient {
     hasVoted(proposalId: BN, user?: PublicKey): Promise<boolean>;
     /**
      * 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.
      */
     getVotingPower(user?: PublicKey): Promise<BN>;
     /**
@@ -759,6 +900,9 @@ declare class GovernanceClient {
     }>;
     /**
      * Get proposal progress
+     *
+     * @note C-03: Quorum is now calculated as votesFor + votesAgainst only.
+     * Abstains do NOT count toward quorum.
      */
     getProposalProgress(proposalId: BN): Promise<{
         votesFor: string;
@@ -774,7 +918,7 @@ declare class GovernanceClient {
      */
     buildCreateProposalTransaction(params: CreateProposalParams): Promise<Transaction>;
     /**
-     * Build vote transaction
+     * 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.
@@ -788,6 +932,66 @@ declare class GovernanceClient {
      * Build execute proposal transaction
      */
     buildExecuteTransaction(proposalId: BN): Promise<Transaction>;
+    /**
+     * 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
+     */
+    buildCastPrivateVoteTransaction(params: CastPrivateVoteParams): Promise<Transaction>;
+    /**
+     * 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
+     */
+    buildEnablePrivateVotingTransaction(params: EnablePrivateVotingParams): Promise<Transaction>;
+    /**
+     * 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
+     */
+    buildSubmitDecryptionShareTransaction(params: SubmitDecryptionShareParams): Promise<Transaction>;
+    /**
+     * 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
+     */
+    buildAggregateRevealedVotesTransaction(params: AggregateRevealedVotesParams): Promise<Transaction>;
+    /**
+     * Check if authority transfer timelock has elapsed (H-02)
+     */
+    canAcceptAuthority(): Promise<{
+        canAccept: boolean;
+        reason?: string;
+    }>;
 }
 
 /**
@@ -849,6 +1053,9 @@ declare class RewardsClient {
     }>;
     /**
      * 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: BN): BN;
     /**
@@ -867,6 +1074,9 @@ declare class RewardsClient {
     private hashBytes;
     /**
      * 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.
      */
     buildClaimTransaction(params: ClaimRewardsParams): Promise<Transaction>;
 }
@@ -935,6 +1145,9 @@ declare class ViLinkClient {
     }>;
     /**
      * 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: BN): {
         fee: BN;
@@ -988,6 +1201,13 @@ declare class ViLinkClient {
      * 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.
      */
     buildExecuteTipAction(creator: PublicKey, nonce: BN): Promise<Transaction>;
     /**
@@ -1033,6 +1253,9 @@ declare class GaslessClient {
     getSessionKey(user: PublicKey, sessionPubkey: PublicKey): Promise<SessionKey | 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.
      */
     getUserStats(user?: PublicKey): Promise<UserGaslessStats | null>;
     /**
@@ -1080,6 +1303,9 @@ declare class GaslessClient {
     createScope(actions: string[]): number;
     /**
      * 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.
      */
     buildCreateSessionTransaction(params: CreateSessionParams): Promise<Transaction>;
     /**
@@ -1130,6 +1356,14 @@ declare class IdentityClient {
      * Get verification level benefits
      */
     getVerificationBenefits(level: VerificationLevel): string[];
+    /**
+     * 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.
+     */
+    buildSubscribeTransaction(tier: number): Promise<Transaction>;
     /**
      * Build create identity transaction
      */
@@ -1190,6 +1424,12 @@ declare class FiveAClient {
     getMaxVouches(composite: number): number;
     /**
      * 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.
      */
     canVouchFor(target: PublicKey): Promise<{
         canVouch: boolean;
@@ -1201,6 +1441,12 @@ declare class FiveAClient {
     getImprovementSuggestions(score: FiveAScore): string[];
     /**
      * 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.
      */
     buildVouchTransaction(target: PublicKey): Promise<Transaction>;
 }
@@ -1265,6 +1511,9 @@ declare class ContentClient {
     }>;
     /**
      * Get content stats
+     *
+     * C-AUDIT-10: Engagement scores can only increase — the on-chain update_engagement
+     * instruction enforces monotonic increase to prevent manipulation.
      */
     getContentStats(contentId: Uint8Array): Promise<{
         tips: string;
@@ -1275,6 +1524,9 @@ declare class ContentClient {
     }>;
     /**
      * Build create content transaction
+     *
+     * C-AUDIT-11: Energy tiers are validated on-chain (valid range: 1-4).
+     * Tier determines max energy and regen rate.
      */
     buildCreateContentTransaction(contentHash: Uint8Array): Promise<Transaction>;
     /**
@@ -1411,6 +1663,10 @@ declare class StakingClient {
     calculateVeVCoin(amount: BN, lockDuration: number): BN;
     /**
      * 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: StakingTier): string;
     /**
@@ -1453,4 +1709,4 @@ declare class StakingClient {
     buildExtendLockTransaction(newDuration: number): Promise<Transaction>;
 }
 
-export { ACTION_SCOPES, ActionType, CONTENT_CONSTANTS, type ClaimRewardsParams, type ConnectionConfig, ContentClient, type ContentRecord, ContentState, type CreateActionParams, type CreateProposalParams, type CreateSessionParams, type DecryptionShare, type Delegation, type EpochDistribution, FIVE_A_CONSTANTS, FeeMethod, FiveAClient, type FiveAConfig, type FiveAScore, GASLESS_CONSTANTS, GOVERNANCE_CONSTANTS, GaslessClient, type GaslessConfig, GovernanceClient, type GovernanceConfig, type HookConfig, type Identity, IdentityClient, type IdentityConfig, LEGACY_SLASH_DEPRECATED, LOCK_DURATIONS, MAX_EPOCH_BITMAP, MAX_URI_LENGTH, MERKLE_CONSTANTS, MERKLE_PROOF_MAX_SIZE, PDAs, PROGRAM_IDS, type PendingAuthorityFields, type PendingScoreUpdate, type PrivateVotingConfig, type Proposal, ProposalStatus, type RegistryConfig, RewardsClient, type RewardsPoolConfig, SECURITY_CONSTANTS, SEEDS, SSCRE_CONSTANTS, STAKING_TIERS, type SessionKey, type SlashRequest, SlashStatus, type StakeParams, StakingClient, type StakingPool, StakingTier, TransactionBuilder, type UserActionStatsExtended, type UserClaim, type UserEnergy, type UserGaslessStats, type UserStake, VALID_URI_PREFIXES, VCOIN_DECIMALS, VCOIN_INITIAL_CIRCULATING, VCOIN_TOTAL_SUPPLY, type VCoinConfig, VEVCOIN_DECIMALS, VILINK_CONSTANTS, VerificationLevel, type ViLinkAction, ViLinkClient, type ViLinkConfig, ViWoClient, ViWoConnection, VoteChoice, type VoteRecord, type VouchRecord, type WalletAdapter, dateToTimestamp, formatVCoin, getCurrentTimestamp, parseVCoin, timestampToDate };
+export { ACTION_SCOPES, ActionType, type AggregateRevealedVotesParams, CONTENT_CONSTANTS, type CastPrivateVoteParams, type ClaimRewardsParams, type ConnectionConfig, ContentClient, type ContentRecord, ContentState, type CreateActionParams, type CreateProposalParams, type CreateSessionParams, type DecryptionShare, type Delegation, type EnablePrivateVotingParams, type EpochDistribution, FIVE_A_CONSTANTS, FeeMethod, FiveAClient, type FiveAConfig, type FiveAScore, GASLESS_CONSTANTS, GOVERNANCE_CONSTANTS, GaslessClient, type GaslessConfig, GovernanceClient, type GovernanceConfig, type HookConfig, type Identity, IdentityClient, type IdentityConfig, LEGACY_SLASH_DEPRECATED, LOCK_DURATIONS, MAX_EPOCH_BITMAP, MAX_URI_LENGTH, MERKLE_CONSTANTS, MERKLE_PROOF_MAX_SIZE, PDAs, PROGRAM_IDS, type PairTracking, type PendingAuthorityFields, type PendingScoreUpdate, type PrivateVotingConfig, type Proposal, ProposalStatus, type RegistryConfig, RewardsClient, type RewardsPoolConfig, SECURITY_CONSTANTS, SEEDS, SSCRE_CONSTANTS, STAKING_TIERS, type SessionKey, type SlashRequest, SlashStatus, type StakeParams, StakingClient, type StakingPool, StakingTier, type SubmitDecryptionShareParams, TransactionBuilder, type UserActionStatsExtended, type UserClaim, type UserEnergy, type UserGaslessStats, type UserStake, VALID_URI_PREFIXES, VCOIN_DECIMALS, VCOIN_INITIAL_CIRCULATING, VCOIN_TOTAL_SUPPLY, type VCoinConfig, VEVCOIN_DECIMALS, VILINK_CONSTANTS, type VeVCoinConfig, VerificationLevel, type ViLinkAction, ViLinkClient, type ViLinkConfig, ViWoClient, ViWoConnection, VoteChoice, type VoteRecord, type VouchRecord, type WalletAdapter, dateToTimestamp, formatVCoin, getCurrentTimestamp, parseVCoin, timestampToDate };