@star-factory/sdk-staking 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+### sdk-staking
+
+Typed client for the on-chain staking program. It mirrors PDA seeds and instruction accounts, and adds read and convenience helpers.
+
+- **Entry**: `sdk-staking/index.ts`
+- **Types**: `sdk-staking/types.ts`
+- **Peer deps**: `@coral-xyz/anchor`, `@solana/spl-token`
+
+### Install
+
+```bash
+yarn add @coral-xyz/anchor @solana/spl-token
+```
+
+### Quick start
+
+```ts
+import { AnchorProvider, BN } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+import { StakingSDK } from '.';
+
+const provider = AnchorProvider.env();
+const sdk = await StakingSDK.create(provider); // or pass custom programId
+
+// Initialize pool (authority must sign)
+await sdk.initialize(new PublicKey('...accepted_mint...'));
+
+// Stake
+await sdk.stake(new BN(1_000_000));
+
+// Unstake (starts 30-day unlock)
+await sdk.unstake(new BN(500_000));
+
+// Claim when eligible
+if (await sdk.canClaimUnstake()) {
+  await sdk.claimUnstake();
+}
+```
+
+### API
+
+```ts
+class StakingSDK {
+  constructor(program: Program<StakeProgram>, provider: AnchorProvider);
+  static create(provider: AnchorProvider, programId?: PublicKey): Promise<StakingSDK>;
+
+  // PDAs
+  getStakePoolPDA(): PDAWithBump;                    // [b"stake_pool"]
+  getUserStakePDA(user: Address): PDAWithBump;       // [b"user_stake", user]
+  getStakeVaultPDA(stakePool: Address): PDAWithBump; // [b"stake_vault", stake_pool]
+
+  // Writes
+  initialize(acceptedMint: Address, authority?: Address): Promise<TransactionSignature>;
+  stake(amount: Amount, user?: Address): Promise<TransactionSignature>;
+  unstake(amount: Amount, user?: Address): Promise<TransactionSignature>;
+  claimUnstake(user?: Address): Promise<TransactionSignature>;
+
+  // Reads
+  getStakePool(): Promise<StakePoolAccount>;
+  getUserStake(user?: Address): Promise<UserStakeAccount | null>;
+
+  // Derived helpers
+  getUserPoolShare(user?: Address): Promise<number>;         // percentage 0..100
+  canClaimUnstake(user?: Address): Promise<boolean>;
+  getTimeUntilClaim(user?: Address): Promise<number | null>; // seconds
+
+  // Events
+  onStakeEvent(cb: EventCallback<StakeEvent>): ListenerId;
+  onUnstakeEvent(cb: EventCallback<UnstakeEvent>): ListenerId;
+  onClaimUnstakeEvent(cb: EventCallback<ClaimUnstakeEvent>): ListenerId;
+  removeEventListener(listenerId: ListenerId): Promise<void>;
+}
+```
+
+### Types (subset)
+
+```ts
+type Address = web3.PublicKey;
+type Amount = BN;
+
+interface StakePoolAccount { acceptedMint: Address; totalStaked: BN }
+interface UserStakeAccount { stakedAmount: BN; pendingUnstake: BN; unlockTimestamp: BN }
+```
+
+### Behavior notes
+
+- Loads IDL from `../target/idl/stake_program.json`; use `StakingSDK.create(provider, programId)` to override address.
+- Uses `.accountsPartial(...)` (Anchor v0.29+). If needed, switch to `.accounts(...)`.
+- `getUserStake()` returns `null` if the PDA is not initialized.
+- `getUserPoolShare()` computes `(stakedAmount / totalStaked) * 100` with two-decimal precision.
+
+---
+
+## Staker Snapshot Script
+
+Creates a snapshot of all stakers for pro-rata reward distribution. Outputs CSV compatible with the airdrop script.
+
+### Usage
+
+```bash
+# From sdk-staking directory
+yarn snapshot --supply <AMOUNT> [options]
+
+# Options:
+#   --supply <amount>   Total reward tokens to distribute (whole tokens)
+#   --decimals <n>      Reward token decimals (default: 6 for USDC)
+#   --output <path>     Output CSV path (default: ./staker-snapshot.csv)
+#   --rpc <url>         RPC endpoint (default: $RPC_URL or localhost)
+```
+
+### Examples
+
+```bash
+# Distribute 1M USDC (6 decimals) to stakers
+yarn snapshot --supply 1000000 --decimals 6 --output ./usdc-rewards.csv
+
+# Distribute 500K tokens with 9 decimals on mainnet
+yarn snapshot --supply 500000 --decimals 9 --rpc https://api.mainnet-beta.solana.com
+```
+
+### Output
+
+Creates three files:
+- `staker-snapshot.csv` - `wallet,amount` format for airdrop script
+- `staker-snapshot-detailed.csv` - Full allocation details (staked amounts, percentages)
+- `staker-snapshot-summary.json` - Verification data and audit trail
+
+### Features
+
+- **100% integer arithmetic** - No floating point for token amounts
+- **Verified math** - `sum(distributed) + remainder = total_supply`
+- **Deterministic ordering** - Sorted by wallet address for reproducibility
+- **Randomized output** - CSV is shuffled so whales aren't airdropped first
+
+### Programmatic Usage
+
+```ts
+import { StakingSDK } from '@star-vault/sdk-staking';
+
+const sdk = await StakingSDK.create(provider);
+
+// Get all stakers
+const { stakers, totalStaked, activeStakers } = await sdk.getAllStakers();
+
+// Each staker has:
+// - wallet: PublicKey
+// - stakedAmount: BN
+// - pendingUnstake: BN
+// - unlockTimestamp: BN
+```
+

