@emblemvault/primitives-stake 0.1.0

package/dist/pda.js

@@ -0,0 +1,58 @@
+/**
+ * PDA derivation for the stake program.
+ *
+ * Three derivations:
+ *   StakePool:           [b"stake-pool", asset_mint, pool_id_le_u32]
+ *   StakeVault:          [b"stake-vault", pool_pda, owner]
+ *   RewardDistribution:  [b"reward-dist", pool_pda, period_id_le_u32]
+ *
+ * Mirrors sdk/sell's pattern. Rust and TS sides derive identically.
+ */
+import { PublicKey } from '@solana/web3.js';
+import { STAKE_PROGRAM_ID } from '@emblemvault/primitives-shared';
+export const STAKE_POOL_SEED = Buffer.from('stake-pool');
+export const STAKE_VAULT_SEED = Buffer.from('stake-vault');
+export const REWARD_DIST_SEED = Buffer.from('reward-dist');
+/**
+ * Stake program id — derived from `keys/stake.json` and emitted by
+ * `scripts/derive-program-ids.mjs` into `shared/src/program-ids.generated.ts`.
+ * Re-exported here so SDK consumers don't need to know about `shared`.
+ *
+ * The Rust program's `declare_id!()` is held in lockstep via Anchor's
+ * keypair-vs-source check.
+ */
+export { STAKE_PROGRAM_ID };
+export function deriveStakePoolPda(args) {
+    const assetKey = new PublicKey(args.asset);
+    const poolIdBytes = encodeU32(args.poolId, 'poolId');
+    const programKey = new PublicKey(args.programId);
+    const [pda, bump] = PublicKey.findProgramAddressSync([STAKE_POOL_SEED, assetKey.toBytes(), poolIdBytes], programKey);
+    return { pda, bump };
+}
+export function deriveStakeVaultPda(args) {
+    const poolKey = new PublicKey(args.poolPda);
+    const ownerKey = new PublicKey(args.owner);
+    const programKey = new PublicKey(args.programId);
+    const [pda, bump] = PublicKey.findProgramAddressSync([STAKE_VAULT_SEED, poolKey.toBytes(), ownerKey.toBytes()], programKey);
+    return { pda, bump };
+}
+export function deriveRewardDistPda(args) {
+    const poolKey = new PublicKey(args.poolPda);
+    const periodBytes = encodeU32(args.periodId, 'periodId');
+    const programKey = new PublicKey(args.programId);
+    const [pda, bump] = PublicKey.findProgramAddressSync([REWARD_DIST_SEED, poolKey.toBytes(), periodBytes], programKey);
+    return { pda, bump };
+}
+// ============================================================================
+// helpers
+// ============================================================================
+/** Encode a u32 as 4 little-endian bytes with a context-aware error message. */
+export function encodeU32(value, fieldName) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new RangeError(`${fieldName} must be an unsigned 32-bit integer (0..4294967295); got ${value}`);
+    }
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32LE(value, 0);
+    return buf;
+}
+//# sourceMappingURL=pda.js.map

