@viwoapp/sdk 0.1.7 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { PublicKey, Connection, Commitment, Transaction, VersionedTransaction, TransactionInstruction } from '@solana/web3.js';
1
+ import { PublicKey, Commitment, Connection, Transaction, VersionedTransaction, TransactionInstruction } from '@solana/web3.js';
2
2
  import { BN, AnchorProvider } from '@coral-xyz/anchor';
3
3
  export { BN } from '@coral-xyz/anchor';
4
4
 
@@ -14,6 +14,16 @@ declare const PROGRAM_IDS: {
14
14
  sscreProtocol: PublicKey;
15
15
  vilinkProtocol: PublicKey;
16
16
  gaslessProtocol: PublicKey;
17
+ /**
18
+ * VCoin Token Mint Address (Token-2022)
19
+ *
20
+ * NOTE: This is a placeholder. Override via ViWoClient config.programIds.vcoinMint
21
+ * after deploying your VCoin mint on devnet/mainnet.
22
+ *
23
+ * Finding #2 Fix: SDK now filters token accounts by mint address to prevent
24
+ * summing balances from other Token-2022 tokens.
25
+ */
26
+ vcoinMint: PublicKey;
17
27
  };
18
28
  declare const SEEDS: {
19
29
  vcoinConfig: string;
@@ -163,7 +173,20 @@ declare const GOVERNANCE_CONSTANTS: {
163
173
  executionDelay: number;
164
174
  vetoWindow: number;
165
175
  quorumBps: number;
166
- zkVotingEnabled: boolean;
176
+ /** Authority transfer timelock (H-02) */
177
+ authorityTransferTimelock: number;
178
+ /** ZK private voting constants */
179
+ zk: {
180
+ /** Vote validity proof size (3 OR proofs + 1 sum proof) */
181
+ voteProofSize: number;
182
+ /** ElGamal ciphertext size (R || C) */
183
+ ciphertextSize: number;
184
+ /** Max committee members */
185
+ maxCommitteeSize: number;
186
+ /** Account sizes */
187
+ privateVotingConfigSize: number;
188
+ decryptionShareSize: number;
189
+ };
167
190
  };
168
191
  declare const SECURITY_CONSTANTS: {
169
192
  authorityTransferTimelock: number;
@@ -179,6 +202,18 @@ declare const SECURITY_CONSTANTS: {
179
202
  merkleProofMaxSize: number;
180
203
  maxEpochBitmap: number;
181
204
  votingPowerVerifiedOnChain: boolean;
205
+ /** H-AUDIT-12: Maximum concurrent sessions per user */
206
+ maxSessionsPerUser: number;
207
+ /** C-AUDIT-15: Maximum day delta for daily budget reset (clock skew protection) */
208
+ maxDayDelta: number;
209
+ /** H-AUDIT-09: Maximum daily activity score for transfer hook */
210
+ maxDailyActivityScore: number;
211
+ /** M-AUDIT-10: Wash flag decay period (7 days) */
212
+ washFlagDecayPeriod: number;
213
+ /** M-18: Maximum vouch age before expiry (1 year) */
214
+ maxVouchAge: number;
215
+ /** C-AUDIT-11: Valid content energy tiers (1-4) */
216
+ maxContentTier: number;
182
217
  };
183
218
  declare const VALID_URI_PREFIXES: readonly ["ipfs://", "https://", "ar://"];
184
219
  declare const MAX_URI_LENGTH = 128;
@@ -384,6 +419,12 @@ interface VoteRecord {
384
419
  votePower: BN;
385
420
  support: boolean;
386
421
  votedAt: BN;
422
+ /** ElGamal ciphertext for "for" vote (64 bytes: R || C) - only set for private votes */
423
+ ctFor?: Uint8Array;
424
+ /** ElGamal ciphertext for "against" vote (64 bytes: R || C) - only set for private votes */
425
+ ctAgainst?: Uint8Array;
426
+ /** ElGamal ciphertext for "abstain" vote (64 bytes: R || C) - only set for private votes */
427
+ ctAbstain?: Uint8Array;
387
428
  }
388
429
  interface CreateProposalParams {
389
430
  title: string;
@@ -433,8 +474,13 @@ declare enum ActionType {
433
474
  Delegate = 6,
434
475
  Vote = 7
435
476
  }
477
+ /**
478
+ * ViLinkConfig - Updated with H-02 pending authority field
479
+ */
436
480
  interface ViLinkConfig extends PendingAuthorityFields {
437
481
  authority: PublicKey;
482
+ /** H-02: Pending authority for two-step transfer */
483
+ pendingAuthority?: PublicKey;
438
484
  vcoinMint: PublicKey;
439
485
  treasury: PublicKey;
440
486
  enabledActions: number;
@@ -442,6 +488,7 @@ interface ViLinkConfig extends PendingAuthorityFields {
442
488
  totalActionsExecuted: BN;
443
489
  totalTipVolume: BN;
444
490
  paused: boolean;
491
+ /** M-02: Platform fee in basis points, bounded 10-1000 (0.1%-10%) */
445
492
  platformFeeBps: number;
446
493
  }
447
494
  interface ViLinkAction {
@@ -472,7 +519,7 @@ interface CreateActionParams {
472
519
  */
473
520
  nonce?: BN;
474
521
  }
475
- /** M-04: User action statistics with nonce tracking */
522
+ /** M-04 + Finding #5: User action statistics with nonce tracking */
476
523
  interface UserActionStatsExtended {
477
524
  user: PublicKey;
478
525
  actionsCreated: BN;
@@ -487,22 +534,47 @@ interface UserActionStatsExtended {
487
534
  lastActionAt: BN;
488
535
  /** M-04: Next nonce to use when creating an action */
489
536
  actionNonce: BN;
537
+ /** Finding #5: Next nonce to use when creating a batch (prevents timestamp collisions) */
538
+ batchNonce: BN;
490
539
  }
491
540
  declare enum FeeMethod {
492
541
  PlatformSubsidized = 0,
493
542
  VCoinDeduction = 1,
494
543
  SSCREDeduction = 2
495
544
  }
545
+ /**
546
+ * GaslessConfig - Finding #8 Fix
547
+ *
548
+ * Updated to include all fields from on-chain GaslessConfig struct.
549
+ * Previous version was missing fields added after H-02 security fix.
550
+ */
496
551
  interface GaslessConfig extends PendingAuthorityFields {
497
552
  authority: PublicKey;
553
+ /** H-02: Pending authority for two-step transfer */
554
+ pendingAuthority?: PublicKey;
498
555
  feePayer: PublicKey;
499
556
  vcoinMint: PublicKey;
557
+ /** Fee vault for VCoin fee collection */
558
+ feeVault?: PublicKey;
559
+ /** SSCRE program for reward deduction integration */
560
+ sscreProgram?: PublicKey;
500
561
  dailySubsidyBudget: BN;
501
562
  solFeePerTx: BN;
502
563
  vcoinFeeMultiplier: BN;
564
+ /** SSCRE deduction rate in basis points */
565
+ sscreDeductionBps?: number;
566
+ /** Maximum subsidized transactions per user per day */
567
+ maxSubsidizedPerUser?: number;
503
568
  totalSubsidizedTx: BN;
569
+ /** Total SOL spent on subsidies */
570
+ totalSolSpent?: BN;
504
571
  totalVcoinCollected: BN;
505
572
  paused: boolean;
573
+ /** Current day number for daily budget reset */
574
+ currentDay?: number;
575
+ /** Today's spent budget */
576
+ daySpent?: BN;
577
+ /** L-03: Maximum fee slippage in basis points (default 500 = 5%) */
506
578
  maxSlippageBps?: number;
507
579
  }
508
580
  interface SessionKey {
@@ -533,6 +605,8 @@ interface UserGaslessStats {
533
605
  totalVcoinFees: BN;
534
606
  sessionsCreated: number;
535
607
  activeSession: PublicKey;
608
+ /** H-AUDIT-12: Number of active (non-revoked, non-expired) sessions */
609
+ activeSessions: number;
536
610
  }
537
611
  declare enum VerificationLevel {
538
612
  None = 0,// Wallet connected only
@@ -609,26 +683,52 @@ interface GovernanceConfig extends PendingAuthorityFields {
609
683
  vevcoinMint: PublicKey;
610
684
  paused: boolean;
611
685
  proposalCount: BN;
612
- zkVotingEnabled: boolean;
686
+ /** H-02: Timestamp when pending authority transfer was initiated (for 24h timelock) */
687
+ pendingAuthorityActivatedAt: BN;
613
688
  }
614
- /** ZK voting decryption share storage (C-02) */
689
+ /** ZK voting decryption share with per-category partials and DLEQ proof */
615
690
  interface DecryptionShare {
616
691
  proposal: PublicKey;
617
692
  committeeIndex: number;
618
693
  committeeMember: PublicKey;
619
- share: Uint8Array;
694
+ /** Partial decryption: sk_j * R_for_sum (Ristretto255 point) */
695
+ partialFor: Uint8Array;
696
+ /** Partial decryption: sk_j * R_against_sum (Ristretto255 point) */
697
+ partialAgainst: Uint8Array;
698
+ /** Partial decryption: sk_j * R_abstain_sum (Ristretto255 point) */
699
+ partialAbstain: Uint8Array;
700
+ /** Batched DLEQ proof challenge (Scalar) */
701
+ dleqChallenge: Uint8Array;
702
+ /** Batched DLEQ proof response (Scalar) */
703
+ dleqResponse: Uint8Array;
620
704
  submittedAt: BN;
705
+ verified: boolean;
621
706
  }
622
- /** Private voting config with committee tracking (C-02) */
707
+ /** Private voting config with ZK cryptographic verification */
623
708
  interface PrivateVotingConfig {
624
709
  proposal: PublicKey;
625
- encryptionPubkey: PublicKey;
710
+ /** Joint ElGamal public key (Ristretto255 point, 32 bytes) */
711
+ encryptionPubkey: Uint8Array;
626
712
  decryptionThreshold: number;
627
713
  decryptionCommittee: PublicKey[];
714
+ /** Committee ElGamal public keys (Ristretto255 points) */
715
+ committeeElgamalPubkeys: Uint8Array[];
628
716
  sharesSubmitted: boolean[];
629
717
  revealCompleted: boolean;
630
718
  aggregatedFor: BN;
631
719
  aggregatedAgainst: BN;
720
+ aggregatedAbstain: BN;
721
+ /** Verification hash for audit trail */
722
+ verificationHash: Uint8Array;
723
+ /** Homomorphically accumulated ciphertext components */
724
+ accumulatedCtForR: Uint8Array;
725
+ accumulatedCtForC: Uint8Array;
726
+ accumulatedCtAgainstR: Uint8Array;
727
+ accumulatedCtAgainstC: Uint8Array;
728
+ accumulatedCtAbstainR: Uint8Array;
729
+ accumulatedCtAbstainC: Uint8Array;
730
+ /** Number of private votes cast */
731
+ totalPrivateVotes: number;
632
732
  }
633
733
  /** Delegation with expiry (M-07) */
634
734
  interface Delegation {
@@ -651,6 +751,8 @@ interface PendingScoreUpdate {
651
751
  submissionCount: number;
652
752
  createdAt: BN;
653
753
  expiresAt: BN;
754
+ /** C-07: Immutable consensus count stored at creation time */
755
+ requiredConsensus: number;
654
756
  }
655
757
  interface HookConfig extends PendingAuthorityFields {
656
758
  authority: PublicKey;
@@ -658,10 +760,82 @@ interface HookConfig extends PendingAuthorityFields {
658
760
  blockWashTrading: boolean;
659
761
  paused: boolean;
660
762
  }
763
+ /** Pair tracking for wash trade detection */
764
+ interface PairTracking {
765
+ sender: PublicKey;
766
+ receiver: PublicKey;
767
+ transferCount: number;
768
+ lastTransferTime: BN;
769
+ washFlags: number;
770
+ /** M-AUDIT-10: Timestamp of last wash flag for decay */
771
+ lastFlagTime: BN;
772
+ }
773
+ interface VeVCoinConfig extends PendingAuthorityFields {
774
+ authority: PublicKey;
775
+ vcoinMint: PublicKey;
776
+ vevcoinMint: PublicKey;
777
+ stakingProtocol: PublicKey;
778
+ totalHolders: BN;
779
+ totalMinted: BN;
780
+ paused: boolean;
781
+ /** C-01: Timestamp when pending authority transfer was initiated (for 24h timelock) */
782
+ pendingAuthorityActivatedAt: BN;
783
+ }
784
+ /** Parameters for casting a private vote */
785
+ interface CastPrivateVoteParams {
786
+ proposalId: BN;
787
+ /** ElGamal ciphertext for "for" (64 bytes) */
788
+ ctFor: Uint8Array;
789
+ /** ElGamal ciphertext for "against" (64 bytes) */
790
+ ctAgainst: Uint8Array;
791
+ /** ElGamal ciphertext for "abstain" (64 bytes) */
792
+ ctAbstain: Uint8Array;
793
+ /** Vote validity proof (352 bytes) */
794
+ proofData: Uint8Array;
795
+ }
796
+ /** Parameters for enabling private voting on a proposal */
797
+ interface EnablePrivateVotingParams {
798
+ proposalId: BN;
799
+ /** Joint ElGamal public key (Ristretto255 point, 32 bytes) */
800
+ encryptionPubkey: Uint8Array;
801
+ /** Committee member Solana pubkeys */
802
+ decryptionCommittee: PublicKey[];
803
+ committeeSize: number;
804
+ decryptionThreshold: number;
805
+ /** Committee member ElGamal public keys (Ristretto255 points, 32 bytes each) */
806
+ committeeElgamalPubkeys: Uint8Array[];
807
+ }
808
+ /** Parameters for submitting a decryption share */
809
+ interface SubmitDecryptionShareParams {
810
+ proposalId: BN;
811
+ committeeIndex: number;
812
+ /** Partial decryption for "for" (Ristretto255 point, 32 bytes) */
813
+ partialFor: Uint8Array;
814
+ /** Partial decryption for "against" (Ristretto255 point, 32 bytes) */
815
+ partialAgainst: Uint8Array;
816
+ /** Partial decryption for "abstain" (Ristretto255 point, 32 bytes) */
817
+ partialAbstain: Uint8Array;
818
+ /** DLEQ proof challenge (Scalar, 32 bytes) */
819
+ dleqChallenge: Uint8Array;
820
+ /** DLEQ proof response (Scalar, 32 bytes) */
821
+ dleqResponse: Uint8Array;
822
+ }
823
+ /** Parameters for aggregating revealed votes (permissionless) */
824
+ interface AggregateRevealedVotesParams {
825
+ proposalId: BN;
826
+ tallyFor: BN;
827
+ tallyAgainst: BN;
828
+ tallyAbstain: BN;
829
+ /** Lagrange interpolation coefficients (Scalars, 32 bytes each) */
830
+ lagrangeCoefficients: Uint8Array[];
831
+ }
661
832
 
662
833
  /**
663
834
  * Governance Client for ViWoApp governance operations
664
835
  *
836
+ * Supports both public voting and ZK private voting with Twisted ElGamal
837
+ * encryption on Ristretto255.
838
+ *
665
839
  * @example
666
840
  * ```typescript
667
841
  * const govClient = client.governance;
@@ -674,8 +848,13 @@ interface HookConfig extends PendingAuthorityFields {
674
848
  * durationDays: 7,
675
849
  * });
676
850
  *
677
- * // Vote on a proposal
678
- * await govClient.vote(proposalId, true); // Vote in favor
851
+ * // Public vote on a proposal
852
+ * await govClient.vote(proposalId, true);
853
+ *
854
+ * // Private vote (using zk-voting-sdk for encryption)
855
+ * await govClient.buildCastPrivateVoteTransaction({
856
+ * proposalId, ctFor, ctAgainst, ctAbstain, proofData,
857
+ * });
679
858
  * ```
680
859
  */
681
860
  declare class GovernanceClient {
@@ -684,7 +863,7 @@ declare class GovernanceClient {
684
863
  /**
685
864
  * Get governance configuration
686
865
  */
687
- getConfig(): Promise<any | null>;
866
+ getConfig(): Promise<GovernanceConfig | null>;
688
867
  /**
689
868
  * Get proposal by ID
690
869
  */
@@ -703,6 +882,9 @@ declare class GovernanceClient {
703
882
  hasVoted(proposalId: BN, user?: PublicKey): Promise<boolean>;
704
883
  /**
705
884
  * Calculate user's voting power
885
+ *
886
+ * @note M-01 fix: 5A boost formula is now `1000 + ((five_a_score * 100) / 1000)`
887
+ * to fix precision loss for small scores.
706
888
  */
707
889
  getVotingPower(user?: PublicKey): Promise<BN>;
708
890
  /**
@@ -718,6 +900,9 @@ declare class GovernanceClient {
718
900
  }>;
719
901
  /**
720
902
  * Get proposal progress
903
+ *
904
+ * @note C-03: Quorum is now calculated as votesFor + votesAgainst only.
905
+ * Abstains do NOT count toward quorum.
721
906
  */
722
907
  getProposalProgress(proposalId: BN): Promise<{
723
908
  votesFor: string;
@@ -733,7 +918,7 @@ declare class GovernanceClient {
733
918
  */
734
919
  buildCreateProposalTransaction(params: CreateProposalParams): Promise<Transaction>;
735
920
  /**
736
- * Build vote transaction
921
+ * Build vote transaction (public)
737
922
  *
738
923
  * @note v2.8.0 (C-NEW-01): Voting power parameters (vevcoin_balance, five_a_score, tier)
739
924
  * are now read from on-chain state, not passed as parameters. This prevents vote manipulation.
@@ -747,6 +932,66 @@ declare class GovernanceClient {
747
932
  * Build execute proposal transaction
748
933
  */
749
934
  buildExecuteTransaction(proposalId: BN): Promise<Transaction>;
935
+ /**
936
+ * Build cast private vote transaction
937
+ *
938
+ * Uses Twisted ElGamal encryption on Ristretto255 with compressed sigma proofs.
939
+ * The voter encrypts their choice into 3 ciphertexts (for/against/abstain) and
940
+ * generates a validity proof that exactly one ciphertext encrypts their weight.
941
+ *
942
+ * Use the `zk-voting-sdk` crate to generate ciphertexts and proofs off-chain:
943
+ * ```rust
944
+ * let (ct_for, ct_against, ct_abstain, proof) = encrypt_and_prove(&pubkey, choice, weight);
945
+ * ```
946
+ *
947
+ * @param params - Private vote parameters with ciphertexts and proof
948
+ */
949
+ buildCastPrivateVoteTransaction(params: CastPrivateVoteParams): Promise<Transaction>;
950
+ /**
951
+ * Build enable private voting transaction
952
+ *
953
+ * Called by the governance authority to enable ZK private voting on a proposal.
954
+ * Requires specifying the decryption committee and their ElGamal public keys.
955
+ *
956
+ * @param params - Private voting configuration
957
+ */
958
+ buildEnablePrivateVotingTransaction(params: EnablePrivateVotingParams): Promise<Transaction>;
959
+ /**
960
+ * Build submit decryption share transaction
961
+ *
962
+ * Called by a committee member during the reveal phase.
963
+ * Each member computes partial decryptions and a DLEQ proof off-chain:
964
+ * ```rust
965
+ * let partial = generate_partial_decryption(&secret_share, &pk, &r_for, &r_against, &r_abstain);
966
+ * ```
967
+ *
968
+ * @param params - Decryption share with DLEQ proof
969
+ */
970
+ buildSubmitDecryptionShareTransaction(params: SubmitDecryptionShareParams): Promise<Transaction>;
971
+ /**
972
+ * Build aggregate revealed votes transaction (permissionless)
973
+ *
974
+ * Anyone can submit the aggregated tally since the on-chain program
975
+ * cryptographically verifies: tally * H == C_sum - D for each category.
976
+ * This prevents fabrication of results.
977
+ *
978
+ * Use the `zk-voting-sdk` to compute the tally off-chain:
979
+ * ```rust
980
+ * let lagrange = compute_lagrange_coefficients(&selected_indices);
981
+ * let d = combine_partials(&lagrange, &partials);
982
+ * let tally = recover_tally(&d, &accumulated_c, max_votes).unwrap();
983
+ * ```
984
+ *
985
+ * @param params - Tally values and Lagrange coefficients
986
+ */
987
+ buildAggregateRevealedVotesTransaction(params: AggregateRevealedVotesParams): Promise<Transaction>;
988
+ /**
989
+ * Check if authority transfer timelock has elapsed (H-02)
990
+ */
991
+ canAcceptAuthority(): Promise<{
992
+ canAccept: boolean;
993
+ reason?: string;
994
+ }>;
750
995
  }
751
996
 
752
997
  /**
@@ -808,6 +1053,9 @@ declare class RewardsClient {
808
1053
  }>;
809
1054
  /**
810
1055
  * Calculate gasless fee for claim
1056
+ *
1057
+ * C-05: Uses ceiling division to prevent fee rounding to zero on small amounts.
1058
+ * Formula: fee = ceil(amount * feeBps / 10000)
811
1059
  */
812
1060
  calculateGaslessFee(amount: BN): BN;
813
1061
  /**
@@ -826,6 +1074,9 @@ declare class RewardsClient {
826
1074
  private hashBytes;
827
1075
  /**
828
1076
  * Build claim rewards transaction
1077
+ *
1078
+ * H-NEW-02: Merkle proof size is limited to 32 levels (supports 4B+ users).
1079
+ * Proofs exceeding this limit will be rejected on-chain with MerkleProofTooLarge.
829
1080
  */
830
1081
  buildClaimTransaction(params: ClaimRewardsParams): Promise<Transaction>;
831
1082
  }
@@ -856,6 +1107,9 @@ declare class ViLinkClient {
856
1107
  constructor(client: ViWoClient);
857
1108
  /**
858
1109
  * Get ViLink configuration
1110
+ *
1111
+ * Finding #8 (related): Corrected byte offsets to match on-chain ViLinkConfig struct.
1112
+ * Added pending_authority field that was missing after H-02 security fix.
859
1113
  */
860
1114
  getConfig(): Promise<ViLinkConfig | null>;
861
1115
  /**
@@ -891,6 +1145,9 @@ declare class ViLinkClient {
891
1145
  }>;
892
1146
  /**
893
1147
  * Calculate platform fee for tip
1148
+ *
1149
+ * C-06: Uses ceiling division to prevent fee rounding to zero on small amounts.
1150
+ * Formula: fee = ceil(amount * feeBps / 10000)
894
1151
  */
895
1152
  calculateFee(amount: BN): {
896
1153
  fee: BN;
@@ -944,6 +1201,13 @@ declare class ViLinkClient {
944
1201
  * Build execute tip action transaction
945
1202
  * @param creator - The action creator's public key
946
1203
  * @param nonce - M-04: The action nonce (NOT timestamp)
1204
+ *
1205
+ * H-05: The on-chain handler validates that the executor's token account has
1206
+ * no active delegation (delegate is None or delegated_amount is 0).
1207
+ * This prevents delegated tokens from being spent without explicit approval.
1208
+ *
1209
+ * C-06: Platform fee uses ceiling division to prevent zero-fee exploitation on
1210
+ * small amounts.
947
1211
  */
948
1212
  buildExecuteTipAction(creator: PublicKey, nonce: BN): Promise<Transaction>;
949
1213
  /**
@@ -977,6 +1241,10 @@ declare class GaslessClient {
977
1241
  constructor(client: ViWoClient);
978
1242
  /**
979
1243
  * Get gasless configuration
1244
+ *
1245
+ * Finding #8 Fix: Corrected byte offsets to match on-chain GaslessConfig struct.
1246
+ * Added missing fields: pendingAuthority, feeVault, sscreProgram, sscreDeductionBps,
1247
+ * maxSubsidizedPerUser, totalSolSpent, currentDay, daySpent, maxSlippageBps.
980
1248
  */
981
1249
  getConfig(): Promise<GaslessConfig | null>;
982
1250
  /**
@@ -985,6 +1253,9 @@ declare class GaslessClient {
985
1253
  getSessionKey(user: PublicKey, sessionPubkey: PublicKey): Promise<SessionKey | null>;
986
1254
  /**
987
1255
  * Get user gasless statistics
1256
+ *
1257
+ * H-AUDIT-12: Now includes active_sessions field for per-user session limit tracking.
1258
+ * The protocol enforces a maximum of 5 concurrent active sessions per user.
988
1259
  */
989
1260
  getUserStats(user?: PublicKey): Promise<UserGaslessStats | null>;
990
1261
  /**
@@ -1032,6 +1303,9 @@ declare class GaslessClient {
1032
1303
  createScope(actions: string[]): number;
1033
1304
  /**
1034
1305
  * Build create session key transaction
1306
+ *
1307
+ * H-AUDIT-12: The protocol enforces a maximum of 5 concurrent active sessions per user.
1308
+ * Creating a session when the limit is reached will fail with MaxSessionsReached error.
1035
1309
  */
1036
1310
  buildCreateSessionTransaction(params: CreateSessionParams): Promise<Transaction>;
1037
1311
  /**
@@ -1082,6 +1356,14 @@ declare class IdentityClient {
1082
1356
  * Get verification level benefits
1083
1357
  */
1084
1358
  getVerificationBenefits(level: VerificationLevel): string[];
1359
+ /**
1360
+ * Build subscribe transaction
1361
+ *
1362
+ * C-AUDIT-22: Non-free subscription tiers require actual USDC payment via SPL
1363
+ * transfer_checked. The transaction must include the user's USDC token account,
1364
+ * the USDC mint, and the treasury token account.
1365
+ */
1366
+ buildSubscribeTransaction(tier: number): Promise<Transaction>;
1085
1367
  /**
1086
1368
  * Build create identity transaction
1087
1369
  */
@@ -1142,6 +1424,12 @@ declare class FiveAClient {
1142
1424
  getMaxVouches(composite: number): number;
1143
1425
  /**
1144
1426
  * Check if user can vouch for another
1427
+ *
1428
+ * C-08: Mutual vouching is prevented — if the target has already vouched for you,
1429
+ * you cannot vouch for them. This is enforced on-chain via reverse_vouch_record check.
1430
+ *
1431
+ * M-18: Vouches expire after 1 year (MAX_VOUCH_AGE = 365 days). Expired vouches
1432
+ * cannot be evaluated and must be re-created.
1145
1433
  */
1146
1434
  canVouchFor(target: PublicKey): Promise<{
1147
1435
  canVouch: boolean;
@@ -1153,6 +1441,12 @@ declare class FiveAClient {
1153
1441
  getImprovementSuggestions(score: FiveAScore): string[];
1154
1442
  /**
1155
1443
  * Build vouch transaction
1444
+ *
1445
+ * C-08: On-chain handler requires a reverse_vouch_record account to verify
1446
+ * mutual vouching is not occurring. The transaction must include this PDA.
1447
+ *
1448
+ * M-18: Vouches have a maximum age of 1 year. After that, evaluate_vouch
1449
+ * will reject with VouchExpired error.
1156
1450
  */
1157
1451
  buildVouchTransaction(target: PublicKey): Promise<Transaction>;
1158
1452
  }
@@ -1217,6 +1511,9 @@ declare class ContentClient {
1217
1511
  }>;
1218
1512
  /**
1219
1513
  * Get content stats
1514
+ *
1515
+ * C-AUDIT-10: Engagement scores can only increase — the on-chain update_engagement
1516
+ * instruction enforces monotonic increase to prevent manipulation.
1220
1517
  */
1221
1518
  getContentStats(contentId: Uint8Array): Promise<{
1222
1519
  tips: string;
@@ -1227,6 +1524,9 @@ declare class ContentClient {
1227
1524
  }>;
1228
1525
  /**
1229
1526
  * Build create content transaction
1527
+ *
1528
+ * C-AUDIT-11: Energy tiers are validated on-chain (valid range: 1-4).
1529
+ * Tier determines max energy and regen rate.
1230
1530
  */
1231
1531
  buildCreateContentTransaction(contentHash: Uint8Array): Promise<Transaction>;
1232
1532
  /**
@@ -1304,6 +1604,9 @@ declare class ViWoClient {
1304
1604
  sendTransaction(tx: Transaction): Promise<string>;
1305
1605
  /**
1306
1606
  * Get VCoin balance
1607
+ *
1608
+ * Finding #2 Fix: Now filters by VCoin mint address instead of summing all Token-2022 accounts.
1609
+ * Make sure to set programIds.vcoinMint in your ViWoClient config.
1307
1610
  */
1308
1611
  getVCoinBalance(user?: PublicKey): Promise<BN>;
1309
1612
  /**
@@ -1360,6 +1663,10 @@ declare class StakingClient {
1360
1663
  calculateVeVCoin(amount: BN, lockDuration: number): BN;
1361
1664
  /**
1362
1665
  * Get tier name
1666
+ *
1667
+ * M-05: The on-chain update_tier instruction will reject no-op tier updates
1668
+ * with TierUnchanged error. Only call updateTier when the user's stake amount
1669
+ * actually qualifies for a different tier.
1363
1670
  */
1364
1671
  getTierName(tier: StakingTier): string;
1365
1672
  /**
@@ -1402,4 +1709,4 @@ declare class StakingClient {
1402
1709
  buildExtendLockTransaction(newDuration: number): Promise<Transaction>;
1403
1710
  }
1404
1711
 
1405
- 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 };
1712
+ 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 };