mpSOL TypeScript SDK

TypeScript SDK for interacting with Metapool's mpSOL Solana leveraged staking protocol.

Official Front End

https://sol.metapool.app

Metapool Docs

https://docs.metapool.app

Features

• Stake LST tokens: Stake mSOL, bSOL, jitoSOL, or raSOL to receive mpSOL
• Unstake: Start the unstaking process by creating a delayed unstake ticket
• Withdraw: Claim LST tokens from matured tickets
• Query Functions: Get contract state, vault information, balances, and more

Installation

pnpm add mp-sol-ts-sdk

Initialization

pnpm install

Compile SDK

pnpm run build

Quick Start

import { MpSolClient } from "mp-sol-ts-sdk";
import { Connection, PublicKey } from "@solana/web3.js";
import { AnchorProvider } from "@coral-xyz/anchor";

// Create a connection
const connection = new Connection("https://api.mainnet-beta.solana.com");

// Create provider with your wallet
const provider = new AnchorProvider(connection, wallet, {
  commitment: "confirmed",
});

// Initialize the client
const client = new MpSolClient(provider);

Usage Examples

1. Get Contract Information

// Get main vault state
const mainState = await client.getMainState();
console.log("Admin:", mainState.admin.toBase58());
console.log("Unstake waiting hours:", mainState.unstakeTicketWaitingHours);
console.log("Performance fee:", mainState.performanceFeeBp, "basis points");

// Get mpSOL total supply
const supply = await client.getMpSolSupply();
console.log("mpSOL supply:", supply.value.uiAmountString);

// Get mpSOL/SOL price
const price = await client.getMpSolPrice();
console.log("mpSOL price:", price, "SOL");

// Get all vaults
const vaults = await client.getAllVaults();
for (const vault of vaults) {
  console.log("Vault mint:", vault.account.lstMint.toBase58());
  console.log("Total LST amount:", vault.account.vaultTotalLstAmount.toString());
}

// Get specific vault by LST name
const msolVault = await client.getVault("msol");
console.log("mSOL vault total:", msolVault.vaultTotalLstAmount.toString());

2. Stake LST Tokens

// Stake mSOL to receive mpSOL
const stakeResult = await client.stake(
  10, // amount: 10 mSOL
  "msol", // token: msol, bsol, jitosol, or rasol
  0 // optional referral code
);
console.log("Transaction:", stakeResult.txHash);
console.log("mpSOL received:", stakeResult.mpSolReceived.toString());

// Stake other LST tokens
await client.stake(5, "jitosol"); // Stake 5 jitoSOL
await client.stake(15, "bsol"); // Stake 15 bSOL
await client.stake(8, "rasol"); // Stake 8 raSOL

3. Fast Unstake Process

Fast unstake is different from the protocol's delayed unstake flow.

• Delayed unstake uses client.unstake(...) to create an on-chain ticket, then you wait for the protocol delay before claiming LST.
• Fast unstake swaps mpSOL directly into SOL through Jupiter routing.
• Fast unstake depends on Jupiter liquidity and route availability, so the result can include slippage and price impact.
• The SDK does not currently expose a dedicated fastUnstake(...) helper. The flow below shows how to build it in an application using the SDK's exported constants plus Jupiter APIs.

3.1 Get A Jupiter Quote

import { MpSolClient, WSOL_TOKEN_MINT } from "mp-sol-ts-sdk";

type JupiterQuoteResponse = {
  inputMint: string;
  outputMint: string;
  inAmount: string;
  outAmount: string;
  otherAmountThreshold: string;
  swapMode: string;
  slippageBps: number;
  priceImpactPct: string;
};

