@wireio/stake 0.5.1 → 0.5.2

package/lib/stake.d.ts

@@ -8099,6 +8099,942 @@ declare class TokenClient {
     getSolPriceUsd(): Promise<bigint>;
 }
 
+/**
+ * Program IDL in camelCase format in order to be used in JS/TS.
+ *
+ * Note that this is only a type helper and is not the actual IDL. The original
+ * IDL can be found at `target/idl/liqsol_token.json`.
+ */
+type LiqsolToken = {
+    "address": "5MRFSLCkXPEzfR6gkcZCVttq9g83mMUHyTZ85Z3TSpvU";
+    "metadata": {
+        "name": "liqsolToken";
+        "version": "0.1.0";
+        "spec": "0.1.0";
+        "description": "Liquidity Staking Token Program";
+    };
+    "instructions": [
+        {
+            "name": "createMintAccount";
+            "discriminator": [
+                76,
+                184,
+                50,
+                62,
+                162,
+                141,
+                47,
+                103
+            ];
+            "accounts": [
+                {
+                    "name": "payer";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "mintAuthority";
+                },
+                {
+                    "name": "receiver";
+                },
+                {
+                    "name": "mint";
+                    "docs": [
+                        "The mint PDA - deterministic address for liqSOL token"
+                    ];
+                    "writable": true;
+                },
+                {
+                    "name": "mintTokenAccount";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                },
+                {
+                    "name": "associatedTokenProgram";
+                },
+                {
+                    "name": "tokenProgram";
+                }
+            ];
+            "args": [
+                {
+                    "name": "args";
+                    "type": {
+                        "defined": {
+                            "name": "createMintAccountArgs";
+                        };
+                    };
+                }
+            ];
+        },
+        {
+            "name": "mintForAuthorizedProgram";
+            "discriminator": [
+                116,
+                208,
+                64,
+                189,
+                2,
+                60,
+                50,
+                41
+            ];
+            "accounts": [
+                {
+                    "name": "mint";
+                    "writable": true;
+                },
+                {
+                    "name": "recipientTokenAccount";
+                    "writable": true;
+                },
+                {
+                    "name": "programAuthority";
+                    "docs": [
+                        "The calling program's authority PDA that proves authorization to mint"
+                    ];
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "mintAuthority";
+                },
+                {
+                    "name": "instructions";
+                },
+                {
+                    "name": "tokenProgram";
+                }
+            ];
+            "args": [
+                {
+                    "name": "args";
+                    "type": {
+                        "defined": {
+                            "name": "mintTokenArgs";
+                        };
+                    };
+                }
+            ];
+        }
+    ];
+    "errors": [
+        {
+            "code": 6000;
+            "name": "invalidMintAuthority";
+            "msg": "Invalid mint authority";
+        },
+        {
+            "code": 6001;
+            "name": "unauthorizedProgram";
+            "msg": "Unauthorized program attempting to mint";
+        },
+        {
+            "code": 6002;
+            "name": "cannotDetermineCallingProgram";
+            "msg": "Cannot determine calling program";
+        },
+        {
+            "code": 6003;
+            "name": "directCallNotAllowed";
+            "msg": "Direct calls not allowed, must be called via CPI";
+        },
+        {
+            "code": 6004;
+            "name": "invalidProgramId";
+            "msg": "Invalid program ID";
+        },
+        {
+            "code": 6005;
+            "name": "unauthorizedAuthority";
+            "msg": "Unauthorized authority PDA";
+        }
+    ];
+    "types": [
+        {
+            "name": "createMintAccountArgs";
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "name";
+                        "type": "string";
+                    },
+                    {
+                        "name": "symbol";
+                        "type": "string";
+                    },
+                    {
+                        "name": "uri";
+                        "type": "string";
+                    }
+                ];
+            };
+        },
+        {
+            "name": "mintTokenArgs";
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "amount";
+                        "type": "u64";
+                    }
+                ];
+            };
+        }
+    ];
+};
+
+/**
+ * Program IDL in camelCase format in order to be used in JS/TS.
+ *
+ * Note that this is only a type helper and is not the actual IDL. The original
+ * IDL can be found at `target/idl/validator_leaderboard.json`.
+ */
+type ValidatorLeaderboard = {
+    "address": "5v7mWL1735qp2Th9B5WNf7spGynR5ZaxwyCYoQw13DP2";
+    "metadata": {
+        "name": "validatorLeaderboard";
+        "version": "0.1.0";
+        "spec": "0.1.0";
+        "description": "Created with Anchor";
+    };
+    "instructions": [
+        {
+            "name": "initializeLeaderboard";
+            "discriminator": [
+                47,
+                23,
+                34,
+                39,
+                46,
+                108,
+                91,
+                176
+            ];
+            "accounts": [
+                {
+                    "name": "authority";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "reallocLeaderboard";
+            "discriminator": [
+                2,
+                70,
+                106,
+                94,
+                81,
+                225,
+                113,
+                152
+            ];
+            "accounts": [
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                },
+                {
+                    "name": "payer";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "systemProgram";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "testClearLeaderboard";
+            "discriminator": [
+                118,
+                207,
+                26,
+                205,
+                180,
+                7,
+                75,
+                244
+            ];
+            "accounts": [
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                },
+                {
+                    "name": "authority";
+                    "signer": true;
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "testForceRegisterValidator";
+            "discriminator": [
+                136,
+                156,
+                132,
+                32,
+                96,
+                240,
+                7,
+                115
+            ];
+            "accounts": [
+                {
+                    "name": "registrant";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "voteAccount";
+                },
+                {
+                    "name": "validatorRecord";
+                    "writable": true;
+                },
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                },
+                {
+                    "name": "clock";
+                }
+            ];
+            "args": [
+                {
+                    "name": "vpp";
+                    "type": "u8";
+                }
+            ];
+        },
+        {
+            "name": "testForceUpdateVpp";
+            "discriminator": [
+                67,
+                51,
+                28,
+                174,
+                200,
+                214,
+                203,
+                162
+            ];
+            "accounts": [
+                {
+                    "name": "registrant";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "voteAccount";
+                },
+                {
+                    "name": "validatorRecord";
+                    "writable": true;
+                },
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                }
+            ];
+            "args": [
+                {
+                    "name": "vpp";
+                    "type": "u8";
+                }
+            ];
+        },
+        {
+            "name": "testSeedRandomValidators";
+            "discriminator": [
+                48,
+                155,
+                181,
+                112,
+                163,
+                242,
+                43,
+                146
+            ];
+            "accounts": [
+                {
+                    "name": "registrant";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                }
+            ];
+            "args": [
+                {
+                    "name": "count";
+                    "type": "u16";
+                },
+                {
+                    "name": "seed";
+                    "type": "u64";
+                },
+                {
+                    "name": "minVpp";
+                    "type": "u8";
+                },
+                {
+                    "name": "maxVpp";
+                    "type": "u8";
+                }
+            ];
+        },
+        {
+            "name": "updateCommission";
+            "discriminator": [
+                2,
+                202,
+                72,
+                156,
+                19,
+                253,
+                91,
+                174
+            ];
+            "accounts": [
+                {
+                    "name": "registrant";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "voteAccount";
+                },
+                {
+                    "name": "validatorRecord";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "updateMevCommission";
+            "discriminator": [
+                107,
+                65,
+                238,
+                108,
+                183,
+                47,
+                236,
+                203
+            ];
+            "accounts": [
+                {
+                    "name": "signer";
+                    "signer": true;
+                },
+                {
+                    "name": "validatorRecord";
+                    "writable": true;
+                },
+                {
+                    "name": "tipDistributionAccount";
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "updateValidator";
+            "discriminator": [
+                105,
+                192,
+                4,
+                98,
+                236,
+                115,
+                108,
+                192
+            ];
+            "accounts": [
+                {
+                    "name": "registrant";
+                    "writable": true;
+                    "signer": true;
+                },
+                {
+                    "name": "voteAccount";
+                },
+                {
+                    "name": "validatorRecord";
+                    "writable": true;
+                },
+                {
+                    "name": "leaderboardState";
+                    "writable": true;
+                },
+                {
+                    "name": "systemProgram";
+                }
+            ];
+            "args": [
+                {
+                    "name": "vpp";
+                    "type": "u8";
+                },
+                {
+                    "name": "proposedRank";
+                    "type": "u16";
+                }
+            ];
+        }
+    ];
+    "accounts": [
+        {
+            "name": "leaderboardState";
+            "discriminator": [
+                211,
+                181,
+                29,
+                120,
+                189,
+                4,
+                106,
+                111
+            ];
+        },
+        {
+            "name": "validatorRecord";
+            "discriminator": [
+                105,
+                248,
+                112,
+                34,
+                71,
+                224,
+                21,
+                71
+            ];
+        }
+    ];
+    "errors": [
+        {
+            "code": 6000;
+            "name": "missingPreviousValidator";
+            "msg": "Missing previous validator account";
+        },
+        {
+            "code": 6001;
+            "name": "missingNextValidator";
+            "msg": "Missing next validator account";
+        },
+        {
+            "code": 6002;
+            "name": "invalidVppScore";
+            "msg": "Invalid VPP score provided.";
+        },
+        {
+            "code": 6003;
+            "name": "invalidInsertPosition";
+            "msg": "Invalid insertion position.";
+        },
+        {
+            "code": 6004;
+            "name": "invalidCurrentPrev";
+            "msg": "Invalid current previous validator.";
+        },
+        {
+            "code": 6005;
+            "name": "invalidCurrentNext";
+            "msg": "Invalid current next validator.";
+        },
+        {
+            "code": 6006;
+            "name": "invalidHeadValidator";
+            "msg": "Head validator cannot have a previous validator";
+        },
+        {
+            "code": 6007;
+            "name": "invalidTailValidator";
+            "msg": "Tail validator cannot have a next validator";
+        },
+        {
+            "code": 6008;
+            "name": "validatorNotInLeaderboard";
+            "msg": "Cannot remove validator that is not in the leaderboard";
+        },
+        {
+            "code": 6009;
+            "name": "validatorAlreadyExists";
+            "msg": "Validator already exists in the leaderboard";
+        },
+        {
+            "code": 6010;
+            "name": "overflow";
+            "msg": "Arithmetic overflow";
+        },
+        {
+            "code": 6011;
+            "name": "invalidVoteAccount";
+            "msg": "Invalid vote account - must be owned by vote program";
+        },
+        {
+            "code": 6012;
+            "name": "vppVerificationFailed";
+            "msg": "VPP verification failed";
+        },
+        {
+            "code": 6013;
+            "name": "vppUnchanged";
+            "msg": "VPP score unchanged - update not needed";
+        },
+        {
+            "code": 6014;
+            "name": "invalidAccountCount";
+            "msg": "Invalid account count for top 10 verification";
+        },
+        {
+            "code": 6015;
+            "name": "invalidVppOrdering";
+            "msg": "Validators not in correct VPP order";
+        },
+        {
+            "code": 6016;
+            "name": "brokenLinkage";
+            "msg": "Broken linked list continuity";
+        },
+        {
+            "code": 6017;
+            "name": "commissionNotUpdated";
+            "msg": "Commission must be updated for current epoch before updating validator";
+        },
+        {
+            "code": 6018;
+            "name": "mevCommissionNotUpdated";
+            "msg": "MEV commission must be updated for current epoch before updating validator";
+        },
+        {
+            "code": 6019;
+            "name": "invalidCurrentNeighbor";
+            "msg": "Current neighbor account doesn't match validator's stored links";
+        },
+        {
+            "code": 6020;
+            "name": "nonAdjacentInsertionPosition";
+            "msg": "Insertion position accounts are not actually adjacent in leaderboard";
+        },
+        {
+            "code": 6021;
+            "name": "staleAccountReference";
+            "msg": "Account reference is outdated due to concurrent update";
+        },
+        {
+            "code": 6022;
+            "name": "invalidStakeAmount";
+            "msg": "Invalid stake amount - exceeds maximum allowed";
+        },
+        {
+            "code": 6023;
+            "name": "invalidTipDistributionAccount";
+            "msg": "Invalid Tip Distribution Account provided";
+        },
+        {
+            "code": 6024;
+            "name": "invalidRankPosition";
+            "msg": "Proposed rank position violates sorted ordering";
+        },
+        {
+            "code": 6025;
+            "name": "leaderboardFull";
+            "msg": "Leaderboard is full - cannot add more validators";
+        },
+        {
+            "code": 6026;
+            "name": "validatorNotInRankings";
+            "msg": "Validator not found in rankings";
+        },
+        {
+            "code": 6027;
+            "name": "arithmeticOverflow";
+            "msg": "Arithmetic overflow";
+        }
+    ];
+    "types": [
+        {
+            "name": "leaderboardState";
+            "docs": [
+                "Central leaderboard state using parallel arrays for efficient ranking and CPI access",
+                "Stores VPP scores and sorted rankings for up to 1024 validators",
+                "Uses zero-copy for efficient access from other programs via CPI"
+            ];
+            "serialization": "bytemuck";
+            "repr": {
+                "kind": "c";
+            };
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "scores";
+                        "docs": [
+                            "VPP scores indexed by registry_index (0-100 range)",
+                            "registry_index is assigned on first validator registration and never changes"
+                        ];
+                        "type": {
+                            "array": [
+                                "u8",
+                                1024
+                            ];
+                        };
+                    },
+                    {
+                        "name": "sortedIndices";
+                        "docs": [
+                            "Validator indices sorted by VPP score descending",
+                            "sorted_indices[0] = registry_index of highest VPP validator",
+                            "sorted_indices[1] = registry_index of 2nd highest VPP validator, etc."
+                        ];
+                        "type": {
+                            "array": [
+                                "u16",
+                                1024
+                            ];
+                        };
+                    },
+                    {
+                        "name": "voteAccounts";
+                        "docs": [
+                            "Vote account pubkeys indexed by registry_index",
+                            "Allows CPI callers to get vote accounts for top N validators"
+                        ];
+                        "type": {
+                            "array": [
+                                {
+                                    "defined": {
+                                        "name": "pubkeyBytes";
+                                    };
+                                },
+                                1024
+                            ];
+                        };
+                    },
+                    {
+                        "name": "numValidators";
+                        "docs": [
+                            "Number of active validators currently in the leaderboard"
+                        ];
+                        "type": "u16";
+                    },
+                    {
+                        "name": "bump";
+                        "docs": [
+                            "PDA bump seed"
+                        ];
+                        "type": "u8";
+                    },
+                    {
+                        "name": "padding";
+                        "docs": [
+                            "Reserved space for future upgrades"
+                        ];
+                        "type": {
+                            "array": [
+                                "u8",
+                                5
+                            ];
+                        };
+                    }
+                ];
+            };
+        },
+        {
+            "name": "pubkeyBytes";
+            "docs": [
+                "Fixed-size representation of a `Pubkey` that satisfies Anchor's zero-copy rules.",
+                "Stores the raw 32-byte array and offers helpers to convert to/from `Pubkey`."
+            ];
+            "serialization": "bytemuck";
+            "repr": {
+                "kind": "transparent";
+            };
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "bytes";
+                        "type": {
+                            "array": [
+                                "u8",
+                                32
+                            ];
+                        };
+                    }
+                ];
+            };
+        },
+        {
+            "name": "validatorRecord";
+            "docs": [
+                "Per-validator record account storing commission data and metadata"
+            ];
+            "type": {
+                "kind": "struct";
+                "fields": [
+                    {
+                        "name": "voteAccount";
+                        "docs": [
+                            "The validator's vote account pubkey"
+                        ];
+                        "type": "pubkey";
+                    },
+                    {
+                        "name": "registryIndex";
+                        "docs": [
+                            "Immutable index into LeaderboardState arrays",
+                            "Assigned on first registration, never changes"
+                        ];
+                        "type": "u16";
+                    },
+                    {
+                        "name": "creditsObserved";
+                        "docs": [
+                            "Current cumulative credits from vote account"
+                        ];
+                        "type": "u64";
+                    },
+                    {
+                        "name": "commissionHistory";
+                        "docs": [
+                            "Circular buffer of past 10 commission values (0-100)",
+                            "Used to penalize validators who increase commission"
+                        ];
+                        "type": {
+                            "array": [
+                                "u8",
+                                10
+                            ];
+                        };
+                    },
+                    {
+                        "name": "commissionIndex";
+                        "docs": [
+                            "Current index in commission_history circular buffer (0-9)"
+                        ];
+                        "type": "u8";
+                    },
+                    {
+                        "name": "lastCommissionUpdate";
+                        "docs": [
+                            "Last epoch when commission was updated"
+                        ];
+                        "type": "u64";
+                    },
+                    {
+                        "name": "epoch";
+                        "docs": [
+                            "Last epoch this validator was updated"
+                        ];
+                        "type": "u64";
+                    },
+                    {
+                        "name": "slot";
+                        "docs": [
+                            "Last slot this validator was updated"
+                        ];
+                        "type": "u64";
+                    },
+                    {
+                        "name": "wireOperator";
+                        "docs": [
+                            "Whether this validator is a Wire operator (5% bonus)"
+                        ];
+                        "type": "bool";
+                    },
+                    {
+                        "name": "mevCommission";
+                        "docs": [
+                            "Current MEV commission in basis points"
+                        ];
+                        "type": "u16";
+                    },
+                    {
+                        "name": "mevCommissionHistory";
+                        "docs": [
+                            "Circular buffer of past 10 MEV commission values"
+                        ];
+                        "type": {
+                            "array": [
+                                "u16",
+                                10
+                            ];
+                        };
+                    },
+                    {
+                        "name": "mevCommissionIndex";
+                        "docs": [
+                            "Current index in mev_commission_history circular buffer (0-9)"
+                        ];
+                        "type": "u8";
+                    },
+                    {
+                        "name": "lastMevCommissionUpdate";
+                        "docs": [
+                            "Last epoch when MEV commission was updated"
+                        ];
+                        "type": "u64";
+                    },
+                    {
+                        "name": "bump";
+                        "docs": [
+                            "PDA bump seed"
+                        ];
+                        "type": "u8";
+                    }
+                ];
+            };
+        }
+    ];
+};
+
+type Entry<IDL> = {
+    idl: IDL & {
+        address: string;
+    };
+    address: string;
+};
+declare const PROGRAMS: {
+    readonly liqsolCore: Entry<LiqsolCore>;
+    readonly liqsolToken: Entry<LiqsolToken>;
+    readonly validatorLeaderboard: Entry<ValidatorLeaderboard>;
+};
+type SolanaProgramName = keyof typeof PROGRAMS;
+declare class SolanaProgramService {
+    private provider;
+    constructor(provider: AnchorProvider);
+    getProgram<K extends SolanaProgramName>(name: K): Program<(typeof PROGRAMS)[K]['idl']>;
+    listProgramNames(): SolanaProgramName[];
+}
+
 declare const SCALE: any;
 /**
  * Solana implementation of IStakingClient.
@@ -8121,6 +9057,7 @@ declare class SolanaStakingClient implements IStakingClient {
     leaderboardClient: LeaderboardClient;
     outpostClient: OutpostClient;
     tokenClient: TokenClient;
+    program: SolanaProgramService;
     get solPubKey(): PublicKey$1;
     get network(): ExternalNetwork;
     constructor(config: StakerConfig);
@@ -8170,7 +9107,28 @@ declare class SolanaStakingClient implements IStakingClient {
      * Used by balance-correction flows and debugging.
      */
     getUserRecord(): Promise<DistributionUserRecord | null>;
+    /**
+     * Returns the system APY (percent) for Solana,
+     * using compound interest per epoch and a
+     * cluster-derived epochs-per-year.
+     */
     getSystemAPY(): Promise<number>;
+    /**
+     * Reads the liqsol_core stakeMetrics account and returns the
+     * Solana per-epoch system rate as a **decimal** (not BPS),
+     * de-scaled using PAY_RATE_SCALE_FACTOR (1e12).
+     */
+    private getEpochRateDecimalFromProgram;
+    private epochsPerYearCache?;
+    private static readonly EPOCHS_PER_YEAR_TTL_MS;
+    /**
+     * Derive "epochs per year" from the live Solana cluster.
+     *
+     * Uses:
+     *  - getRecentPerformanceSamples() to estimate slots/second
+     *  - getEpochInfo() to read slotsInEpoch
+     */
+    private getEpochsPerYearFromCluster;
     /**
      * Estimate the protocol deposit fee in lamports for a given SOL amount,
      * based on recent pay rates and globalConfig.depositFeeMultiplier.