@wireio/stake 0.3.0 → 0.4.0

package/src/networks/solana/clients/token.client.ts

@@ -6,20 +6,31 @@ import {
     ASSOCIATED_TOKEN_PROGRAM_ID,
 } from '@solana/spl-token';
 
-import { buildOutpostAccounts, type OutpostAccounts, buildSolanaTrancheSnapshot } from '../utils';
+import {
+    buildOutpostAccounts,
+    type OutpostAccounts,
+} from '../utils';
+
 import { SolanaProgramService } from '../program';
-import { LiqsolCore } from '../../../assets/solana/types/liqsol_core';
+import type { LiqsolCore } from '../../../assets/solana/types/liqsol_core';
+
 import {
     GlobalState,
     PriceHistory,
     TrancheState,
-    UserWarrantRecord,
     WalletLike,
-    WireReceipt,
+    OutpostAccount,
+    UserPretokenRecord,
 } from '../types';
-import { derivePriceHistoryPda } from '../constants';
-import type { } from '../types';
-import { ChainID, SolChainID } from '@wireio/core';
+
+import {
+    derivePriceHistoryPda,
+    CHAINLINK_FEED,
+    CHAINLINK_PROGRAM,
+    PROGRAM_IDS,
+    deriveExtraAccountMetaListPda,
+} from '../constants';
+
 
 export class TokenClient {
     private readonly program: Program<LiqsolCore>;
@@ -28,6 +39,10 @@ export class TokenClient {
         return this.provider.wallet;
     }
 
+    get connection(): Connection {
+        return this.provider.connection;
+    }
+
     constructor(private readonly provider: AnchorProvider) {
         const svc = new SolanaProgramService(provider);
         this.program = svc.getProgram('liqsolCore');
@@ -51,92 +66,83 @@ export class TokenClient {
         return this.program.account.trancheState.fetch(trancheState);
     }
 
-    async fetchWireReceipt(user: PublicKey): Promise<WireReceipt> {
-        const { wireReceipt } = await this.getAccounts(user);
-        return this.program.account.wireReceipt.fetch(wireReceipt);
+    /**
+     * Fetch the per-user Outpost account (old "wire receipt").
+     * Returns null if the user has never interacted with Outpost.
+     */
+    async fetchOutpostAccount(user: PublicKey): Promise<OutpostAccount | null> {
+        const { outpostAccount } = await this.getAccounts(user);
+        return this.program.account.outpostAccount.fetchNullable(outpostAccount);
     }
 
-    async fetchUserWarrantRecord(user: PublicKey): Promise<UserWarrantRecord> {
-        const { userWarrantRecord } = await this.getAccounts(user);
-        return this.program.account.userWarrantRecord.fetch(userWarrantRecord);
+    /**
+     * Fetch the per-user pretoken purchase record.
+     * Returns null if the user has never purchased pretokens.
+     */
+    async fetchUserPretokenRecord(
+        user: PublicKey,
+    ): Promise<UserPretokenRecord | null> {
+        const { userPretokenRecord } = await this.getAccounts(user);
+        return this.program.account.userPretokenRecord.fetchNullable(
+            userPretokenRecord,
+        );
     }
 
-    // ---------------------------------------------------------------------------
-    // Tranche snapshot / quoting
-    // ---------------------------------------------------------------------------
-
     // ---------------------------------------------------------------------------
     // Instruction builders (no send / confirm)
     // ---------------------------------------------------------------------------
 
-    async buildPurchaseWithSolIx(
+    /**
+     * Build a pretoken `purchase` instruction using liqSOL from the user’s ATA.
+     *
+     * This mirrors capital-staking `executePurchase` wiring:
+     * - amountLamports: liqSOL amount (raw token-2022 units, not SOL)
+     */
+    async buildPurchaseIx(
         amountLamports: bigint,
         user = this.wallet.publicKey,
     ): Promise<TransactionInstruction> {
         const a = await this.getAccounts(user);
 
+        const extraAccountMetaList = deriveExtraAccountMetaListPda(a.liqsolMint);
+        const liqsolCoreProgram = PROGRAM_IDS.LIQSOL_CORE;
+        const transferHookProgram = PROGRAM_IDS.TRANSFER_HOOK;
+
         return this.program.methods
-            .purchaseWithSol(new BN(amountLamports.toString()))
+            .purchase(new BN(amountLamports.toString()))
             .accounts({
                 user: a.user,
                 liqsolMint: a.liqsolMint,
                 globalState: a.globalState,
+                distributionState: a.distributionState,
 
+                // buyer’s liqSOL
+                buyerAta: a.userAta,
+
+                // pool / bucket context
                 poolAuthority: a.poolAuthority,
-                liqsolPoolAta: a.liqsolPoolAta,
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
                 bucketAuthority: a.bucketAuthority,
                 bucketTokenAccount: a.bucketTokenAccount,
-                solBucket: a.solBucket,
-
-                // IDL name is warrantDepositRecord (wireReceipt PDA)
-                warrantDepositRecord: a.wireReceipt,
+                bucketUserRecord: a.bucketUserRecord,
 
-                trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
-
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
-
-                tokenProgram: TOKEN_2022_PROGRAM_ID,
-                systemProgram: SystemProgram.programId,
-            })
-            .instruction();
-    }
+                // distribution userRecords (token-account keyed)
+                senderUserRecord: a.userUserRecord,
+                receiverUserRecord: a.liqsolPoolUserRecord,
 
-    async buildPurchaseWithLiqsolIx(
-        amountLamports: bigint,
-        user = this.wallet.publicKey,
-    ): Promise<TransactionInstruction> {
-        const a = await this.getAccounts(user);
+                // transfer-hook wiring
+                extraAccountMetaList,
+                liqsolCoreProgram,
+                transferHookProgram,
 
-        return this.program.methods
-            .purchaseWithLiqsol(new BN(amountLamports.toString()))
-            .accounts({
-                user: a.user,
-                liqsolMint: a.liqsolMint,
-                globalState: a.globalState,
-
-                buyerAta: a.userAta,
-                poolAuthority: a.poolAuthority,
+                // pool + outpost + tranche
                 liqsolPoolAta: a.liqsolPoolAta,
-
-                warrantDepositRecord: a.wireReceipt,
-
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
-                bucketAuthority: a.bucketAuthority,
-                bucketTokenAccount: a.bucketTokenAccount,
-                solBucket: a.solBucket,
-
+                outpostAccount: a.outpostAccount,
                 trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
+                userPretokenRecord: a.userPretokenRecord,
 
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
+                // Chainlink pricing
+                chainlinkFeed: a.chainLinkFeed ?? CHAINLINK_FEED,
+                chainlinkProgram: a.chainLinkProgram ?? CHAINLINK_PROGRAM,
 
                 tokenProgram: TOKEN_2022_PROGRAM_ID,
                 associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
@@ -145,37 +151,12 @@ export class TokenClient {
             .instruction();
     }
 
-    async buildPurchaseFromYieldIx(
-        user = this.wallet.publicKey,
-    ): Promise<TransactionInstruction> {
-        const a = await this.getAccounts(user);
-
-        return this.program.methods
-            .purchaseWarrantsFromYield()
-            .accounts({
-                user: a.user,
-                globalState: a.globalState,
-                liqsolMint: a.liqsolMint,
-                poolAuthority: a.poolAuthority,
-                liqsolPoolAta: a.liqsolPoolAta,
-                solBucket: a.solBucket,
-
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
-                bucketAuthority: a.bucketAuthority,
-                bucketTokenAccount: a.bucketTokenAccount,
-
-                trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
-
-                tokenProgram: TOKEN_2022_PROGRAM_ID,
-                systemProgram: SystemProgram.programId,
-            })
-            .instruction();
-    }
+    // NOTE:
+    // - There is no longer `purchaseWithSol` in the IDL - SOL → liqSOL happens
+    //   through the deposit / liqSOL minting path, not directly in pretokens.
+    // - `purchaseFromYield` is an operator-facing / protocol flow and you
+    //   indicated you’ll trigger it from Wire infra, so we don’t expose a
+    //   client helper here for now.
 
     // ---------------------------------------------------------------------------
     // Price helpers (SOL/USD via priceHistory account)
@@ -193,7 +174,7 @@ export class TokenClient {
 
     /**
      * Fetch latest SOL/USD price (1e8 scale) from liqsol_core.priceHistory.
-     * Uses the ring-buffer semantics from earlier SDK code.
+     * Uses the ring-buffer semantics from capital-staking.
      */
     async getSolPriceUsd(): Promise<bigint> {
         const priceHistoryPda = derivePriceHistoryPda();
@@ -204,19 +185,23 @@ export class TokenClient {
         const { prices, nextIndex, count, windowSize } = history;
 
         if (!prices || prices.length === 0 || !count) {
-            throw new Error('Price history is empty – no SOL price available');
+            throw new Error('Price history is empty - no SOL price available');
         }
 
         const capacity = prices.length || windowSize;
         if (!capacity) {
-            throw new Error('Price history capacity is zero – check account layout');
+            throw new Error(
+                'Price history capacity is zero - check account layout',
+            );
         }
 
         const lastIndex = nextIndex === 0 ? capacity - 1 : nextIndex - 1;
         const latest = prices[lastIndex];
 
         if (!BN.isBN(latest)) {
-            throw new Error('Latest price entry is not a BN – check IDL/decoder');
+            throw new Error(
+                'Latest price entry is not a BN - check IDL/decoder',
+            );
         }
 
         return BigInt(latest.toString());

package/src/networks/solana/constants.ts

@@ -1,9 +1,10 @@
 // src/networks/solana/constants.ts
 import { PublicKey, StakeProgram } from '@solana/web3.js';
 
-import liqsolCoreIDL from "../../assets/solana/idl/liqsol_core.json";
-import liqSolTokenIDL from "../../assets/solana/idl/liqsol_token.json";
-import validatorLeaderboardIDL from "../../assets/solana/idl/validator_leaderboard.json";
+import liqsolCoreIDL from '../../assets/solana/idl/liqsol_core.json';
+import liqSolTokenIDL from '../../assets/solana/idl/liqsol_token.json';
+import validatorLeaderboardIDL from '../../assets/solana/idl/validator_leaderboard.json';
+import transferHookIDL from '../../assets/solana/idl/transfer_hook.json';
 
 /**
  * ---------------------------------------------------------------------------
@@ -14,27 +15,24 @@ import validatorLeaderboardIDL from "../../assets/solana/idl/validator_leaderboa
  *  - `metadata.address` in your Anchor IDLs under src/assets/solana/idl/*.json
  *  - The program IDs printed by your deploy scripts
  */
-// Extract program IDs from IDL files
 export const PROGRAM_IDS = {
     LIQSOL_CORE: new PublicKey(liqsolCoreIDL.address),
     LIQSOL_TOKEN: new PublicKey(liqSolTokenIDL.address),
     VALIDATOR_LEADERBOARD: new PublicKey(validatorLeaderboardIDL.address),
+    TRANSFER_HOOK: new PublicKey(transferHookIDL.address),
 } as const;
 
-// Export individual program IDs for convenience
 export const {
     LIQSOL_CORE,
     LIQSOL_TOKEN,
     VALIDATOR_LEADERBOARD,
+    TRANSFER_HOOK,
 } = PROGRAM_IDS;
 
 /**
  * ---------------------------------------------------------------------------
  *  PDA SEEDS (must match on-chain programs)
  * ---------------------------------------------------------------------------
- *
- * These strings are baked into the on-chain programs and are already used in
- * your test utils. We centralize them here so all clients share them.
  */
 
 export const PDA_SEEDS = {
@@ -52,156 +50,238 @@ export const PDA_SEEDS = {
 
     // distribution program (embedded in liqsol_core)
     DISTRIBUTION_STATE: 'distribution_state',
+    // NOTE: in the current IDL, userRecord is keyed by the USER (wallet), not ATA
     USER_RECORD: 'user_record',
 
-    // pay-rate history
+    // pay-rate / price history
     PAY_RATE_HISTORY: 'pay_rate_history',
+    PRICE_HISTORY: 'price_history',
 
     // validator leaderboard (state + records)
     LEADERBOARD_STATE: 'leaderboard_state',
     VALIDATOR_RECORD: 'validator',
     GLOBAL_STAKE_INFO: 'global_stake_info',
 
-    // Outpost
-    WARRANT_DEPOSIT_GLOBAL: 'warrant_deposit_global',
+    // Outpost / Wire pretokens
+    OUTPOST_GLOBAL_STATE: 'outpost_global_state',
     LIQSOL_POOL: 'liqsol_pool',
-    WARRANT_DEPOSIT_RECORD: 'warrant_deposit_record',
-    WIRE_SOL_BUCKET: 'wire_sol_bucket',
+    OUTPOST_ACCOUNT: 'outpost_account',
+    USER_PRETOKEN_RECORD: 'user_pretoken_record',
     TRANCHE_STATE: 'tranche_state',
-    USER_WARRANT_RECORD: 'user_warrant_record',
 
-    // BAR
+    // BAR module (bonded actor roles)
     BAR_STATE_SEED: 'bar_state',
     BONDED_ACTOR_SEED: 'bonded_actor',
     BOND_LEVEL_SEED: 'bond_level',
 
-    // Other?
-    PRICE_HISTORY: 'price_history',
+    // SPL transfer-hook extra account metas
+    EXTRA_ACCOUNT_METAS: 'extra-account-metas',
+
+    // Withdraw module / receipts
+    WITHDRAW_GLOBAL: 'global',
+    STAKE_ALLOCATION_STATE: 'stake_allocation_state',
+    STAKE_METRICS: 'stake_metrics',
+    MAINTENANCE_LEDGER: 'maintenance_ledger',
+    WITHDRAW_MINT_AUTHORITY: 'mint_authority',
+    MINT_METADATA: 'mint_metadata',
+    LIQ_RECEIPT_DATA: 'liq_receipt_data',
+    WITHDRAW_MINT: 'mint',
 } as const;
 
 /**
- * Helpers for PDA derivation so clients don’t duplicate logic.
+ * ---------------------------------------------------------------------------
+ *  CORE / DISTRIBUTION / DEPOSIT PDAS
+ * ---------------------------------------------------------------------------
  */
+
 export const deriveLiqsolMintPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.LIQSOL_MINT)],
-        PROGRAM_IDS.LIQSOL_TOKEN,
+        LIQSOL_TOKEN,
     )[0];
 
 export const deriveLiqsolMintAuthorityPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.LIQSOL_MINT_AUTHORITY)],
-        PROGRAM_IDS.LIQSOL_TOKEN,
+        LIQSOL_TOKEN,
     )[0];
 
 export const deriveDepositAuthorityPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.DEPOSIT_AUTHORITY)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const deriveVaultPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.VAULT)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const deriveReservePoolPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.RESERVE_POOL)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const deriveStakeControllerStatePda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.STAKE_CONTROLLER_STATE)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const derivePayoutStatePda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.PAYOUT_STATE)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const deriveBucketAuthorityPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.BUCKET_AUTHORITY)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const deriveDistributionStatePda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.DISTRIBUTION_STATE)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
