@reflectmoney/junior 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @reflectmoney/junior
+
+TypeScript SDK for the **Reflect Liquid Protection (RLP)** Solana program — the junior tranche of Reflect's two-tranche stablecoin protection system.
+
+Wraps Codama-generated instruction builders and provides higher-level helpers for pool lifecycle, deposits, cooldown-gated withdrawals, NAV-based slashing, and admin operations.
+
+---
+
+## Install
+
+```sh
+npm install @reflectmoney/junior @solana/kit
+```
+
+Peer expectations: a `@solana/kit` `Rpc<SolanaRpcApi>` for read paths, and a `TransactionSigner` for writes.
+
+---
+
+## Quick start
+
+```ts
+import { createSolanaRpc } from "@solana/kit";
+import { JuniorTranche, PdaClient } from "@reflectmoney/junior";
+
+const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+const juniorTranche = new JuniorTranche(rpc);
+await juniorTranche.load();
+
+// Deposit into liquidity pool 0
+const ix = await juniorTranche.deposit(
+  signer,
+  1_000_000_000n,  // amount in raw asset units
+  USDC_MINT,
+  0,               // liquidity pool id
+  null,            // minLpTokens slippage guard (null = no minimum)
+);
+```
+
+---
+
+## What this SDK covers
+
+### Pool lifecycle (admin)
+
+| Method | Notes |
+| --- | --- |
+| `initializeRlp(signer, swapFeeBps)` | One-time program bootstrap. |
+| `addAsset(signer, mint, oracle, accessLevel)` | Whitelist a deposit/swap asset. |
+| `updateOracle(signer, assetMint, newOracle)` | Rotate an asset's Pyth feed. |
+| `initializeLiquidityPool(signer, lpToken, cooldownDuration, assets, protectedVault?)` | Create a pool. `protectedVault` opts the pool into NAV-based slashing (audit-M06). |
+| `initializePoolReserve(signer, liquidityPoolId, assetMint)` | Pre-create the pool's ATA for a whitelisted asset. Idempotent. |
+| `forceRemoveAsset(signer, liquidityPoolId, assetMint)` | Recovery path for a pool reserve that has been permanently frozen by the mint authority (audit-M02). |
+| `updateDepositCap(signer, liquidityPoolId, newCap)` | Set or clear per-pool deposit cap. |
+
+### User flow
+
+| Method | Notes |
+| --- | --- |
+| `deposit(signer, amount, mint, liquidityPoolId, minLpTokens?)` | Mints LP tokens proportional to NAV. `minLpTokens` is a slippage guard. |
+| `requestWithdrawal(signer, liquidityPoolId, amount)` | Burns LP tokens and opens a per-pool cooldown account. |
+| `withdraw(signer, liquidityPoolId, cooldownId)` | Settles a matured cooldown. Excess LP tokens (if pool grew during cooldown) are refunded automatically (audit-1). |
+| `swap(signer, liquidityPoolId, tokenFrom, tokenTo, amountIn, minOut?)` | Oracle-priced rebalance between pool assets. |
+
+### Slashing (NAV-based — audit-M06)
+
+| Method | Notes |
+| --- | --- |
+| `slash(signer, liquidityPoolId, assetMint, proxyState, maxAmount)` | RLP (junior) covers losses of the senior proxy tranche. Pool must have been initialized with a `protectedVault`. The instruction computes `loss = max(0, principal + integratorsCommission − vaultValue)` from the `ProxyState` account and transfers up to `maxAmount` of `assetMint` into the proxy vault. |
+
+The legacy operator-discretion slash has been removed.
+
+### Permissions
+
+| Method | Notes |
+| --- | --- |
+| `createPermissionAccount(signer, target)` | Create a user-permissions PDA. |
+| `updateRoleHolder(signer, target, role, add)` | Grant/revoke a role for a user. |
+| `updateActionRole(signer, action, role, add)` | Bind an action (Deposit/Withdraw/Swap/Slash/etc.) to a role. **Slash cannot be assigned to `Role.PUBLIC`.** |
+
+### PDAs
+
+`PdaClient` exposes pure helpers:
+
+```ts
+const [settings]         = await PdaClient.deriveSettings();
+const [permissions]      = await PdaClient.deriveUserPermissions(user);
+const [pool]             = await PdaClient.deriveLiquidityPool(0);
+const [asset]            = await PdaClient.deriveAsset(mint);
+const [cooldown]         = await PdaClient.deriveCooldown(poolId, cooldownId);
+const [eventAuthority]   = await PdaClient.deriveEventAuthority();
+const [proxyState]       = await PdaClient.deriveProxyState(brandedMint);
+```
+
+---
+
+## Audit fixes in this release
+
+The SDK is aligned with the integrated audit-fixes branch. Notable behavioral changes that callers may need to know about:
+
+- **NAV-based slash** replaces the operator-discretion slash. Call signature is different — see above.
+- **`initializeLiquidityPool` accepts `protectedVault`.** Pass `null` for a pool that is not protecting any proxy vault. Pass the proxy state PDA otherwise.
+- **`withdraw` refunds excess LP tokens.** No caller change, but the on-chain math now redeems against the *current* NAV at withdraw time, capped by what the cooldown originally locked.
+- **`Action.Slash` is not publicly assignable.** Attempting `updateActionRole(Action.Slash, Role.PUBLIC, …)` is rejected by the program.
+- **`forceRemoveAsset` + `initializePoolReserve`** are new admin wrappers for the frozen-pool-reserve recovery path.
+- **Cooldowns are now per-pool** (a separate counter on each `LiquidityPool` rather than the program-wide settings counter).
+
+---
+
+## Development
+
+```sh
+npm install
+npm run build          # tsc → dist/
+npm test               # mocha + litesvm + the in-tree rlp.so
+```
+
+The test suite uses [LiteSVM](https://github.com/LiteSVM/litesvm) and loads `../target/deploy/rlp.so`, so make sure the program is built (`anchor build` or `cargo-build-sbf`) before running.
+
+`npm publish` runs `prepublishOnly` which cleans `dist`, rebuilds, and runs the test suite — publish will fail if any of those steps fail.

package/dist/classes/JuniorTranche.d.ts

@@ -0,0 +1,201 @@
+import { Rpc, SolanaRpcApi, Address, TransactionSigner } from "@solana/kit";
+import { type Settings, type LiquidityPool, type Asset, type Cooldown, type UserPermissions, type AccessLevel, type Action, type Role, type Update } from "../generated";
+export type AccountWithAddress<T> = {
+    data: T;
+    address: Address;
+};
+export declare class JuniorTranche {
+    private connection;
+    private settings;
+    private liquidityPools;
+    private assets;
+    constructor(connection: Rpc<SolanaRpcApi>);
+    load(): Promise<void>;
+    getSettingsData(): Promise<Settings>;
+    getLiquidityPools(): Promise<AccountWithAddress<LiquidityPool>[]>;
+    getLiquidityPoolData(liquidityPoolId: number): Promise<LiquidityPool>;
+    getAssets(): Promise<AccountWithAddress<Asset>[]>;
+    getCooldowns(): Promise<AccountWithAddress<Cooldown>[]>;
+    getCooldownsByUser(user: Address): Promise<AccountWithAddress<Cooldown>[]>;
+    getUserPermissions(): Promise<AccountWithAddress<UserPermissions>[]>;
+    getUserPermissionsFromAddress(address: Address): Promise<AccountWithAddress<UserPermissions>[]>;
+    initializeRlp(signer: TransactionSigner, swapFeeBps: number): Promise<import("../generated").InitializeRlpInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    initializeLiquidityPool(signer: TransactionSigner, args: {
+        lpTokenMint: Address;
+        cooldownDuration: number | bigint;
+        depositCap: number | bigint | null;
+        assets: number[];
+        /**
+         * Optional senior-tranche ProxyState account this pool covers.
+         * When set, the pool's `slash` flow becomes NAV-coverage-based:
+         * slashed tokens go directly into the proxy vault, capped at the
+         * proxy's current mark-to-market loss (principal + commission -
+         * vault_value). Pools with `None` are un-slashable by design.
+         */
+        protectedVault?: Address | null;
+    }): Promise<import("../generated").InitializeLpInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    /**
+     * Create the canonical pool reserve ATA for a single asset. Required after
+     * `initialize_lp` before any deposit/withdraw/swap against that asset can
+     * succeed (audit-E02). Idempotent: safe to call again on an already-
+     * initialized reserve.
+     */
+    initializePoolReserve(signer: TransactionSigner, liquidityPoolId: number, assetMint: Address): Promise<import("../generated").InitializePoolReserveInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, string, string, []>>;
+    /**
+     * Admin recovery for a permanently-frozen pool asset (audit-M02). Drops the
+     * asset from the pool's reserve list. Requires the asset's pool reserve ATA
+     * to actually be in the SPL `Frozen` state.
+     */
+    forceRemoveAsset(signer: TransactionSigner, liquidityPoolId: number, assetMint: Address): Promise<import("../generated").ForceRemoveAssetInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    addAsset(signer: TransactionSigner, assetMint: Address, oracle: Address, accessLevel: AccessLevel): Promise<import("../generated").AddAssetInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    updateOracle(signer: TransactionSigner, assetMint: Address, oracle: Address): Promise<import("../generated").UpdateOracleInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    /**
+     * NAV-based junior-tranche slash (audit-M06 redesign). Pulls from this
+     * pool's reserve of the proxy's `stablecoinMint` directly into the proxy's
+     * vault, capped on-chain at the current mark-to-market loss
+     * `principal + commission - vault_value`.
+     *
+     * The pool must have been initialized with `protectedVault` pinned to the
+     * supplied `proxyState`. The proxy's stablecoin_mint must equal the
+     * `stablecoinMint` arg, and the pool must whitelist that mint as one of
+     * its assets.
+     *
+     * @param signer            Caller (must hold the Slash action role).
+     * @param liquidityPoolId   The pool index.
+     * @param stablecoinMint    The proxy's underlying stablecoin (USDC+).
+     * @param proxyState        The senior tranche's ProxyState account.
+     * @param amount            Requested amount in raw stablecoin_mint units.
+     *                          Capped at the current gap; pass any positive
+     *                          value up to that cap.
+     */
+    slash(signer: TransactionSigner, liquidityPoolId: number, stablecoinMint: Address, proxyState: Address, amount: number | bigint): Promise<import("../generated").SlashInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    /**
+     * Inject pre-fetched state (useful for testing without an RPC connection).
+     */
+    loadFromCache(settings: Settings, liquidityPools: AccountWithAddress<LiquidityPool>[], assets: AccountWithAddress<Asset>[]): void;
+    /**
+     * Return the assets that belong to a specific liquidity pool,
+     * ordered by the pool's `assets` array.
+     */
+    private getPoolAssets;
+    /**
+     * Build the remaining accounts needed by calculate_total_pool_value().
+     * Per asset (in pool asset order): [pool_ata, asset_pda, oracle, mint]
+     */
+    private buildPoolValueRemainingAccounts;
+    /**
+     * Build the remaining accounts needed by withdraw's load_assets,
+     * load_reserves, and load_user_token_accounts.
+     *
+     * Layout (must match on-chain expectations):
+     *   - First N: asset PDAs (positional, for load_assets)
+     *   - Then N: pool reserve ATAs (searched by load_reserves)
+     *   - Then N: user token ATAs (searched by load_user_token_accounts)
+     */
+    private buildWithdrawRemainingAccounts;
+    /**
+     * Append remaining account metas to a frozen instruction object,
+     * returning a new instruction with the extra accounts.
+     */
+    private appendRemainingAccounts;
+    deposit(signer: TransactionSigner, amount: number | bigint, mint: Address, liquidityPoolId: number, minLpTokens?: number | bigint | null): Promise<import("../generated").DepositInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", string, string, string, string, string, string, string, any, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    requestWithdrawal(signer: TransactionSigner, liquidityPoolId: number, amount: number | bigint): Promise<import("../generated").RequestWithdrawalInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", string, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    withdraw(signer: TransactionSigner, liquidityPoolId: number, cooldownId: number | bigint): Promise<import("../generated").WithdrawInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    swap(signer: TransactionSigner, liquidityPoolId: number, tokenFromMint: Address, tokenToMint: Address, amountIn: number | bigint, minOut?: number | bigint | null): Promise<import("../generated").SwapInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    createPermissionAccount(caller: TransactionSigner, newAdmin: Address): Promise<import("../generated").CreatePermissionAccountInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    updateRoleHolder(admin: TransactionSigner, targetAddress: Address, role: Role, update: Update): Promise<import("../generated").UpdateRoleHolderInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    updateActionRole(admin: TransactionSigner, action: Action, role: Role, update: Update): Promise<import("../generated").UpdateActionRoleInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    updateDepositCap(signer: TransactionSigner, liquidityPoolId: number, newCap: number | bigint | null): Promise<import("../generated").UpdateDepositCapInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    freezeFunctionality(admin: TransactionSigner, action: Action, freeze: boolean): Promise<import("../generated").FreezeFunctionalityInstruction<Address<"RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz">, string, string, string, string, string, "RLptfFmhKtGLrJ9fD4o8VCHGWZZLSRrpaTKzJXdCCWz", []>>;
+    findAssetFromMint(mint: Address): Promise<Address>;
+    getSettings(): Settings;
+    getCachedLiquidityPools(): AccountWithAddress<LiquidityPool>[];
+    getCachedAssets(): AccountWithAddress<Asset>[];
+    /**
+     * Fetch and deserialize the Pyth PriceUpdateV2 oracle account for a given
+     * asset, returning `{ price, exponent }` ready to pass into
+     * `simulateDepositMath`.
+     *
+     * @param mint  The asset mint whose oracle to read, OR a direct oracle
+     *              address.  When a mint is provided the oracle address is
+     *              looked up from the cached asset list.
+     */
+    fetchOraclePrice(mintOrOracle: Address): Promise<{
+        price: bigint;
+        exponent: number;
+        publishTime: bigint;
+    }>;
+    /**
+     * Deserialize a raw Pyth PriceUpdateV2 account buffer into price fields.
+     *
+     * Borsh layout (after 8-byte Anchor discriminator):
+     *   write_authority: Pubkey (32)
+     *   verification_level: Full=[1] (1 byte) | Partial=[0,u8] (2 bytes)
+     *   price_message {
+     *     feed_id: [u8;32], price: i64, conf: u64, exponent: i32,
+     *     publish_time: i64, ...
+     *   }
+     */
+    static deserializePythPrice(data: Uint8Array): {
+        price: bigint;
+        exponent: number;
+        publishTime: bigint;
+    };
+    /**
+     * Simulate deposit math off-chain.
+     *
+     * Mirrors the on-chain logic in:
+     *   - `OraclePrice::mul`          (oracle_price.rs)
+     *   - `LiquidityPool::calculate_total_pool_value`
+     *   - `LiquidityPool::calculate_lp_tokens_on_deposit`
+     *
+     * @param depositAmount   Raw token amount to deposit (base units).
+     * @param depositAssetPrice  Oracle price of the deposit asset (`{ price, exponent }`).
+     * @param depositAssetDecimals  Decimals of the deposit token mint.
+     * @param poolReserves    Array of { balance, price, exponent, decimals } for every
+     *                        asset currently in the pool (BEFORE the deposit).
+     * @param lpTokenSupply   Current total supply of the LP token (includes dead shares).
+     * @param lpTokenDecimals Decimals of the LP token mint (typically 9).
+     * @returns               The number of LP tokens the depositor would receive (bigint).
+     */
+    static simulateDepositMath(params: {
+        depositAmount: bigint;
+        depositAssetPrice: {
+            price: bigint;
+            exponent: number;
+        };
+        depositAssetDecimals: number;
+        poolReserves: {
+            balance: bigint;
+            price: bigint;
+            exponent: number;
+            decimals: number;
+        }[];
+        lpTokenSupply: bigint;
+        lpTokenDecimals: number;
+    }): bigint;
+    /**
+     * Simulate withdrawal math off-chain.
+     *
+     * Mirrors the on-chain logic in `withdraw()` which computes:
+     *   `user_share_per_asset = reserve_amount * lp_token_amount / lp_token_supply`
+     *
+     * Uses PreciseNumber arithmetic to match on-chain rounding.
+     *
+     * @param lpTokenAmount   Amount of LP tokens the user is redeeming.
+     * @param lpTokenSupply   Current total supply of the LP token.
+     * @param reserves        Array of { mint, balance } for each pool asset.
+     * @returns               Array of { mint, amount } the user would receive per asset.
+     */
+    static simulateWithdrawMath(params: {
+        lpTokenAmount: bigint;
+        lpTokenSupply: bigint;
+        reserves: {
+            mint: Address;
+            balance: bigint;
+        }[];
+    }): {
+        mint: Address;
+        amount: bigint;
+    }[];
+}