package/dist/cli/set-allowed-mint.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=set-allowed-mint.d.ts.map

package/dist/cli/set-allowed-mint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-allowed-mint.d.ts","sourceRoot":"","sources":["../../src/cli/set-allowed-mint.ts"],"names":[],"mappings":""}

package/dist/cli/set-allowed-mint.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const fs_1 = require("fs");
+const index_1 = require("../index");
+function getFlagValue(flag, argv) {
+    const index = argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return argv[index + 1];
+}
+function parseArgs(argv) {
+    const mint = getFlagValue('--mint', argv);
+    const programId = getFlagValue('--program-id', argv);
+    const keypair = getFlagValue('--keypair', argv);
+    const url = getFlagValue('--url', argv);
+    if (!mint) {
+        throw new Error('--mint <ADDRESS> is required');
+    }
+    return { mint, programId, keypair, url };
+}
+function expandHome(path) {
+    if (path.startsWith('~')) {
+        const home = process.env.HOME || process.env.USERPROFILE;
+        return (home ? path.replace('~', home) : path);
+    }
+    if (path.startsWith('${HOME}')) {
+        const home = process.env.HOME || process.env.USERPROFILE;
+        return (home ? path.replace('${HOME}', home) : path);
+    }
+    return path;
+}
+function loadKeypairFromFile(filePath) {
+    const expanded = expandHome(filePath);
+    if (!(0, fs_1.existsSync)(expanded)) {
+        throw new Error(`Keypair file not found: ${expanded}`);
+    }
+    const raw = (0, fs_1.readFileSync)(expanded, { encoding: 'utf-8' });
+    const secret = JSON.parse(raw);
+    return web3_js_1.Keypair.fromSecretKey(Uint8Array.from(secret));
+}
+async function createProvider(args) {
+    if (!args.keypair && !args.url) {
+        return anchor_1.AnchorProvider.env();
+    }
+    const connection = new web3_js_1.Connection(args.url ?? (0, web3_js_1.clusterApiUrl)('devnet'), {
+        commitment: 'confirmed',
+        confirmTransactionInitialTimeout: 60_000,
+    });
+    const kp = args.keypair ? loadKeypairFromFile(args.keypair) : undefined;
+    const wallet = kp ? new anchor_1.Wallet(kp) : anchor_1.AnchorProvider.env().wallet;
+    return new anchor_1.AnchorProvider(connection, wallet, {
+        commitment: 'confirmed',
+        preflightCommitment: 'confirmed',
+    });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const args = parseArgs(argv);
+    const acceptedMint = new web3_js_1.PublicKey(args.mint);
+    const programId = args.programId ? new web3_js_1.PublicKey(args.programId) : undefined;
+    const provider = await createProvider(args);
+    const sdk = await index_1.StakingSDK.create(provider, programId);
+    const { signature: sig } = await sdk.initialize({ acceptedMint });
+    // eslint-disable-next-line no-console
+    console.log('Set allowed mint via initialize:', sig);
+    // Verify and print resulting pool state
+    const pool = await sdk.getStakePool();
+    // eslint-disable-next-line no-console
+    console.log('Accepted mint:', pool.acceptedMint.toBase58());
+}
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err?.stack || err?.message || String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=set-allowed-mint.js.map

package/dist/cli/set-allowed-mint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-allowed-mint.js","sourceRoot":"","sources":["../../src/cli/set-allowed-mint.ts"],"names":[],"mappings":"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"}