@wireio/stake 0.3.1 → 0.4.1

package/src/networks/ethereum/clients/stake.client.ts

@@ -1,5 +1,5 @@
 import { BigNumber, ethers } from "ethers";
-import { preLaunchReceipt, StakedEvent, WithdrawnStakeEvent, WithdrawnStakeResult } from "../types";
+import { StakedEvent, WithdrawnStakeEvent, WithdrawnStakeResult } from "../types";
 import { EthereumContractService } from "../contract";
 import { formatContractErrors } from "../utils";
 
@@ -28,62 +28,6 @@ export class StakeClient {
     }
 
 
-    /**
-     * Read OPP / Outpost state used by the Depositor to decide whether staking is allowed.
-     * Returns various data
-     */
-    async getOppStatus(): Promise<any> {
-        const depositor = this.contract.Depositor;
-        const opp = this.contract.OPP;
-
-        
-        const oppAddress: string = await depositor.oppAddress();
-        const oppInboundAddress: string = await depositor.oppInboundAddress();
-        const prevEpochSent = await opp.prevEpochSent();
-        
-
-        const inbound = this.contractService.getReadOnly('OPPInbound');
-
-        // Query useful getters
-        const nextEpochBN: any = await inbound.nextEpochNum();
-        const pendingEpochRaw: any = await inbound.pendingEpoch();
-        const pendingMessageCount: any = await inbound.pendingMessageCount();
-        const previousEpochHash: string = await inbound.previousEpochHash();
-        const nextEpochNum = (nextEpochBN && typeof nextEpochBN.toNumber === 'function') ? nextEpochBN.toNumber() : Number(nextEpochBN || 0);
-
-        const pendingEpoch = (pendingEpochRaw && pendingEpochRaw.epochNumber !== undefined)
-            ? {
-                epochNumber: (pendingEpochRaw.epochNumber && typeof pendingEpochRaw.epochNumber.toNumber === 'function') ? pendingEpochRaw.epochNumber.toNumber() : Number(pendingEpochRaw.epochNumber || 0),
-                timestamp: (pendingEpochRaw.timestamp && typeof pendingEpochRaw.timestamp.toNumber === 'function') ? pendingEpochRaw.timestamp.toNumber() : Number(pendingEpochRaw.timestamp || 0),
-                prevEpochHash: pendingEpochRaw.prevEpochHash,
-                merkleRoot: pendingEpochRaw.merkleRoot,
-                firstMessageID: pendingEpochRaw.firstMessageID,
-                lastMessageID: pendingEpochRaw.lastMessageID,
-            }
-            : null;
-
-        const pendingMessagesBN = pendingMessageCount;
-        const pendingMessages = (pendingMessagesBN && typeof pendingMessagesBN.toString === 'function') ? pendingMessagesBN.toString() : String(pendingMessagesBN || '0');
-
-        const hasPendingMessages = (pendingMessagesBN && typeof pendingMessagesBN.gt === 'function') ? pendingMessagesBN.gt(0) : (Number(pendingMessages) > 0);
-
-        return {
-            oppAddress,
-            prevEpochSent,
-            oppInboundAddress,
-            nextEpochNum,
-            pendingEpoch,
-            pendingMessageCount: pendingMessages,
-            previousEpochHash,
-            hasPendingMessages,
-            raw: {
-                nextEpochBN,
-                pendingEpochRaw,
-                pendingMessageCount: pendingMessagesBN,
-            },
-        };
-    }
-
 
     /**
      * 
@@ -153,97 +97,6 @@ export class StakeClient {
 
 
 
-    async getOwnedTokenIdsFor(
-        owner: string,
-        fromBlock = 1850820,
-        toBlock: number | string = "latest"
-    ): Promise<BigNumber[]> {
-        const receiptContract = this.contract.ReceiptNFT;
-
-        // Logs where address received tokens
-        const toLogs = await receiptContract.queryFilter(
-            receiptContract.filters.Transfer(null, owner),
-            fromBlock,
-            toBlock
-        );
-
-        // Logs where address sent tokens (including burns from owner → 0)
-        const fromLogs = await receiptContract.queryFilter(
-            receiptContract.filters.Transfer(owner, null),
-            fromBlock,
-            toBlock
-        );
-
-        const owned = new Set<string>();
-
-        // Add all received tokenIds
-        for (const e of toLogs) {
-            const tokenId = e.args?.tokenId;
-            if (!tokenId) continue;
-            owned.add(tokenId.toString());
-        }
-
-        // Remove all sent tokenIds
-        for (const e of fromLogs) {
-            const tokenId = e.args?.tokenId;
-            if (!tokenId) continue;
-            owned.delete(tokenId.toString());
-        }
-
-        // Convert to BigNumbers
-        return Array.from(owned).map((id) => BigNumber.from(id));
-    }
-
-
-    /**
-     * 
-     * @param amountWei an amount of liqETH (in WEI) to stake to the Outpost
-     * @returns txHash (hash of the transaction), receipt, WithdrawnStake event
-     */
-    async fetchPreLaunchReceipts(address: string): Promise<preLaunchReceipt[]> {
-        const receiptContract = this.contract.ReceiptNFT;
-
-        // first figure out which tokenIds this address owns, from events
-        const tokenIds = await this.getOwnedTokenIdsFor(address);
-
-        const results: preLaunchReceipt[] = [];
-
-        // next fetch on-chain receipt data just for those ids
-        for (const idBN of tokenIds) {
-            try {
-                const receiptData = await receiptContract.getReceipt(idBN);
-                const formattedReceipt = {
-                    account: receiptData.account,
-                    currency: receiptData.currency,
-                    kind: receiptData.kind,
-                    indexAtMint: receiptData.indexAtMint.toBigInt(),
-                    principal: {
-                        amount: receiptData.principal.toBigInt(),
-                        decimals: 18,
-                        symbol: "LiqETH"
-                    },
-                    shares: {
-                        amount: receiptData.shares.toBigInt(),
-                        decimals: 18,
-                        symbol: "LiqETH"
-                    },
-                    timestamp: new Date(Number(receiptData.timestamp.toString()) * 1000).toLocaleString(),
-                }
-
-                // Only fetch staking receipts (kind 1 is a wire pretoken receipt)
-                if(receiptData.kind == 0) results.push({ tokenId: idBN.toBigInt(), receipt: formattedReceipt } as any);
-            } catch (err) {
-                // in case of any mismatch or race, just skip this id
-                console.warn(`Failed to load receipt for tokenId=${idBN.toString()}`, err);
-                continue;
-            }
-        }
-
-        console.log('results of prelaunch receipts', results)
-        return results;
-    }
-
-
     /**
      * 
      * @param amountWei an amount of liqETH (in WEI) to stake to the Outpost

package/src/networks/ethereum/contract.ts

@@ -21,6 +21,7 @@ import OPPInboundArtifact from '../../assets/ethereum/ABI/outpost/OPPInbound.sol
 import PretokenArtifact from '../../assets/ethereum/ABI/outpost/Pretoken.sol/Pretoken.json';
 import AggregatorArtifact from '../../assets/ethereum/ABI/outpost/Aggregator.sol/Aggregator.json';
 import EthUsdPriceConsumerArtifact from '../../assets/ethereum/ABI/outpost/EthUsdPriceConsumer.sol/EthUsdPriceConsumer.json';
+import PoolArtifact from '../../assets/ethereum/ABI/outpost/Pool.sol/Pool.json';
 
 import ERC20Artifact from '../../assets/ethereum/ABI/token/ERC20Token.sol/ERC20Token.json';
 import ERC721Artifact from '../../assets/ethereum/ABI/token/ERC721Token.sol/ERC721Token.json';
@@ -41,6 +42,7 @@ export const ERC1155Abi = ERC1155Artifact.abi;
 
 // Make sure ContractName in ./types includes all of these keys.
 export const ADDRESSES: AddressBook = {
+    // LiqETH contracts
     Accounting: "0xd333A03a44D5d602A98c1B7bcd7ED1f042DD0dEd",
     DepositManager: "0x601eaA31e8d33D8725786f1733f4cE6cCEf740D4",
     LiqEth: "0x08252e1Dcbaa86A2887927b02536CD3E67a802c8", // AKA LiqEthToken
@@ -48,10 +50,6 @@ export const ADDRESSES: AddressBook = {
     WithdrawalQueue: "0x951E413FC81a2CE133078ABE8B88677F5296abE7",
     WithdrawalVault: "0x0D2bf834DD560839e986d42D06DeE268A17c2d13",
 
-    // LiqEthAuthority: "0x7A9cf59EC53F32577Cc8200466Cc7693713129D5",
-    // BeaconState: "0xD3860E5977C94b343341635a2dEEBD20B651c48f",
-    // YieldOracle: "0x307b35816674913cf122975B3CF912b5709653F3",
-    
     //Outpost contracts
     Depositor: "0x69Aa53Ef02F124dB421AeDda509d6912341299Cc",
     ReceiptNFT: "0x13588fF41E2f47D047874162B1eD15AaF6818f5a",
@@ -63,6 +61,7 @@ export const ADDRESSES: AddressBook = {
     Pretoken: "0xcf6A1209A7A391cc576174204386F4e5462323dC",
     EthUsdPriceConsumer: "0x1Ef180FF49313fCB8B5c0470268295d0d24CDE69",
     Aggregator: "0xFCfc3ddd4CBd9Ad3b3af3A374B8bdA1b66eE6FFF",
+    Pool: "0x29DEf0fA009e02d108d9505018EAe0168F233e03",
 };
 
 export type Contracts<T extends string = ContractName> = Record<T, ContractConfig>;
@@ -142,6 +141,10 @@ export const CONTRACTS: Contracts<ContractName> = {
     EthUsdPriceConsumer: {
         address: ADDRESSES.EthUsdPriceConsumer,
         abi: EthUsdPriceConsumerArtifact.abi as JsonFragment[],
+    },
+    Pool: {
+        address: ADDRESSES.Pool,
+        abi: PoolArtifact.abi as JsonFragment[],
     }
 };
 

package/src/networks/ethereum/ethereum.ts

@@ -1,13 +1,20 @@
 import { BigNumber, ethers } from 'ethers';
-import { IStakingClient, Portfolio, StakerConfig, TrancheSnapshot } from '../../types';
 import { ChainID, EvmChainID, PublicKey as WirePubKey } from '@wireio/core';
+import { 
+    IStakingClient,
+    OPPAssertion,
+    Portfolio, 
+    StakerConfig, 
+    TrancheSnapshot 
+} from '../../types';
 import { EthereumContractService } from './contract';
 import { preLaunchReceipt } from './types';
-import { DepositClient } from './clients/deposit.client';
+import { buildEthereumTrancheSnapshot } from './utils';
+import { ConvertClient } from './clients/convert.client';
 import { StakeClient } from './clients/stake.client';
 import { PretokenClient } from './clients/pretoken.client';
-import { buildEthereumTrancheSnapshot } from './utils';
-import { LiqClient } from './clients/liq.client';
+import { OPPClient } from './clients/opp.client';
+import { ReceiptClient } from './clients/receipt.client';
 
 
 
@@ -18,10 +25,11 @@ export class EthereumStakingClient implements IStakingClient {
     private readonly signer: ethers.Signer;
     private readonly contractService: EthereumContractService;
 
-    private depositClient: DepositClient;
-    private liqClient: LiqClient;
+    private convertClient: ConvertClient;
     private pretokenClient: PretokenClient;
     private stakeClient: StakeClient;
+    private oppClient: OPPClient;
+    private receiptClient: ReceiptClient;
 
 
     get contract() { return this.contractService.contract; }
@@ -38,10 +46,11 @@ export class EthereumStakingClient implements IStakingClient {
                 signer: this.signer,
             });
             
-            this.depositClient = new DepositClient(this.contractService);
-            this.liqClient = new LiqClient(this.contractService);
+            this.convertClient = new ConvertClient(this.contractService);
             this.pretokenClient = new PretokenClient(this.contractService);
             this.stakeClient = new StakeClient(this.contractService);
+            this.oppClient = new OPPClient(this.contractService);
+            this.receiptClient = new ReceiptClient(this.contractService);
         }   
         catch (error) {
             // console.error('Error initializing EthereumStakingClient:', error);
@@ -66,7 +75,7 @@ export class EthereumStakingClient implements IStakingClient {
             ? amount
             : BigNumber.from(amount);
 
-        const result = await this.depositClient.performDeposit(amountWei);
+        const result = await this.convertClient.performDeposit(amountWei);
         return result.txHash;
     }
 
@@ -80,18 +89,15 @@ export class EthereumStakingClient implements IStakingClient {
     async withdraw(amount: bigint): Promise<string> {
         const address = await this.signer.getAddress();
         const amountWei = BigNumber.from(amount);
-        // const chainId = this.network?.chainId ?? (await this.provider.getNetwork()).chainId;
-        // const result = await this.depositClient.requestWithdraw(amountWei, this.signer, chainId);
 
-        const result = await this.liqClient.safeBurn(address, amountWei)
+        const result = await this.convertClient.performWithdraw(address, amountWei)
         return result.txHash;
     }
 
 
     /**
      * Stake liqETH via DepositManager.
-     * @param amount  Amount in wei 
-     *                Keep this as a bigint / string in the caller; avoid JS floats.
+     * @param amount  Amount in wei - Keep this as a bigint / string in the caller; avoid JS floats.
      * @returns transaction hash
      */
     async stake(amount: bigint): Promise<string> {
@@ -125,71 +131,38 @@ export class EthereumStakingClient implements IStakingClient {
 
     async buy(amount: bigint): Promise<string> {
         const buyer = await this.signer.getAddress();
-        const amountBigNum = BigNumber.from(amount)
 
         // ! Hoodi only - check if the mock aggregator price is stale, and if so, update it before submitting the buy request
         await this.updateMockAggregatorPrice();
-        
-
-        const bal = await this.contract.LiqEth.balanceOf(buyer);
-        const paused = await this.contract.Depositor.paused();
-        if(paused) {
-            throw new Error("Error - Depositor is in a paused state");
-        }
-
-        // if current liq balance is less than the requested buy amount, throw an error
-        if (bal.lt(amount)) {
-            throw new Error(`Balance insufficient for pre-token purchase`);
-        }
-
-        //check that the contract has allowance for the token
-        const depositorAddr = this.contract.Depositor.address;
-        const allowance = await this.contract.LiqEth.allowance(buyer, depositorAddr);
-
-        // if allowance is less than the requested stake amount, request permission to spend LiqEth
-        if (allowance.lt(amount)) {
-            const liqWrite = this.contractService.getWrite('LiqEth');
-
-            // currently requested unlimited amount - potentially change to only request up to the current amount?
-            const approveAmount = ethers.constants.MaxUint256;
-
-            console.warn(`allowance insufficient (${allowance.toString()} < ${amount.toString()}); sending approve(${depositorAddr}, ${approveAmount.toString()})`);
-
-            const approveTx = await liqWrite.approve(depositorAddr, approveAmount);
-            await approveTx.wait(1);
-
-            // re-read allowance to ensure approval succeeded
-            const newAllowance = await this.contract.LiqEth.allowance(buyer, depositorAddr);
-            if (newAllowance.lt(amount)) {
-                throw new Error('Approval failed or allowance still insufficient after approve');
-            }
-        }
-
-
-        let result = await this.pretokenClient.purchasePretokensWithLiqETH(amountBigNum, buyer);
 
+        let result = await this.pretokenClient.purchasePretokensWithLiqETH(amount, buyer);
         return result && result.txHash ? result.txHash : "Error - no resulting txHash";
     }
 
 
-    
+    async getOPPMessages(address?: string): Promise<OPPAssertion[]> {
+        if(!address) address = await this.signer.getAddress();
+        
+        return await this.oppClient.getMessages(address);
+    }
+
 
     async getOPPStatus(): Promise<any> {
-        return await this.stakeClient.getOppStatus();
+        return await this.oppClient.getStatus();
     }
 
 
     
     /**
-     * ETH Prelaunch function to list the ReceiptNFTs owned by a specific user
+     * ETH Prelaunch function to list the Stake ReceiptNFTs owned by a specific user
      * @param address address to query the receipts for
      * @returns array of receipts
      */
     async fetchPrelaunchReceipts(address?: string): Promise<preLaunchReceipt[]> {
         if(address === undefined) address = await this.signer.getAddress();
         
-        let receipts = await this.stakeClient.fetchPreLaunchReceipts(address);
-        return receipts
+        //default to stake receipts
+        return await this.receiptClient.stakeReceipts(address);
     }
 
     
@@ -206,6 +179,7 @@ export class EthereumStakingClient implements IStakingClient {
         }
     }
 
+
     /**
      * Resolve the user's ETH + liqETH balances.
      *
@@ -215,8 +189,6 @@ export class EthereumStakingClient implements IStakingClient {
      */
     async getPortfolio(): Promise<Portfolio> {
         const walletAddress = await this.signer.getAddress();
-        // console.log('getPortfolio() wallet address', walletAddress)
-
 
         // 1) Native ETH balance
         const nativeBalance = await this.provider.getBalance(walletAddress);
@@ -227,9 +199,16 @@ export class EthereumStakingClient implements IStakingClient {
         const liqBalance: ethers.BigNumber = await this.contract.LiqEth.balanceOf(walletAddress);
         const liqSymbol = 'Liq' + (this.network?.nativeCurrency?.symbol ?? 'ETH');
 
-        // 3) staked liqEth ERC-20 balance (actual)
-        const stakedLiqBalance = await this.contract.Depositor.sharesOf(walletAddress);
+        // 3) staked liqEth ERC-20 balance (calculate from receipts)
+        let stakeReceipts = await this.receiptClient.stakeReceipts(walletAddress);
+        let stakeBalanceBN = BigNumber.from(0);
+        for (let r of stakeReceipts) {
+            stakeBalanceBN = stakeBalanceBN.add(BigNumber.from(r.receipt.principal.amount));
+        }
+
 
+        // 4) WIRE pretoken balance
+        const wireBalance: ethers.BigNumber = await this.contract.Pretoken.balanceOf(walletAddress);
 
         const portfolio: Portfolio = {
             native: {
@@ -242,19 +221,14 @@ export class EthereumStakingClient implements IStakingClient {
                 decimals: nativeDecimals,
                 symbol: liqSymbol,
             },
-            tracked: {
-                amount: liqBalance.toBigInt(),
-                decimals: nativeDecimals,
-                symbol: liqSymbol,
-            },
             staked: {
-                amount: stakedLiqBalance.toBigInt(),
+                amount: stakeBalanceBN.toBigInt(),
                 decimals: nativeDecimals,
                 symbol: liqSymbol,
             },
             wire: {
-                amount: BigInt(0), // TODO
-                decimals: 0,
+                amount: wireBalance.toBigInt(),
+                decimals: 18,
                 symbol: '$WIRE',
             },
             chainID: this.network.chainId

package/src/networks/ethereum/types.ts

@@ -20,6 +20,7 @@ export const CONTRACT_NAMES = [
     'Pretoken',
     'Aggregator',
     'EthUsdPriceConsumer',
+    'Pool',
 
 ] as const;
 

package/src/networks/ethereum/utils.ts

@@ -300,7 +300,7 @@ export async function buildEthereumTrancheSnapshot(options: {
         priceGrowthBps,
         currentTrancheSupply,
         initialTrancheSupply,
-        totalWarrantsSold: totalTrancheSupply,
+        totalPretokensSold: totalTrancheSupply,
         nativePriceUsd: ethPriceUsd,
         nativePriceTimestamp,
         ladder,

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

@@ -1,6 +1,5 @@
 import { AnchorProvider, BN, Program } from '@coral-xyz/anchor';
 import {
-    PublicKey,
     SystemProgram,
     Transaction,
     TransactionInstruction,
@@ -27,26 +26,54 @@ import {
     deriveReservePoolPda,
     deriveVaultPda,
     deriveStakeControllerStatePda,
+    derivePayoutStatePda,
     deriveBucketAuthorityPda,
     derivePayRateHistoryPda,
     deriveDistributionStatePda,
     deriveUserRecordPda,
-    derivePayoutStatePda,
     deriveEphemeralStakeAddress,
+    deriveWithdrawGlobalPda,
+    deriveStakeAllocationStatePda,
+    deriveStakeMetricsPda,
+    deriveMaintenanceLedgerPda,
+    deriveWithdrawMintAuthorityPda,
+    deriveWithdrawMintMetadataPda,
+    deriveWithdrawNftMintPda,
+    deriveLiqReceiptDataPda,
 } from '../constants';
 import { WalletLike } from '../types';
 
 export class DepositClient {
     private program: Program<LiqsolCore>;
 
-    get wallet(): WalletLike { return this.provider.wallet; }
+    get wallet(): WalletLike {
+        return this.provider.wallet;
+    }
 
     constructor(private provider: AnchorProvider) {
         const svc = new SolanaProgramService(provider);
         this.program = svc.getProgram('liqsolCore');
     }
 
-    async buildDepositTx(amount: bigint, user = this.wallet.publicKey): Promise<Transaction> {
+    /**
+     * Build a deposit transaction:
+     *   SOL -> liqSOL via liqsol_core::deposit.
+     */
+    async buildDepositTx(
+        amount: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<Transaction> {
+        if (!user) {
+            throw new Error(
+                'DepositClient.buildDepositTx: wallet not connected',
+            );
+        }
+        if (!amount || amount <= BigInt(0)) {
+            throw new Error(
+                'DepositClient.buildDepositTx: amount must be greater than zero.',
+            );
+        }
+
         // -------------------------------------------------------------
         // PDAs
         // -------------------------------------------------------------
@@ -59,8 +86,6 @@ export class DepositClient {
         const payoutState = derivePayoutStatePda();
         const bucketAuthority = deriveBucketAuthorityPda();
         const payRateHistory = derivePayRateHistoryPda();
-        const distributionState = deriveDistributionStatePda();
-        const userRecord = deriveUserRecordPda(user);
 
         // -------------------------------------------------------------
         // Token-2022 ATAs
@@ -69,14 +94,20 @@ export class DepositClient {
             liqsolMint,
             user,
             false,
-            TOKEN_2022_PROGRAM_ID
+            TOKEN_2022_PROGRAM_ID,
         );
 
+        // -------------------------------------------------------------
+        // Distribution state + user_record (KEYED BY TOKEN ACCOUNT)
+        // -------------------------------------------------------------
+        const distributionState = deriveDistributionStatePda();
+        const userRecord = deriveUserRecordPda(userAta);
+
         const bucketTokenAccount = getAssociatedTokenAddressSync(
             liqsolMint,
             bucketAuthority,
             true,
-            TOKEN_2022_PROGRAM_ID
+            TOKEN_2022_PROGRAM_ID,
         );
 
         // -------------------------------------------------------------
@@ -124,4 +155,119 @@ export class DepositClient {
 
         return new Transaction().add(ix);
     }
+
+    /**
+     * Build a withdraw-request transaction:
+     *   liqSOL -> SOL via liqsol_core::requestWithdraw.
+     *
+     * This:
+     *  - burns liqSOL from the user
+     *  - increments totalEncumberedFunds in global state
+     *  - mints an NFT receipt (liqReceiptData + NFT ATA for owner)
+     */
+    async buildWithdrawTx(
+        amount: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<Transaction> {
+        if (!user) {
+            throw new Error(
+                'DepositClient.buildWithdrawTx: wallet not connected',
+            );
+        }
+        if (!amount || amount <= BigInt(0)) {
+            throw new Error(
+                'DepositClient.buildWithdrawTx: amount must be greater than zero.',
+            );
+        }
+
+        // -------------------------------------------------------------
+        // Core program + liqSOL mint / user ATA
+        // -------------------------------------------------------------
+        const liqsolMint = deriveLiqsolMintPda();
+
+        const userAta = getAssociatedTokenAddressSync(
+            liqsolMint,
+            user,
+            false,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        // Distribution / balance-tracking
+        // user_record is keyed by the user’s liqSOL ATA (same convention as deposit/purchase)
+        const userRecord = deriveUserRecordPda(userAta);
+        const distributionState = deriveDistributionStatePda();
+
+        // Reserve + stake controller PDAs
+        const global = deriveWithdrawGlobalPda();
+        const reservePool = deriveReservePoolPda();
+        const stakeAllocationState = deriveStakeAllocationStatePda();
+        const stakeMetrics = deriveStakeMetricsPda();
+        const maintenanceLedger = deriveMaintenanceLedgerPda();
+
+        // -------------------------------------------------------------
+        // Need nextReceiptId from withdraw global state
+        // -------------------------------------------------------------
+        const globalState = await this.program.account.global.fetch(global);
+        const receiptId = (globalState.nextReceiptId as BN).toBigInt();
+
+        // -------------------------------------------------------------
+        // NFT receipt PDAs (mint, metadata, data, ATA)
+        // -------------------------------------------------------------
+        const mintAuthority = deriveWithdrawMintAuthorityPda();
+        const metadata = deriveWithdrawMintMetadataPda();
+
+        const nftMint = deriveWithdrawNftMintPda(receiptId);
+        const receiptData = deriveLiqReceiptDataPda(nftMint);
+
+        const owner = user;
+        const nftAta = getAssociatedTokenAddressSync(
+            nftMint,
+            owner,
+            false,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        // Bucket token account (same bucket used by deposit/distribution)
+        const bucketAuthority = deriveBucketAuthorityPda();
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        // -------------------------------------------------------------
+        // BUILD IX (MUST MATCH requestWithdraw IDL)
+        // -------------------------------------------------------------
+        const ix: TransactionInstruction = await this.program.methods
+            .requestWithdraw(new BN(amount.toString()))
+            .accounts({
+                user,
+                owner,
+                global,
+                liqsolMint,
+                userAta,
+                userRecord,
+                reservePool,
+                stakeAllocationState,
+                stakeMetrics,
+                maintenanceLedger,
+                clock: SYSVAR_CLOCK_PUBKEY,
+                mintAuthority,
+                receiptData,
+                metadata,
+                nftMint,
+                nftAta,
+                distributionState,
+                bucketTokenAccount,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                tokenInterface: TOKEN_2022_PROGRAM_ID,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                systemProgram: SystemProgram.programId,
+                rent: SYSVAR_RENT_PUBKEY,
+            })
+            .instruction();
+
+        return new Transaction().add(ix);
+    }
 }