@poise-finance/sdk

TypeScript SDK for Poise Finance — the Solana Folio / DTF protocol (tokenized multi-asset index funds). Built on @solana/kit v8 with generated Codama clients.

Builders return unsigned instructions (or a PoiseTx[] bundle). You sign and send — the same code works with a browser wallet or a keypair signer.

See docs/PROTOCOL.md for how folios, mint/redeem, roles, rebalance auctions, and fees work.

Install

npm install @poise-finance/sdk

Node 20+. Program IDs and IDLs are bundled; re-sync after a contract redeploy with yarn sync-idl (point CONTRACTS_DIR at your poise-finance checkout), then yarn generate.

Quickstart

import { generateKeyPairSigner } from "@solana/kit";
import {
  PoiseClient, createIndex, mint, getFolio, getBasket, sendBundle,
  basketDepositsFromWeights, annualPctToD18, pctToD18,
  TOKEN_2022_PROGRAM_ADDRESS,
} from "@poise-finance/sdk";

const owner = await generateKeyPairSigner();
const client = PoiseClient.fromEndpoint("http://127.0.0.1:8899", owner);

// tokenized-equity mints (see the STOCKS catalog)
const NVDAX = "Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh";
const AMDX  = "XsXcJ6GZ9kVnjqGsjBnktRcuwMBmvKWh8S93RefZ1rF";
const MU    = "MUxEsUKSMACyw5fZf68wxf5FLnZVhtU9CwH8uNNGay1";

// 1. create an index: 50% NVDAx / 30% AMDx / 20% MU, 1 share ≈ $100, seed 10 shares.
//    decimals + priceUsd are illustrative — use real values for your basket.
const deposits = basketDepositsFromWeights(
  [
    { mint: NVDAX, weightBps: 5000, decimals: 8, priceUsd: 120 },
    { mint: AMDX,  weightBps: 3000, decimals: 8, priceUsd: 150 },
    { mint: MU,    weightBps: 2000, decimals: 8, priceUsd: 110 },
  ],
  100, 10,
);

const { bundle, folioTokenMint } = await createIndex(client, {
  name: "Poise Semis", symbol: "PSEMI",
  tvlFeeAnnual: annualPctToD18(1), mintFee: pctToD18(0.3),
  auctionLength: 300n,
  basket: deposits.map((d) => ({ mint: d.mint, amount: d.amount })),
  initialShares: 10n * 1_000_000_000n,          // 10 shares, 9 decimals
  basketTokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
});
await sendBundle(client, bundle);

// 2. mint 5 more shares
const buyer = await generateKeyPairSigner();
const bc = PoiseClient.fromEndpoint("http://127.0.0.1:8899", buyer);
await sendBundle(bc, await mint(bc, {
  folioTokenMint,
  shares: 5n * 1_000_000_000n,
  minShares: 4_900_000_000n,                    // slippage floor
  basketTokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
}));

// 3. read state
const folio = await getFolio(client, folioTokenMint);
console.log(folio, await getBasket(client, folio.address));

API

Amounts are bigint (raw on-chain units); addresses are Address (base58 strings). PDA helpers are async.

| Area | Exports | |---|---| | Client | PoiseClient | | PDAs | folioPda, actorPda, folioBasketPda, userPendingBasketPda, rebalancePda, auctionPda, auctionEndsPda, daoFeeConfigPda, folioFeeConfigPda, programRegistrarPda, … | | Index lifecycle | createIndex, mint, redeem, quoteMint, quoteRedeem | | Read | getFolio, getBasket, getUserPendingBasket, getRebalance, getTotalSupply, FolioStatus | | Rebalance / auctions | startRebalance, openAuction, openAuctionPermissionless, closeAuction, bid, auctionPriceAt, quoteBid, toAuctionView | | Roles | grantRole, revokeRole, Role | | Admin | initProgramRegistrar, updateProgramRegistrar, setDaoFeeConfig, setFolioFeeConfig | | Helpers | basketDepositsFromWeights, annualPctToD18, pctToD18 | | Reference data | STOCKS, stockByTicker, SEMICONDUCTOR_INDEX | | Tx | sendBundle, computeUnitIx, appendAccounts, PoiseTx | | Constants | FOLIO_PROGRAM_ID, FOLIO_ADMIN_PROGRAM_ID, REWARDS_PROGRAM_ID, D9, D18, FOLIO_TOKEN_DECIMALS, MAX_* | | Generated clients | folioClient, folioAdminClient, rewardsClient (full Codama surface) |

Notes

• Quotes are estimates. poke may accrue fee shares between quote and execution. Always pass a slippage bound: minShares on mint, minOut on redeem, maxBuyAmount on bid.
• One token program per call. A Token-2022 basket needs basketTokenProgram: TOKEN_2022_PROGRAM_ADDRESS; a mixed basket needs separate calls.
• Multi-transaction. createIndex / mint / redeem return an ordered PoiseTx[] because large baskets exceed one transaction.
• STOCKS is a third-party reference catalog, not issued by Poise — verify mints against your target cluster.

Development

yarn install
yarn generate     # regenerate Codama clients from src/idl/*.json
yarn build
yarn test         # vitest — pure-helper unit tests

# full lifecycle against a live cluster (needs a funded ~/.config/solana/id.json):
RPC_URL=https://api.devnet.solana.com yarn smoke