+/**
+ * user_record PDA
+ *
+ * In the current liqsol_core IDL, this is keyed by USER (wallet),
+ * not by token account.
+ */
 export const deriveUserRecordPda = (user: PublicKey) =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.USER_RECORD), user.toBuffer()],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
 export const derivePayRateHistoryPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.PAY_RATE_HISTORY)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        LIQSOL_CORE,
     )[0];
 
-export const deriveLeaderboardStatePda = () =>
+/**
+ * ---------------------------------------------------------------------------
+ *  WITHDRAW MODULE / RECEIPTS
+ * ---------------------------------------------------------------------------
+ */
+
+export const deriveWithdrawGlobalPda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.LEADERBOARD_STATE)],
-        PROGRAM_IDS.VALIDATOR_LEADERBOARD,
+        [Buffer.from(PDA_SEEDS.WITHDRAW_GLOBAL)],
+        LIQSOL_CORE,
     )[0];
 
-export const deriveValidatorRecordPda = (voteAccount: PublicKey) =>
+export const deriveStakeAllocationStatePda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.VALIDATOR_RECORD), voteAccount.toBuffer()],
-        PROGRAM_IDS.VALIDATOR_LEADERBOARD,
+        [Buffer.from(PDA_SEEDS.STAKE_ALLOCATION_STATE)],
+        LIQSOL_CORE,
     )[0];
 
