@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

npm install @reflectmoney/junior @solana/kit

Peer expectations: a @solana/kit Rpc<SolanaRpcApi> for read paths, and a TransactionSigner for writes.

Quick start

import { address, 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)
);

JuniorTranche targets the production program by default. Pass a program address to use staging, localnet, or another deployment; all account queries, PDA derivations, permission sentinels, and instructions use the override:

const stagingProgram = address("GSEYK2FtDLywAoxn2mioXCft9FWH6Zn4VmKUArGyTVj8");
const stagingJuniorTranche = new JuniorTranche(rpc, {
  programAddress: stagingProgram,
});
await stagingJuniorTranche.load();

Low-level helpers accept the same address directly, for example PdaClient.deriveAsset(mint, stagingProgram) and generated instruction builders' { programAddress: stagingProgram } configuration.

What this SDK covers

Pool lifecycle (admin)

| Method | Notes | | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | initializeRlp(signer, swapFeeBps) | One-time program bootstrap. | | addAsset(signer, mint, accessLevel, chain) | Whitelist an asset with one to three oracle legs and an external price band. | | updateOracle(signer, assetMint, chain) | Replace and validate the complete oracle chain. | | 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:

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 [streamPrice] = await PdaClient.deriveStreamPrice(
  mint,
  chainlinkFeedIdBytes
);
const [pythPrice] = await PdaClient.derivePythPrice(pythFeedIdBytes);
const [eventAuthority] = await PdaClient.deriveEventAuthority();
const [proxyState] = await PdaClient.deriveProxyState(brandedMint);

Pull oracle keepers

The SDK accepts oracle credentials as explicit parameters. It never reads environment variables or persists secrets itself, so applications can supply credentials from their own secret manager.

Chainlink Data Streams

import {
  fetchAndBuildPostChainlinkPriceInstruction,
  type DataStreamsCredentials,
} from "@reflectmoney/junior";

const credentials: DataStreamsCredentials = {
  apiKey: process.env.STREAMS_API_KEY!,
  apiSecret: process.env.STREAMS_API_SECRET!,
  network: "testnet", // or "mainnet"
};

const { report, instruction } =
  await fetchAndBuildPostChainlinkPriceInstruction({
    signer: keeper,
    assetMint,
    feedId,
    credentials,
  });

This fetches and validates the subscribed report, Snappy-compresses it, derives the verifier accounts, derives the asset-scoped StreamPrice PDA, and builds RLP's shared postOraclePrice instruction. Use buildChainlinkStreamLeg when constructing the OracleChainConfig passed to addAsset or updateOracle.

Pyth Pull / Hermes

import {
  fetchLatestPythPriceUpdates,
  buildPostPythPriceInstruction,
} from "@reflectmoney/junior";

const update = await fetchLatestPythPriceUpdates([feedId], {
  apiKey: process.env.PYTH_API_KEY!,
  endpoint: process.env.PYTH_HERMES_URL, // optional
});

const instruction = await buildPostPythPriceInstruction({
  payer: keeper,
  assetMint,
  feedId,
  encodedVaa,
  postUpdateParams,
  treasuryId,
});

Hermes supplies the accumulator update. Posting and fully verifying its Wormhole VAA, and constructing the serialized PostUpdateParams, remains the responsibility of @pythnetwork/pyth-solana-receiver; the RLP helper builds the subsequent receiver CPI wrapper.

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).
• Withdrawal cooldowns expire one hour after maturity. Anyone may crank a live withdrawal; the owner can reclaim LP tokens after expiry with the generated reclaimCooldown builder.
• Data Streams prices are asset-scoped. Their PDA is ["stream", assetMint, feedId], preventing assets with different bounds from sharing a cache.
• Self-cancelling oracle chains are rejected. Opposite-inverse legs cannot reuse an oracle or feed.
• Deposits into slash-wiped pools are rejected until outstanding real LP supply is removed.

Development

npm install
npm run build          # tsc → dist/
npm test               # mocha + litesvm + the in-tree rlp.so

The test suite uses 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.

Stable releases publish to NPM's default latest dist-tag:

npm publish --access public