@emblemvault/primitives-stake 0.1.0

package/dist/client.js

@@ -0,0 +1,749 @@
+/**
+ * EmblemStake — TS client for the stake program.
+ *
+ * Tier-1 surface: a developer outside Emblem:build runs `npm install
+ * @emblemvault/primitives-stake @emblemvault/auth-sdk`, hands the SDK an
+ * auth-sdk signer, creates pools / stakes / claims rewards.
+ *
+ * Phase 1+ status:
+ *   - PDA derivation, getPool/getVault/getDistribution — work today
+ *     against any deployed program (read paths)
+ *   - evaluateStakeGate — works today: takes a StakeVaultAccount + minimum,
+ *     returns granted/lockExpired. This is what sdk/gate's stake-mode
+ *     evaluator will call via the gate program's CPI; the off-chain version
+ *     is useful for previews and tests
+ *   - createPool / stake / unstake / claim / distributeRewards — stub
+ *     NotYetImplemented until programs/stake ships (Phase 3)
+ */
+import { PublicKey, SystemProgram, SYSVAR_RENT_PUBKEY, Transaction, TransactionInstruction, } from '@solana/web3.js';
+import { TOKEN_PROGRAM_ID } from '@solana/spl-token';
+import { EmblemError, } from '@emblemvault/primitives-shared';
+import { decodeRewardDistributionAccount, decodeStakePoolAccount, decodeStakeVaultAccount, MULTIPLIER_SCALE, PENALTY_TAG_BURN, PENALTY_TAG_REDISTRIBUTE, PENALTY_TAG_TREASURY_PDA, REWARD_CADENCE_DAILY, REWARD_CADENCE_HOURLY, REWARD_CADENCE_WEEKLY, REWARD_FORMULA_LINEAR_V1, REWARD_FORMULA_SAMMY_V1, REWARD_SOURCE_TAG_DIST_VAULT, REWARD_SOURCE_TAG_SPLIT_RECIPIENT, STAKE_POOL_DISCRIMINATOR, STAKE_VAULT_DISCRIMINATOR, } from './codec.js';
+import { deriveRewardDistPda, deriveStakePoolPda, deriveStakeVaultPda, STAKE_PROGRAM_ID, } from './pda.js';
+// =============================================================================
+// Anchor instruction discriminators
+// =============================================================================
+const IX_CREATE_POOL = Buffer.from([
+    0xe9, 0x92, 0xd1, 0x8e, 0xcf, 0x68, 0x40, 0xbc,
+]);
+const IX_REGISTER_REWARD_VAULT = Buffer.from([
+    0xcb, 0x37, 0x29, 0x9c, 0xfc, 0x7f, 0xb9, 0xef,
+]);
+const IX_REGISTER_PENDING_ACTION_VAULT = Buffer.from([
+    0x5b, 0x60, 0x22, 0xa1, 0x04, 0x7c, 0xa3, 0x62,
+]);
+const IX_REGISTER_POOL_TOKEN_ACCOUNTS = Buffer.from([
+    0x3c, 0xd3, 0x00, 0x47, 0x80, 0x7b, 0xc8, 0x52,
+]);
+const IX_STAKE = Buffer.from([
+    0xce, 0xb0, 0xca, 0x12, 0xc8, 0xd1, 0xb3, 0x6c,
+]);
+const IX_UNSTAKE = Buffer.from([
+    0x5a, 0x5f, 0x6b, 0x2a, 0xcd, 0x7c, 0x32, 0xe1,
+]);
+const IX_CLAIM = Buffer.from([
+    0x3e, 0xc6, 0xd6, 0xc1, 0xd5, 0x9f, 0x6c, 0xd2,
+]);
+const IX_DISTRIBUTE_REWARDS = Buffer.from([
+    0x61, 0x06, 0xe3, 0xff, 0x7c, 0xa5, 0x03, 0x94,
+]);
+const ACTION_TYPE_BUYBACK_BURN = 0;
+const ACTION_TYPE_LP_REINFORCE = 1;
+// =============================================================================
+// Borsh helpers
+// =============================================================================
+function bsString(s) {
+    const utf8 = Buffer.from(s, 'utf-8');
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(utf8.length, 0);
+    return Buffer.concat([len, utf8]);
+}
+function bsOptString(s) {
+    if (s == null)
+        return Buffer.from([0]);
+    return Buffer.concat([Buffer.from([1]), bsString(s)]);
+}
+function bsOptU64(v) {
+    if (v == null)
+        return Buffer.from([0]);
+    const buf = Buffer.alloc(9);
+    buf.writeUInt8(1, 0);
+    buf.writeBigUInt64LE(v, 1);
+    return buf;
+}
+function u32(n) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(n, 0);
+    return b;
+}
+function u16(n) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16LE(n, 0);
+    return b;
+}
+function u64(n) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(n, 0);
+    return b;
+}
+function encodePenaltyDestination(p) {
+    switch (p.kind) {
+        case 'redistribute':
+            return Buffer.from([PENALTY_TAG_REDISTRIBUTE]);
+        case 'burn':
+            return Buffer.from([PENALTY_TAG_BURN]);
+        case 'treasury-pda':
+            return Buffer.concat([Buffer.from([PENALTY_TAG_TREASURY_PDA]), bsString(p.id)]);
+    }
+}
+function encodeRewardSource(s) {
+    if (s.type === 'distribution-vault') {
+        return Buffer.concat([Buffer.from([REWARD_SOURCE_TAG_DIST_VAULT]), bsString(s.id)]);
+    }
+    return Buffer.concat([
+        Buffer.from([REWARD_SOURCE_TAG_SPLIT_RECIPIENT]),
+        bsString(s.fromConfigId),
+    ]);
+}
+function encodeRewardCadence(c) {
+    if (c === 'hourly')
+        return REWARD_CADENCE_HOURLY;
+    if (c === 'daily')
+        return REWARD_CADENCE_DAILY;
+    return REWARD_CADENCE_WEEKLY;
+}
+function encodeRewardFormula(f) {
+    return f === 'linear-v1' ? REWARD_FORMULA_LINEAR_V1 : REWARD_FORMULA_SAMMY_V1;
+}
+/**
+ * Vault-authority PDA. Owns all program-managed token accounts (reward
+ * vaults + pending vaults). Same value across the whole program.
+ */
+function deriveVaultAuthority(programId) {
+    return PublicKey.findProgramAddressSync([Buffer.from('vault-authority')], programId)[0];
+}
+function deriveRewardVault(vaultId, programId) {
+    return PublicKey.findProgramAddressSync([Buffer.from('reward-vault'), Buffer.from(vaultId)], programId)[0];
+}
+function deriveRewardVaultForPool(poolPda, programId) {
+    // staker-pool reward vault uses the pool PDA bytes as the vault id
+    return PublicKey.findProgramAddressSync([Buffer.from('reward-vault'), poolPda.toBytes()], programId)[0];
+}
+function derivePendingActionVault(configId, mint, actionType, programId) {
+    return PublicKey.findProgramAddressSync([
+        Buffer.from('pending-vault'),
+        Buffer.from(configId),
+        mint.toBytes(),
+        Buffer.from([actionType]),
+    ], programId)[0];
+}
+export class EmblemStakeError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[EmblemStake/${EmblemError[code]}] ${message}`);
+        this.name = 'EmblemStakeError';
+        this.code = code;
+    }
+}
+export class EmblemStakeClient {
+    connection;
+    programId;
+    signer;
+    commitment;
+    constructor(opts) {
+        this.connection = opts.connection;
+        this.programId = new PublicKey(opts.programId ?? STAKE_PROGRAM_ID);
+        this.signer = opts.signer;
+        this.commitment = opts.commitment ?? 'confirmed';
+    }
+    getProgramId() {
+        return this.programId.toBase58();
+    }
+    // ==========================================================================
+    // PDA derivation
+    // ==========================================================================
+    derivePoolPda(args) {
+        const { pda, bump } = deriveStakePoolPda({
+            asset: args.asset,
+            poolId: args.poolId,
+            programId: this.programId.toBase58(),
+        });
+        return { poolPda: pda.toBase58(), bump };
+    }
+    deriveVaultPda(args) {
+        const { pda, bump } = deriveStakeVaultPda({
+            poolPda: args.poolPda,
+            owner: args.owner,
+            programId: this.programId.toBase58(),
+        });
+        return { vaultPda: pda.toBase58(), bump };
+    }
+    deriveDistributionPda(args) {
+        const { pda, bump } = deriveRewardDistPda({
+            poolPda: args.poolPda,
+            periodId: args.periodId,
+            programId: this.programId.toBase58(),
+        });
+        return { distributionPda: pda.toBase58(), bump };
+    }
+    // ==========================================================================
+    // Reads
+    // ==========================================================================
+    async getPool(poolPda) {
+        const key = new PublicKey(poolPda);
+        const info = await this.connection.getAccountInfo(key, this.commitment);
+        if (!info)
+            return null;
+        if (!info.owner.equals(this.programId)) {
+            throw new EmblemStakeError(EmblemError.InvalidPda, `account ${poolPda} is owned by ${info.owner.toBase58()}, not the stake program ${this.programId.toBase58()}`);
+        }
+        const decoded = decodeStakePoolAccount(info.data);
+        return { ...decoded, poolPda };
+    }
+    async getVault(args) {
+        const owner = args.owner ?? this.signer?.publicKey;
+        if (!owner) {
+            throw new EmblemStakeError(EmblemError.MissingAccount, 'getVault requires either an explicit owner arg or a signer on the client');
+        }
+        const { vaultPda } = this.deriveVaultPda({ poolPda: args.poolPda, owner });
+        const key = new PublicKey(vaultPda);
+        const info = await this.connection.getAccountInfo(key, this.commitment);
+        if (!info)
+            return null;
+        if (!info.owner.equals(this.programId)) {
+            throw new EmblemStakeError(EmblemError.InvalidPda, `account ${vaultPda} is owned by ${info.owner.toBase58()}, not the stake program ${this.programId.toBase58()}`);
+        }
+        const decoded = decodeStakeVaultAccount(info.data);
+        return { ...decoded, vaultPda };
+    }
+    async getDistribution(distributionPda) {
+        const key = new PublicKey(distributionPda);
+        const info = await this.connection.getAccountInfo(key, this.commitment);
+        if (!info)
+            return null;
+        const decoded = decodeRewardDistributionAccount(info.data);
+        return { ...decoded, distributionPda };
+    }
+    /** List all vaults belonging to a pool. RPC-expensive on mainnet. */
+    async listVaultsByPool(poolPda) {
+        const poolKey = new PublicKey(poolPda);
+        // pool_pda field offset = disc(8) + bump(1) = 9.
+        const POOL_FIELD_OFFSET = 9;
+        const filters = [
+            { memcmp: { offset: 0, bytes: bs58Encode(STAKE_VAULT_DISCRIMINATOR) } },
+            { memcmp: { offset: POOL_FIELD_OFFSET, bytes: poolKey.toBase58() } },
+        ];
+        const accounts = await this.connection.getProgramAccounts(this.programId, {
+            commitment: this.commitment,
+            filters,
+        });
+        return accounts.map((a) => {
+            const decoded = decodeStakeVaultAccount(a.account.data);
+            return { ...decoded, vaultPda: a.pubkey.toBase58() };
+        });
+    }
+    /** List all pools created by an authority. */
+    async listPoolsByAuthority(authority) {
+        const authorityKey = new PublicKey(authority);
+        const AUTHORITY_FIELD_OFFSET = 9;
+        const filters = [
+            { memcmp: { offset: 0, bytes: bs58Encode(STAKE_POOL_DISCRIMINATOR) } },
+            { memcmp: { offset: AUTHORITY_FIELD_OFFSET, bytes: authorityKey.toBase58() } },
+        ];
+        const accounts = await this.connection.getProgramAccounts(this.programId, {
+            commitment: this.commitment,
+            filters,
+        });
+        return accounts.map((a) => {
+            const decoded = decodeStakePoolAccount(a.account.data);
+            return { ...decoded, poolPda: a.pubkey.toBase58() };
+        });
+    }
+    // ==========================================================================
+    // Off-chain stake-mode evaluator — works today
+    // ==========================================================================
+    /**
+     * Evaluate "does this user pass a stake-mode gate?" given a vault account
+     * and a minimum threshold. Pure off-chain math; no chain calls.
+     *
+     * sdk/gate's evaluateOffChain stake-mode currently throws NotYetImplemented;
+     * with this client, you can compose the two yourself:
+     *
+     *   const vault = await stake.getVault({ poolPda, owner: user });
+     *   if (!vault) return { granted: false, evidence: { stakedAmount: 0, ... } };
+     *   return stake.evaluateStakeGate(vault, minStake, nowUnixSeconds);
+     *
+     * "Granted" semantics: per 02-recipes.md §I and the GateRule shape, gate
+     * stake-mode is "user has at least N tokens currently staked in the named
+     * pool". We don't require the lock to still be active — the user is welcome
+     * to unstake (paying penalty) but for as long as the stake exists, the
+     * gate grants.
+     */
+    evaluateStakeGate(vault, minStake, nowUnixSeconds) {
+        const stakedAmount = Number(vault.stakedAmount);
+        return {
+            granted: stakedAmount >= minStake,
+            evidence: {
+                stakedAmount,
+                lockEndsAt: vault.lockEndsAt,
+                lockExpired: nowUnixSeconds >= vault.lockEndsAt,
+            },
+        };
+    }
+    // ==========================================================================
+    // Instruction builders
+    // ==========================================================================
+    /**
+     * Build the create_pool instruction. Encodes the full StakePoolConfig
+     * including Vec<LockTier>, Vec<RewardSource>, and the tagged-enum
+     * PenaltyDestination.
+     */
+    buildCreatePoolIx(args) {
+        const poolId = args.poolId ?? 0;
+        const cfg = args.config;
+        const asset = new PublicKey(cfg.asset);
+        const { poolPda } = this.derivePoolPda({
+            asset: cfg.asset,
+            poolId,
+        });
+        const lockTiers = cfg.lockOptions.map((t) => ({
+            days: t.days,
+            // Convert decimal multiplier (1.5) to fixed-point ×1000 (1500)
+            multiplier: Math.round(t.multiplier * MULTIPLIER_SCALE),
+        }));
+        const data = Buffer.concat([
+            IX_CREATE_POOL,
+            u32(poolId),
+            Buffer.from(asset.toBytes()),
+            bsOptString(cfg.hostUrl),
+            // Vec<LockTier>
+            u32(lockTiers.length),
+            ...lockTiers.flatMap((t) => [u32(t.days), u32(t.multiplier)]),
+            u64(BigInt(cfg.minStake)),
+            bsOptU64(cfg.maxStakePerVault != null ? BigInt(cfg.maxStakePerVault) : null),
+            u16(cfg.earlyExitPenaltyBps),
+            encodePenaltyDestination(cfg.penaltyDestination),
+            // Vec<RewardSource>
+            u32(cfg.rewardSources.length),
+            ...cfg.rewardSources.map(encodeRewardSource),
+            Buffer.from([encodeRewardCadence(cfg.rewardCadence)]),
+            Buffer.from([encodeRewardFormula(cfg.rewardFormula)]),
+        ]);
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.authority), isSigner: true, isWritable: true },
+                { pubkey: new PublicKey(poolPda), isSigner: false, isWritable: true },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            ],
+            data,
+        });
+    }
+    /** Build the register_reward_vault instruction (Tier 2 settlement bucket). */
+    buildRegisterRewardVaultIx(args) {
+        const mint = new PublicKey(args.mint);
+        const vaultAuthority = deriveVaultAuthority(this.programId);
+        const vault = deriveRewardVault(args.vaultId, this.programId);
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.authority), isSigner: true, isWritable: true },
+                { pubkey: mint, isSigner: false, isWritable: false },
+                { pubkey: vaultAuthority, isSigner: false, isWritable: false },
+                { pubkey: vault, isSigner: false, isWritable: true },
+                { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                { pubkey: SYSVAR_RENT_PUBKEY, isSigner: false, isWritable: false },
+            ],
+            data: Buffer.concat([IX_REGISTER_REWARD_VAULT, bsString(args.vaultId)]),
+        });
+    }
+    /** Build the register_pending_action_vault instruction (Tier 3 settlement bucket). */
+    buildRegisterPendingActionVaultIx(args) {
+        const mint = new PublicKey(args.mint);
+        const actionByte = args.actionType === 'buyback-burn' ? ACTION_TYPE_BUYBACK_BURN : ACTION_TYPE_LP_REINFORCE;
+        const vaultAuthority = deriveVaultAuthority(this.programId);
+        const vault = derivePendingActionVault(args.configId, mint, actionByte, this.programId);
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.authority), isSigner: true, isWritable: true },
+                { pubkey: mint, isSigner: false, isWritable: false },
+                { pubkey: vaultAuthority, isSigner: false, isWritable: false },
+                { pubkey: vault, isSigner: false, isWritable: true },
+                { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                { pubkey: SYSVAR_RENT_PUBKEY, isSigner: false, isWritable: false },
+            ],
+            data: Buffer.concat([
+                IX_REGISTER_PENDING_ACTION_VAULT,
+                bsString(args.configId),
+                Buffer.from([actionByte]),
+            ]),
+        });
+    }
+    /** Address of the staker-pool reward vault (Tier 2 destination for StakerPool recipients). */
+    deriveStakerPoolRewardVault(poolPda) {
+        return deriveRewardVaultForPool(new PublicKey(poolPda), this.programId).toBase58();
+    }
+    /** Address of a named distribution-vault (Tier 2 destination for DistributionVault recipients). */
+    deriveDistributionVaultAddress(vaultId) {
+        return deriveRewardVault(vaultId, this.programId).toBase58();
+    }
+    /** Address of a Tier 3 pending-action vault. */
+    derivePendingActionVaultAddress(args) {
+        const actionByte = args.actionType === 'buyback-burn' ? ACTION_TYPE_BUYBACK_BURN : ACTION_TYPE_LP_REINFORCE;
+        return derivePendingActionVault(args.configId, new PublicKey(args.mint), actionByte, this.programId).toBase58();
+    }
+    /** Vault-authority PDA — owns all program-managed token accounts. */
+    deriveVaultAuthorityAddress() {
+        return deriveVaultAuthority(this.programId).toBase58();
+    }
+    /** Pool's principal vault — where staked principal accumulates. */
+    derivePrincipalVaultAddress(poolPda) {
+        return PublicKey.findProgramAddressSync([Buffer.from('principal-vault'), new PublicKey(poolPda).toBytes()], this.programId)[0].toBase58();
+    }
+    /** Per-staker StakeVault metadata PDA. */
+    deriveStakeVaultAddress(args) {
+        return PublicKey.findProgramAddressSync([
+            Buffer.from('stake-vault'),
+            new PublicKey(args.poolPda).toBytes(),
+            new PublicKey(args.owner).toBytes(),
+        ], this.programId)[0].toBase58();
+    }
+    /** RewardDistribution PDA for a (pool, period_id) pair. */
+    deriveRewardDistributionAddress(args) {
+        const periodBytes = Buffer.alloc(4);
+        periodBytes.writeUInt32LE(args.periodId, 0);
+        return PublicKey.findProgramAddressSync([Buffer.from('reward-dist'), new PublicKey(args.poolPda).toBytes(), periodBytes], this.programId)[0].toBase58();
+    }
+    // ==========================================================================
+    // Stake-flow ix builders
+    // ==========================================================================
+    /** Build the register_pool_token_accounts ix. Permissionless; one-time per pool. */
+    buildRegisterPoolTokenAccountsIx(args) {
+        const poolKey = new PublicKey(args.poolPda);
+        const principalVault = new PublicKey(this.derivePrincipalVaultAddress(args.poolPda));
+        const rewardVault = new PublicKey(this.deriveStakerPoolRewardVault(args.poolPda));
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.payer), isSigner: true, isWritable: true },
+                { pubkey: poolKey, isSigner: false, isWritable: false },
+                { pubkey: new PublicKey(args.mint), isSigner: false, isWritable: false },
+                {
+                    pubkey: deriveVaultAuthority(this.programId),
+                    isSigner: false,
+                    isWritable: false,
+                },
+                { pubkey: principalVault, isSigner: false, isWritable: true },
+                { pubkey: rewardVault, isSigner: false, isWritable: true },
+                { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                { pubkey: SYSVAR_RENT_PUBKEY, isSigner: false, isWritable: false },
+            ],
+            data: IX_REGISTER_POOL_TOKEN_ACCOUNTS,
+        });
+    }
+    /** Build the stake ix. */
+    buildStakeIx(args) {
+        const poolKey = new PublicKey(args.poolPda);
+        const stakeVault = new PublicKey(this.deriveStakeVaultAddress({ poolPda: args.poolPda, owner: args.user }));
+        const principalVault = new PublicKey(this.derivePrincipalVaultAddress(args.poolPda));
+        const amountBuf = Buffer.alloc(8);
+        amountBuf.writeBigUInt64LE(args.amount, 0);
+        const data = Buffer.concat([
+            IX_STAKE,
+            amountBuf,
+            Buffer.from([args.lockTierIdx]),
+        ]);
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.user), isSigner: true, isWritable: true },
+                { pubkey: poolKey, isSigner: false, isWritable: true },
+                { pubkey: stakeVault, isSigner: false, isWritable: true },
+                { pubkey: principalVault, isSigner: false, isWritable: true },
+                {
+                    pubkey: new PublicKey(args.userTokenAccount),
+                    isSigner: false,
+                    isWritable: true,
+                },
+                { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            ],
+            data,
+        });
+    }
+    /** Build the unstake ix.
+     *
+     * Account requirements depend on the pool's penalty_destination:
+     *   - `Redistribute`: only `mint` is required; pass any valid mint pubkey
+     *     (constraint validates it equals pool.asset). penaltyDestinationAta
+     *     can be omitted.
+     *   - `Burn`: pass the pool's asset mint as `mint`. The program calls
+     *     `token::burn` against it, decrementing supply atomically.
+     *     penaltyDestinationAta is unused.
+     *   - `TreasuryPda`: pass `mint` AND `penaltyDestinationAta` (the
+     *     treasury PDA's ATA for the asset).
+     *
+     * `mint` must equal the pool's configured asset mint. The Anchor
+     * constraint enforces this on chain.
+     */
+    buildUnstakeIx(args) {
+        const poolKey = new PublicKey(args.poolPda);
+        const stakeVault = new PublicKey(this.deriveStakeVaultAddress({ poolPda: args.poolPda, owner: args.user }));
+        const principalVault = new PublicKey(this.derivePrincipalVaultAddress(args.poolPda));
+        const keys = [
+            { pubkey: new PublicKey(args.user), isSigner: true, isWritable: true },
+            { pubkey: poolKey, isSigner: false, isWritable: true },
+            { pubkey: stakeVault, isSigner: false, isWritable: true },
+            {
+                pubkey: deriveVaultAuthority(this.programId),
+                isSigner: false,
+                isWritable: false,
+            },
+            // mint — slot order matches programs/stake/src/lib.rs::UnstakeAccounts.
+            // Writable because token::burn (when penalty_destination is Burn)
+            // decrements the mint's supply field.
+            { pubkey: new PublicKey(args.mint), isSigner: false, isWritable: true },
+            { pubkey: principalVault, isSigner: false, isWritable: true },
+            {
+                pubkey: new PublicKey(args.userTokenAccount),
+                isSigner: false,
+                isWritable: true,
+            },
+        ];
+        // penalty_destination_ata is `Option<Account<TokenAccount>>` in Rust.
+        // When provided (TreasuryPda destination), pass the real ATA mut.
+        // When omitted (Burn / Redistribute), pass the program id as the
+        // None sentinel — Anchor recognizes this as Option::None and skips
+        // deserialization + writability checks for the slot.
+        if (args.penaltyDestinationAta) {
+            keys.push({
+                pubkey: new PublicKey(args.penaltyDestinationAta),
+                isSigner: false,
+                isWritable: true,
+            });
+        }
+        else {
+            keys.push({ pubkey: this.programId, isSigner: false, isWritable: false });
+        }
+        keys.push({ pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false });
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys,
+            data: IX_UNSTAKE,
+        });
+    }
+    /**
+     * Build the claim ix. The caller must pass RewardDistribution PDAs
+     * for every period from `last_claim_period` to `current_period - 1`
+     * inclusive in `remaining_accounts`.
+     */
+    buildClaimIx(args) {
+        const poolKey = new PublicKey(args.poolPda);
+        const stakeVault = new PublicKey(this.deriveStakeVaultAddress({ poolPda: args.poolPda, owner: args.user }));
+        const rewardVault = new PublicKey(this.deriveStakerPoolRewardVault(args.poolPda));
+        const distAccounts = args.periodIds.map((pid) => ({
+            pubkey: new PublicKey(this.deriveRewardDistributionAddress({ poolPda: args.poolPda, periodId: pid })),
+            isSigner: false,
+            isWritable: false,
+        }));
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.user), isSigner: true, isWritable: false },
+                { pubkey: poolKey, isSigner: false, isWritable: false },
+                { pubkey: stakeVault, isSigner: false, isWritable: true },
+                {
+                    pubkey: deriveVaultAuthority(this.programId),
+                    isSigner: false,
+                    isWritable: false,
+                },
+                { pubkey: rewardVault, isSigner: false, isWritable: true },
+                {
+                    pubkey: new PublicKey(args.userTokenAccount),
+                    isSigner: false,
+                    isWritable: true,
+                },
+                { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                ...distAccounts,
+            ],
+            data: IX_CLAIM,
+        });
+    }
+    /**
+     * Build the distribute_rewards ix. Permissionless trigger — anyone
+     * pays tx fees to advance the period.
+     */
+    buildDistributeRewardsIx(args) {
+        const poolKey = new PublicKey(args.poolPda);
+        const rewardVault = new PublicKey(this.deriveStakerPoolRewardVault(args.poolPda));
+        const distribution = new PublicKey(this.deriveRewardDistributionAddress({
+            poolPda: args.poolPda,
+            periodId: args.periodId,
+        }));
+        return new TransactionInstruction({
+            programId: this.programId,
+            keys: [
+                { pubkey: new PublicKey(args.payer), isSigner: true, isWritable: true },
+                { pubkey: poolKey, isSigner: false, isWritable: true },
+                { pubkey: rewardVault, isSigner: false, isWritable: false },
+                { pubkey: distribution, isSigner: false, isWritable: true },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            ],
+            data: IX_DISTRIBUTE_REWARDS,
+        });
+    }
+    // ==========================================================================
+    // Self-submitting wrappers
+    // ==========================================================================
+    async createPool(args) {
+        const signer = this.requireSigner('createPool');
+        const ix = this.buildCreatePoolIx({ ...args, authority: signer.publicKey });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        const { poolPda } = this.derivePoolPda({
+            asset: args.config.asset,
+            poolId: args.poolId ?? 0,
+        });
+        return { poolPda, txSignature };
+    }
+    async registerRewardVault(args) {
+        const signer = this.requireSigner('registerRewardVault');
+        const ix = this.buildRegisterRewardVaultIx({ ...args, authority: signer.publicKey });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        return { vaultPda: this.deriveDistributionVaultAddress(args.vaultId), txSignature };
+    }
+    async registerPendingActionVault(args) {
+        const signer = this.requireSigner('registerPendingActionVault');
+        const ix = this.buildRegisterPendingActionVaultIx({
+            ...args,
+            authority: signer.publicKey,
+        });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        return {
+            vaultPda: this.derivePendingActionVaultAddress(args),
+            txSignature,
+        };
+    }
+    /**
+     * Stake `amount` of the pool's asset for `lockTierIdx` from the
+     * configured signer. Caller must pass `userTokenAccount` (their ATA
+     * for the pool's mint) — the SDK doesn't auto-derive it because the
+     * caller may want to pre-create the ATA in the same tx.
+     */
+    async stake(args) {
+        const signer = this.requireSigner('stake');
+        const ix = this.buildStakeIx({
+            user: signer.publicKey,
+            poolPda: args.poolPda,
+            userTokenAccount: args.userTokenAccount,
+            amount: args.amount,
+            lockTierIdx: args.lockTierIdx,
+        });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        const vaultPda = this.deriveStakeVaultAddress({
+            poolPda: args.poolPda,
+            owner: signer.publicKey,
+        });
+        return { vaultPda, txSignature };
+    }
+    async unstake(args) {
+        const signer = this.requireSigner('unstake');
+        const ix = this.buildUnstakeIx({
+            user: signer.publicKey,
+            poolPda: args.poolPda,
+            mint: args.mint,
+            userTokenAccount: args.userTokenAccount,
+            penaltyDestinationAta: args.penaltyDestinationAta,
+        });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        return { txSignature };
+    }
+    async claimRewards(args) {
+        const signer = this.requireSigner('claimRewards');
+        const ix = this.buildClaimIx({
+            user: signer.publicKey,
+            poolPda: args.poolPda,
+            userTokenAccount: args.userTokenAccount,
+            periodIds: args.periodIds,
+        });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        return { txSignature };
+    }
+    async distributeRewards(args) {
+        const signer = this.requireSigner('distributeRewards');
+        const ix = this.buildDistributeRewardsIx({
+            payer: signer.publicKey,
+            poolPda: args.poolPda,
+            periodId: args.periodId,
+        });
+        const tx = new Transaction().add(ix);
+        const txSignature = await this.signAndSubmit(tx, signer);
+        return {
+            distributionPda: this.deriveRewardDistributionAddress({
+                poolPda: args.poolPda,
+                periodId: args.periodId,
+            }),
+            txSignature,
+        };
+    }
+    async signAndSubmit(tx, signer) {
+        const { blockhash } = await this.connection.getLatestBlockhash(this.commitment);
+        tx.recentBlockhash = blockhash;
+        tx.feePayer = new PublicKey(signer.publicKey);
+        const signed = (await signer.signTransaction(tx));
+        const sig = await this.connection.sendRawTransaction(signed.serialize());
+        await this.connection.confirmTransaction(sig, this.commitment);
+        return sig;
+    }
+    requireSigner(op) {
+        if (!this.signer) {
+            throw new EmblemStakeError(EmblemError.Unauthorized, `${op}() requires a signer; construct EmblemStakeClient with { signer }`);
+        }
+        return this.signer;
+    }
+}
+export function createStakeReader(opts) {
+    return new EmblemStakeClient({
+        connection: opts.connection,
+        programId: opts.programId ?? STAKE_PROGRAM_ID,
+        commitment: opts.commitment,
+    });
+}
+// ============================================================================
+// helpers
+// ============================================================================
+function bs58Encode(bytes) {
+    const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] * 256;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let result = '';
+    for (let i = 0; i < zeros; i++)
+        result += ALPHABET[0];
+    for (let i = digits.length - 1; i >= 0; i--)
+        result += ALPHABET[digits[i]];
+    return result;
+}
+//# sourceMappingURL=client.js.map