-export const deriveStakeControllerVaultPda = () =>
+export const deriveStakeMetricsPda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.VAULT)],
-        PROGRAM_IDS.LIQSOL_CORE,
+        [Buffer.from(PDA_SEEDS.STAKE_METRICS)],
+        LIQSOL_CORE,
+    )[0];
+
+export const deriveMaintenanceLedgerPda = () =>
+    PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.MAINTENANCE_LEDGER)],
+        LIQSOL_CORE,
+    )[0];
+
+export const deriveWithdrawMintAuthorityPda = () =>
+    PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.WITHDRAW_MINT_AUTHORITY)],
+        LIQSOL_CORE,
+    )[0];
+
+export const deriveWithdrawMintMetadataPda = () =>
+    PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.MINT_METADATA)],
+        LIQSOL_CORE,
     )[0];
 
 /**
- * OUTPOST 
+ * NFT mint for withdrawal receipt, derived from nextReceiptId.
  */
-export const deriveOutpostGlobalStatePda = () => 
+export const deriveWithdrawNftMintPda = (receiptId: bigint | number) => {
+    const receiptIdBytes = Buffer.alloc(8);
+    // receiptId comes in as BN or bigint upstream → normalize
+    const asBigInt =
+        typeof receiptId === 'bigint'
+            ? receiptId
+            : BigInt(receiptId.toString());
+    receiptIdBytes.writeBigUInt64LE(asBigInt);
+    return PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.WITHDRAW_MINT), receiptIdBytes],
+        LIQSOL_CORE,
+    )[0];
+};
+
+export const deriveLiqReceiptDataPda = (nftMint: PublicKey) =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.WARRANT_DEPOSIT_GLOBAL)],
+        [Buffer.from(PDA_SEEDS.LIQ_RECEIPT_DATA), nftMint.toBuffer()],
         LIQSOL_CORE,
     )[0];
 