package/dist/pda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pda.js","sourceRoot":"","sources":["../src/pda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAsB,MAAM,gCAAgC,CAAC;AAEtF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAiB5B,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC7D,MAAM,QAAQ,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,sBAAsB,CAClD,CAAC,eAAe,EAAE,QAAQ,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,EAClD,UAAU,CACX,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvB,CAAC;AAYD,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,sBAAsB,CAClD,CAAC,gBAAgB,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,EACzD,UAAU,CACX,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvB,CAAC;AAYD,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,sBAAsB,CAClD,CAAC,gBAAgB,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,EAClD,UAAU,CACX,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvB,CAAC;AAED,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,SAAiB;IACxD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,WAAW,EAAE,CAAC;QACjE,MAAM,IAAI,UAAU,CAClB,GAAG,SAAS,4DAA4D,KAAK,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Stake SDK — types.
+ *
+ * Three account types — pool config, per-user vault, per-period reward
+ * distribution bookkeeping. The pool's interior config (lock tiers, reward
+ * sources, penalty destination, reward formula) reuses the cross-primitive
+ * types in @emblemvault/primitives-shared.
+ *
+ * Per 03-build-plan.md Phase 3, this is the most stateful primitive. Phase
+ * 1+ ships the TS shape so consumers can build against the on-chain layout
+ * before programs/stake deploys.
+ */
+import type { PenaltyDestination, RewardFormula, SolanaAddress, StakeLockTier, StakePoolConfig, StakeRewardSource } from '@emblemvault/primitives-shared';
+/**
+ * The on-chain StakePoolAccount.
+ *
+ * Seeds: [b"stake-pool", asset_mint, pool_id_le_u32]
+ *
+ * The pool_id is per-(asset, authority) unique — multiple pools can stake
+ * the same asset under different rules (different lock tiers, different
+ * reward formulas, etc.).
+ */
+export interface StakePoolAccount {
+    /** Wallet that created the pool — also the authority for any future updates. */
+    authority: SolanaAddress;
+    /** Per-(asset, authority) sequential pool id. */
+    poolId: number;
+    /** Token mint that gets staked into this pool. */
+    asset: SolanaAddress;
+    /** Optional dashboard URL — surfaced by the SDK in some contexts. */
+    hostUrl: string | null;
+    /** Lock tiers, ordered from shortest to longest. Max 10 (per shared limit). */
+    lockOptions: StakeLockTier[];
+    /** Min stake amount per user (base units). */
+    minStake: bigint;
+    /** Optional max per-vault cap. null = unlimited. */
+    maxStakePerVault: bigint | null;
+    /** Penalty in bps applied to early-exit unstake. */
+    earlyExitPenaltyBps: number;
+    /** Where the penalty goes (redistribute / burn / treasury PDA). */
+    penaltyDestination: PenaltyDestination;
+    /** Reward sources funding this pool. */
+    rewardSources: StakeRewardSource[];
+    /** How often distribute_rewards is callable. */
+    rewardCadence: 'hourly' | 'daily' | 'weekly';
+    /** Reward formula identifier — "linear-v1" until sammy-curve-v1 lands. */
+    rewardFormula: RewardFormula;
+    /** Total amount currently staked across all vaults. */
+    totalStaked: bigint;
+    /** Total weighted-stake (sum of stake × multiplier across all vaults). */
+    totalWeightedStake: bigint;
+    /** Period counter — increments on each distribute_rewards. */
+    currentPeriod: number;
+    /** Monotonic version, incremented on update. */
+    version: number;
+    /** Unix-seconds at creation. */
+    createdAt: number;
+}
+export interface StakePoolView extends StakePoolAccount {
+    poolPda: SolanaAddress;
+}
+/**
+ * The on-chain StakeVaultAccount — one per (pool, owner).
+ *
+ * Seeds: [b"stake-vault", pool_pda, owner]
+ */
+export interface StakeVaultAccount {
+    /** The pool this vault belongs to. */
+    poolPda: SolanaAddress;
+    /** The wallet that owns this stake. */
+    owner: SolanaAddress;
+    /** Amount staked (base units). */
+    stakedAmount: bigint;
+    /** Index into the pool's lockOptions array. */
+    lockTierIdx: number;
+    /** Unix-seconds at which the lock ends. After this, unstake is penalty-free. */
+    lockEndsAt: number;
+    /** Accrued but-not-yet-claimed rewards (base units of asset OR reward token, depending on source). */
+    accruedRewards: bigint;
+    /** Last period this vault was credited. */
+    lastClaimPeriod: number;
+    /** Unix-seconds at last claim. */
+    lastClaimAt: number;
+    /** Unix-seconds at which the stake was first created. */
+    stakedAt: number;
+}
+export interface StakeVaultView extends StakeVaultAccount {
+    vaultPda: SolanaAddress;
+}
+/**
+ * Per-period bookkeeping. The program writes one of these on each
+ * distribute_rewards call and uses it to compute fair shares for vaults
+ * claiming during this period.
+ *
+ * Seeds: [b"reward-dist", pool_pda, period_id_le_u32]
+ */
+export interface RewardDistributionAccount {
+    /** The pool this distribution belongs to. */
+    poolPda: SolanaAddress;
+    /** Sequential period id. */
+    periodId: number;
+    /** Total reward amount distributed during this period. */
+    totalDistributed: bigint;
+    /** Snapshot of the pool's totalWeightedStake at distribute time. */
+    weightedStakeAtSnapshot: bigint;
+    /** Unix-seconds at distribution. */
+    distributedAt: number;
+    /** The reward token mint (may differ from the staked asset). */
+    rewardMint: SolanaAddress;
+}
+export interface RewardDistributionView extends RewardDistributionAccount {
+    distributionPda: SolanaAddress;
+}
+/** Args to `createPool()` — accepts the same shape as the SDK's StakePoolConfig. */
+export interface CreatePoolArgs {
+    config: StakePoolConfig;
+    /** Optional explicit pool id; if omitted, the SDK derives the next sequential value. */
+    poolId?: number;
+}
+export interface StakeArgs {
+    poolPda: SolanaAddress;
+    amount: bigint;
+    lockTierIdx: number;
+}
+export interface UnstakeArgs {
+    poolPda: SolanaAddress;
+    amount: bigint;
+}
+export interface ClaimRewardsArgs {
+    poolPda: SolanaAddress;
+}
+export interface DistributeRewardsArgs {
+    poolPda: SolanaAddress;
+}
+export interface GetVaultArgs {
+    poolPda: SolanaAddress;
+    /** Optional override; defaults to the configured signer. */
+    owner?: SolanaAddress;
+}
+/** Result of an off-chain "would this user pass a stake-mode gate?" check. */
+export interface StakeGateEvaluationResult {
+    /** True iff stakedAmount >= min AND lock is still active. */
+    granted: boolean;
+    evidence: {
+        stakedAmount: number;
+        lockEndsAt: number;
+        /** True if lock has expired — the user could unstake now without penalty. */
+        lockExpired: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Stake SDK — types.
+ *
+ * Three account types — pool config, per-user vault, per-period reward
+ * distribution bookkeeping. The pool's interior config (lock tiers, reward
+ * sources, penalty destination, reward formula) reuses the cross-primitive
+ * types in @emblemvault/primitives-shared.
+ *
+ * Per 03-build-plan.md Phase 3, this is the most stateful primitive. Phase
+ * 1+ ships the TS shape so consumers can build against the on-chain layout
+ * before programs/stake deploys.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@emblemvault/primitives-stake",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Emblem stake primitive — lock-up pools, reward vaults, multipliers, and early-exit penalties.",
+  "keywords": [
+    "emblem",
+    "emblemvault",
+    "solana",
+    "anchor",
+    "stake",
+    "staking",
+    "primitives"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@solana/spl-token": "^0.4.6",
+    "@solana/web3.js": "^1.91.0",
+    "@emblemvault/primitives-shared": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests"
+  }
+}