async function getMpSolToSolQuote(client: MpSolClient, amountLamports: string) {
  const params = new URLSearchParams({
    inputMint: client.mpSolMint.toBase58(),
    outputMint: WSOL_TOKEN_MINT,
    amount: amountLamports,
    slippageBps: "50",
    restrictIntermediateTokens: "true",
  });

  const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${params.toString()}`);
  if (!response.ok) {
    throw new Error("Failed to fetch Jupiter quote.");
  }

  return response.json() as Promise<JupiterQuoteResponse>;
}

3.2 Build And Send The Jupiter Swap

import { VersionedTransaction } from "@solana/web3.js";
import { MpSolClient } from "mp-sol-ts-sdk";

type WalletLike = {
  publicKey: { toBase58(): string };
  sendTransaction(transaction: VersionedTransaction, connection: any): Promise<string>;
};

function decodeBase64Transaction(serializedTransaction: string) {
  const binary = atob(serializedTransaction);
  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
}

async function fastUnstakeMpSol(
  client: MpSolClient,
  wallet: WalletLike,
  amountLamports: string,
) {
  const quoteResponse = await getMpSolToSolQuote(client, amountLamports);

  const response = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      quoteResponse,
      userPublicKey: wallet.publicKey.toBase58(),
      wrapAndUnwrapSol: true,
      dynamicComputeUnitLimit: true,
      prioritizationFeeLamports: "auto",
    }),
  });

  if (!response.ok) {
    throw new Error("Failed to prepare Jupiter swap transaction.");
  }

  const payload = await response.json() as { swapTransaction?: string };
  if (!payload.swapTransaction) {
    throw new Error("Jupiter did not return a swap transaction.");
  }

  const transaction = VersionedTransaction.deserialize(
    decodeBase64Transaction(payload.swapTransaction),
  );

  return wallet.sendTransaction(transaction, client.provider.connection);
}

3.3 Example Usage

// 1 mpSOL expressed in base units
const amountLamports = "1000000000";

const quote = await getMpSolToSolQuote(client, amountLamports);
console.log("Estimated SOL:", quote.outAmount);
console.log("Price impact:", quote.priceImpactPct);

const txHash = await fastUnstakeMpSol(client, wallet, amountLamports);
console.log("Swap transaction:", txHash);

4. Start Delayed Unstake Process

// Create an unstake ticket by burning mpSOL
const unstakeResult = await client.unstake(
  5 // amount: 5 mpSOL to unstake
);
console.log("Transaction:", unstakeResult.txHash);
console.log("Ticket address:", unstakeResult.ticketAccount.toBase58());
console.log("SOL value:", unstakeResult.solValue.toString());

// Check if ticket is ready to claim
const isReady = await client.isTicketReady(unstakeResult.ticketAccount);
console.log("Ticket ready:", isReady);

5. Withdraw from Ticket

// Withdraw LST tokens from a matured ticket
const withdrawResult = await client.withdraw(
  ticketAddress, // PublicKey of the ticket
  "msol", // LST token to receive
  5 // SOL value amount to withdraw
);
console.log("Transaction:", withdrawResult.txHash);
console.log("LST received:", withdrawResult.lstReceived.toString());

6. Query User Information

// Get user's mpSOL balance
const userPubkey = new PublicKey("YOUR_WALLET_ADDRESS");
const mpSolBalance = await client.getUserMpSolBalance(userPubkey);
console.log("mpSOL balance:", mpSolBalance);

// Get user's LST balance
const msolBalance = await client.getUserLstBalance(userPubkey, "msol");
console.log("mSOL balance:", msolBalance);

// Get all user tickets
const userTickets = await client.getUserTickets(userPubkey);
for (const ticket of userTickets) {
  console.log("Ticket:", ticket.publicKey.toBase58());
  console.log("SOL value:", ticket.account.solValue.toString());
  console.log("Created at:", new Date(ticket.account.createdAt.toNumber() * 1000));
}

// Get specific ticket info
const ticket = await client.getTicket(ticketAddress);
console.log("Beneficiary:", ticket.beneficiary.toBase58());
console.log("SOL value:", ticket.solValue.toString());
console.log("Created at:", ticket.createdAt.toString());

Supported LST Tokens

• mSOL: Marinade Finance staked SOL ("msol")
• bSOL: BlazeStake staked SOL ("bsol")
• jitoSOL: Jito staked SOL ("jitosol")
• raSOL: Stake Pool Hub staked SOL ("rasol")

The SDK also accepts "hubsol" as a backward-compatible alias.

API Reference

MpSolClient

Constructor

new MpSolClient(provider: AnchorProvider)

Static Methods

• fromConnectionAndWallet(connection, wallet) - Create client from connection and wallet

Query Methods

• getMainState() - Get main vault state
• getAllVaults() - Get all secondary vaults
• getVault(lstToken) - Get specific vault by LST token name
• getMpSolSupply() - Get mpSOL total supply
• getMpSolPrice() - Get mpSOL/SOL price
• getUserMpSolBalance(userPubkey) - Get user's mpSOL balance
• getUserLstBalance(userPubkey, lstToken) - Get user's LST token balance
• getTicket(ticketAddress) - Get ticket information
• getUserTickets(userPubkey) - Get all tickets for a user
• isTicketReady(ticketAddress) - Check if ticket is ready to claim

Transaction Methods

• stake(lstAmount, lstToken, refCode?) - Stake LST tokens to receive mpSOL
• unstake(mpSolAmount) - Start unstake process (create ticket)
• withdraw(ticketAddress, lstToken, solValueAmount) - Withdraw LST from ticket

Error Handling

try {
  const result = await client.stake(10, "msol");
  console.log("Success:", result.txHash);
} catch (error) {
  console.error("Stake failed:", error);
}

Development

Build the SDK:

npm run build

License

MIT

Links

• Meta Pool Website
• Documentation
• GitHub