-export const deriveOutpostPoolAuthorityPda = () =>
+/**
+ * ---------------------------------------------------------------------------
+ *  VALIDATOR LEADERBOARD
+ * ---------------------------------------------------------------------------
+ */
+
+export const deriveLeaderboardStatePda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.LIQSOL_POOL)],
+        [Buffer.from(PDA_SEEDS.LEADERBOARD_STATE)],
+        VALIDATOR_LEADERBOARD,
+    )[0];
+
+export const deriveValidatorRecordPda = (voteAccount: PublicKey) =>
+    PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.VALIDATOR_RECORD), voteAccount.toBuffer()],
+        VALIDATOR_LEADERBOARD,
+    )[0];
+
+export const deriveStakeControllerVaultPda = () =>
+    PublicKey.findProgramAddressSync(
+        [Buffer.from(PDA_SEEDS.VAULT)],
         LIQSOL_CORE,
     )[0];
 
-export const deriveWireReceiptPda = (user: PublicKey) =>
+/**
+ * ---------------------------------------------------------------------------
+ *  OUTPOST / PRETOKENS
+ * ---------------------------------------------------------------------------
+ */
+
+export const deriveOutpostGlobalStatePda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.WARRANT_DEPOSIT_RECORD), user.toBuffer()],
+        [Buffer.from(PDA_SEEDS.OUTPOST_GLOBAL_STATE)],
         LIQSOL_CORE,
     )[0];
 
-export const derivePoolUserRecordPda = (poolAuthority: PublicKey) =>
+export const deriveOutpostPoolAuthorityPda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.USER_RECORD), poolAuthority.toBuffer()],
+        [Buffer.from(PDA_SEEDS.LIQSOL_POOL)],
         LIQSOL_CORE,
     )[0];
 
-export const deriveUserUserRecordPda = (user: PublicKey) =>
+export const deriveOutpostAccountPda = (user: PublicKey) =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.USER_RECORD), user.toBuffer()],
+        [Buffer.from(PDA_SEEDS.OUTPOST_ACCOUNT), user.toBuffer()],
         LIQSOL_CORE,
     )[0];
 
-export const deriveSolBucketPda = () =>
+export const deriveUserPretokenRecordPda = (user: PublicKey) =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.WIRE_SOL_BUCKET)],
+        [Buffer.from(PDA_SEEDS.USER_PRETOKEN_RECORD), user.toBuffer()],
         LIQSOL_CORE,
     )[0];
 
@@ -211,12 +291,16 @@ export const deriveTrancheStatePda = () =>
         LIQSOL_CORE,
     )[0];
 
-export const deriveUserWarrantRecordPda = (user: PublicKey) =>
+export const derivePriceHistoryPda = () =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.USER_WARRANT_RECORD), user.toBuffer()],
+        [Buffer.from(PDA_SEEDS.PRICE_HISTORY)],
         LIQSOL_CORE,
     )[0];
 
+/**
+ * BAR (bonded actor roles)
+ */
+
 export const deriveBarConfigPda = () =>
     PublicKey.findProgramAddressSync(
         [Buffer.from(PDA_SEEDS.BAR_STATE_SEED)],
@@ -235,10 +319,13 @@ export const deriveBondedActorPda = (actor: PublicKey) =>
         LIQSOL_CORE,
     )[0];
 
-export const derivePriceHistoryPda = () =>
+/**
+ * SPL Transfer-hook: extra-account-metas PDA for the liqSOL mint.
+ */
+export const deriveExtraAccountMetaListPda = (liqsolMint: PublicKey) =>
     PublicKey.findProgramAddressSync(
-        [Buffer.from(PDA_SEEDS.PRICE_HISTORY)],
-        LIQSOL_CORE,
+        [Buffer.from(PDA_SEEDS.EXTRA_ACCOUNT_METAS), liqsolMint.toBuffer()],
+        PROGRAM_IDS.TRANSFER_HOOK,
     )[0];
 
 /**
@@ -247,18 +334,21 @@ export const derivePriceHistoryPda = () =>
  */
 export const deriveEphemeralStakeAddress = async (
     user: PublicKey,
-    seed: any,
+    seed: number,
 ): Promise<PublicKey> => {
     const seedStr = `ephemeral_${seed}`;
-    return await PublicKey.createWithSeed(user, seedStr, StakeProgram.programId);
+    return PublicKey.createWithSeed(user, seedStr, StakeProgram.programId);
 };
 
 /**
- * Constant keys
+ * Constant keys (Chainlink)
  */
-
-export const CHAINLINK_FEED = new PublicKey("99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR");
-export const CHAINLINK_PROGRAM = new PublicKey("HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny");
+export const CHAINLINK_FEED = new PublicKey(
+    '99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR',
+);
+export const CHAINLINK_PROGRAM = new PublicKey(
+    'HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny',
+);
 
 /**
  * ---------------------------------------------------------------------------
@@ -276,14 +366,15 @@ export const DEFAULT_AVERAGE_PAY_RATE = BigInt(191_780_821);
 export const DEFAULT_PAY_RATE_LOOKBACK = 5;
 
 // Rent exemption for ephemeral stake account (lamports)
-// Mirrors EPHEMERAL_RENT_EXEMPTION = 2_282_880 used in tests
 export const EPHEMERAL_RENT_EXEMPTION = 2_282_880;
 
 // For convenience: lamports <-> SOL helpers (no RPC dependency)
 export const LAMPORTS_PER_SOL = 1_000_000_000;
 
+export const INDEX_SCALE = BigInt(1_000_000_000_000); // 1e12
+
 export const lamportsToSol = (lamports: number | bigint): number =>
     Number(lamports) / LAMPORTS_PER_SOL;
 
 export const solToLamports = (sol: number): bigint =>
-    BigInt(Math.round(sol * LAMPORTS_PER_SOL));
+    BigInt(Math.round(sol * LAMPORTS_PER_SOL));