pangu-sdk 0.1.0

package/dist/dbc.d.mts

@@ -0,0 +1,505 @@
+import { PublicKey, Transaction, Keypair, Connection, AccountMeta } from '@solana/web3.js';
+import * as _meteora_ag_dynamic_bonding_curve_sdk from '@meteora-ag/dynamic-bonding-curve-sdk';
+import { TokenType, TokenAuthorityOption, CollectFeeMode, MigrationOption, BuildCurveParams, VirtualPool, PoolConfig } from '@meteora-ag/dynamic-bonding-curve-sdk';
+import { P as PriceBandInput, a as PanguErrorName, b as PriceReading } from './feed-CY-pcUU2.mjs';
+import * as _coral_xyz_anchor from '@coral-xyz/anchor';
+import { BN } from '@anchor-lang/core';
+import { S as Sale } from './accounts-BuD-oCcr.mjs';
+
+/**
+ * The settings a Pangu sale cannot work without.
+ *
+ * Token-2022 base: a transfer hook only exists on Token-2022.
+ * The hook program: Pangu itself, or no rule is ever applied.
+ * DAMM v2 migration: where a finished sale graduates to.
+ * Fees in the paying token only: C11 in the threat model. With fees collected
+ * in the sale token, a fee claim would move the sale token while the hook is
+ * live, past every cap and approval.
+ * The token authority option: C14. It decides whether DBC leaves the mint
+ * authority alive at pool creation, and a token that can still be minted is one
+ * the hook can never hold to a cap.
+ */
+declare const FORCED: {
+    readonly tokenType: TokenType.Token2022;
+    readonly tokenUpdateAuthority: TokenAuthorityOption.CreatorUpdateAuthority;
+    readonly collectFeeMode: CollectFeeMode.QuoteToken;
+    readonly migrationOption: MigrationOption.MET_DAMM_V2;
+    readonly transferHookProgram: PublicKey;
+};
+/**
+ * The caller's curve with Pangu's own settings put in.
+ *
+ * Anything else about the curve, the supply, the graduation threshold, the fee
+ * schedule, the liquidity split, is the issuer's to choose. Exported so the app
+ * can show what it will send before anybody signs.
+ *
+ * Throws PanguInputError when the caller set one of Pangu's settings to
+ * something else, or asked for a token that can still be minted.
+ */
+declare function panguCurve(curve: BuildCurveParams): BuildCurveParams;
+interface LaunchTemplateInput {
+    connection: Connection;
+    /** The partner opening the template. Pays unless a payer is given. */
+    partner: PublicKey;
+    payer?: PublicKey;
+    /** The token buyers pay in. */
+    quoteMint: PublicKey;
+    curve: BuildCurveParams;
+    /** Who may claim the partner's share of the trading fees. Defaults to partner. */
+    feeClaimer?: PublicKey;
+    /** Who receives tokens left on the curve at graduation. Defaults to partner. */
+    leftoverReceiver?: PublicKey;
+    /** DBC's badge for a paying token that needs one, such as a stock token. */
+    tokenBadge?: PublicKey;
+    /** The hook program. Only Pangu's own id is allowed. */
+    transferHookProgram?: PublicKey;
+}
+interface LaunchTemplate {
+    transaction: Transaction;
+    /** The new template's account. It signs this transaction once. */
+    config: Keypair;
+    bytes: number;
+}
+/**
+ * Builds the launch template every Pangu sale is opened from.
+ *
+ * Wraps Meteora's `createConfigWithTransferHook` and fixes the settings a Pangu
+ * sale depends on, refusing any attempt to set them otherwise. Signs and
+ * sends nothing: the partner signs the returned transaction together with the
+ * returned config keypair.
+ *
+ * Throws PanguInputError for a forced setting the caller tried to override, or
+ * for a transaction that would not fit.
+ */
+declare function launchTemplateTransaction(input: LaunchTemplateInput): Promise<LaunchTemplate>;
+
+/** The sale's rules, as the issuer chooses them. */
+interface SaleTerms {
+    /** Most raw token units one wallet may end up holding. */
+    cap?: bigint;
+    /** The same cap written as a share of what the curve sells. Use one or the other. */
+    capShareBps?: number;
+    accessMode: number;
+    /** Access mode 2 only. */
+    credential?: PublicKey;
+    schema?: PublicKey;
+    band?: PriceBandInput;
+    /** Unix seconds at which the offering ends and every rule lifts. Leave out for no end. */
+    endsAt?: number;
+}
+interface OpenSaleInput {
+    connection: Connection;
+    /** The pool's creator, who becomes the sale's issuer. Pays unless a payer is given. */
+    creator: PublicKey;
+    payer?: PublicKey;
+    config: PublicKey;
+    name: string;
+    symbol: string;
+    uri: string;
+    sale: SaleTerms;
+    /** The new token's mint. Generated when not given. It signs this transaction. */
+    baseMint?: Keypair;
+    /**
+     * DBC's badge for a paying token that needs one, such as a tokenized stock.
+     * Without it DBC refuses the pool with InvalidTokenBadge. The same badge the
+     * launch template was opened with.
+     */
+    tokenBadge?: PublicKey;
+}
+interface OpenSale {
+    transaction: Transaction;
+    baseMint: Keypair;
+    pool: PublicKey;
+    bytes: number;
+}
+/**
+ * A cap written as a share of the tokens the curve will sell before graduation.
+ *
+ * Taken from the template rather than from a number typed in, so the cap means
+ * the same thing whatever supply the issuer chose. A share of 100 percent or
+ * more is refused: create_sale answers CapCoversWholeSale for a cap at or above
+ * the curve's supply, because one wallet could then buy the whole sale.
+ */
+declare function capFromShare(swapBaseAmount: bigint, capShareBps: number): bigint;
+/**
+ * Opens the pool and the sale's rules in one transaction.
+ *
+ * C7: the rules and the hook's account list are derived from the mint, which is
+ * public the moment the pool transaction is seen. Creating them in the same
+ * transaction as the pool is what stops anyone else setting the rules for this
+ * sale. Nothing is signed or sent here, and the transaction is measured, so a
+ * sale that would not fit is refused before the creator signs.
+ *
+ * Throws PanguInputError when the template is not one Pangu opened, when the
+ * cap is given twice or not at all, or when the transaction would not fit.
+ */
+declare function openSaleTransaction(input: OpenSaleInput): Promise<OpenSale>;
+
+/** A trade, built but not signed. */
+interface TradeTransaction {
+    transaction: Transaction;
+    /** What Meteora's own quote says this trade returns, in raw units. */
+    expectedAmountOut: bigint;
+    /** The least the trade may return before it is refused, after slippage. */
+    minimumAmountOut: bigint;
+    bytes: number;
+    computeUnitLimit: number;
+}
+interface BuyInput {
+    connection: Connection;
+    buyer: PublicKey;
+    mint: PublicKey;
+    /** Raw units of the paying token to spend. */
+    amountIn: bigint;
+    slippageBps?: number;
+    /**
+     * How to handle a curve with less left than this buy asks for.
+     *
+     * "exactIn", the default, spends the whole amount or the trade is refused.
+     * "partial" lets DBC take what the curve can still absorb and leave the rest
+     * in the buyer's account. The last buy of a sale needs "partial": the tokens
+     * run out before the paying side does, and an exact-in swap is refused.
+     */
+    fill?: "exactIn" | "partial";
+    /**
+     * The fewest sale tokens, in raw units, the buy may return before the chain
+     * refuses it. Set it from the quote the buyer was shown, less their slippage,
+     * so the floor is what they agreed to and not a fresh quote taken at build
+     * time. When given it replaces `slippageBps`, and the build throws if its own
+     * fresh quote already returns less.
+     */
+    minimumAmountOut?: bigint;
+}
+interface SellInput {
+    connection: Connection;
+    seller: PublicKey;
+    mint: PublicKey;
+    /** Raw units of the sale token to sell back to the pool. */
+    amountIn: bigint;
+    slippageBps?: number;
+    /**
+     * The fewest paying tokens, in raw units, the sell may return before the
+     * chain refuses it. The same rule as `minimumAmountOut` on a buy.
+     */
+    minimumQuoteOut?: bigint;
+}
+/**
+ * Buys into a sale: the buyer's paying token in, the sale token out.
+ *
+ * Everything the hook needs travels with it. The paying token account is opened
+ * if missing, wrapped SOL is funded, the buyer's record is opened when this is
+ * their first buy, and the hook's accounts come from the sale's own published
+ * list, so a credential sale and a banded sale carry their extra accounts
+ * without the caller knowing they exist. Nothing is signed or sent.
+ *
+ * Throws PanguInputError for a mint with no Pangu sale, an amount of zero, a
+ * transaction that would not fit, or a `minimumAmountOut` the market has
+ * already moved past.
+ */
+declare function buyTransaction(input: BuyInput): Promise<TradeTransaction>;
+/**
+ * Sells back to the pool: the sale token in, the paying token out.
+ *
+ * The exit reads nothing that can be missing, which is C5 in the threat model,
+ * so a seller who is no longer approved, or whose sale's price feed has gone
+ * stale, still gets out. That includes a sale whose rules this package cannot
+ * read, because an older build wrote them: the program lets that sell through,
+ * so the pool is found from the mint instead and the sell is built all the
+ * same. Nothing is signed or sent.
+ *
+ * Throws PanguInputError when no transfer hook pool sells the mint, for an
+ * amount of zero, for a transaction that would not fit, or for a
+ * `minimumQuoteOut` the market has already moved past.
+ */
+declare function sellTransaction(input: SellInput): Promise<TradeTransaction>;
+
+/** What the chain says about a buy that has not been signed yet. */
+interface BuyPreflight {
+    ok: boolean;
+    /** The program's own refusal this buy would hit, or null when it would pass. */
+    error: PanguErrorName | null;
+    /** One sentence a buyer can read. Null when the buy would pass. */
+    reason: string | null;
+    /** Raw token units this wallet may still buy before the cap stops it. */
+    capRoom: bigint;
+    /** Where this buy would leave the curve, in dollars scaled by 1e18. */
+    curvePrice: bigint | null;
+    /** The highest curve price the band allows right now, same scale. */
+    ceiling: bigint | null;
+    /** The sale's live stock price, when it has a band. */
+    price: PriceReading | null;
+    /**
+     * True when the wallet has no record yet and the caller said the buy opens
+     * one in the same transaction, so every answer above assumes a fresh record:
+     * unapproved, nothing bought. `buyTransaction` always does that.
+     */
+    recordOpensInThisBuy: boolean;
+}
+interface PreflightBuyInput {
+    connection: Connection;
+    buyer: PublicKey;
+    mint: PublicKey;
+    /** Raw units of the sale token the buyer wants to end up with. */
+    amountOut: bigint;
+    /**
+     * Set when the buy will open the wallet's record in the same transaction, as
+     * `buyTransaction` does on a first buy. A missing record is then judged as
+     * the fresh one that transaction creates instead of being refused, so a first
+     * buyer gets the band and the cap answers. Off by default, which refuses a
+     * missing record with BuyerRecordMissing as the hook would on its own.
+     */
+    openingRecord?: boolean;
+}
+/**
+ * Says whether a buy would be refused, and why, before anything is signed.
+ *
+ * Runs the hook's own checks in the hook's own order against live chain state:
+ * the record, the approval or the credential, the price band, then the cap.
+ * The order is the hook's and not a tidier one, because a buy that breaks two
+ * rules at once has to be given the same refusal here that the chain would
+ * give it, and handle_execute judges the band before the cap.
+ *
+ * In mode 2 the attestation and the credential's list of authorized signers are
+ * decoded here the way the hook decodes them, so a wallet is told whether its
+ * approval is missing, out of date, or signed by a key the verifier has since
+ * dropped. The answer is one of the program's error names with its plain
+ * sentence, so the app can say the same thing before and after a refusal.
+ *
+ * With `openingRecord` a wallet with no record is judged as the record the buy
+ * opens would leave it: not approved, nothing bought, so an issuer-list sale
+ * still answers NotApproved and every other sale goes on to the band and the
+ * cap with the whole cap as room.
+ *
+ * What it cannot see: the Wormhole guardian signatures behind the price, which
+ * only Pyth's receiver program can check, and anything that changes between
+ * this read and the buy landing. A "pass" here is the state now, not a promise.
+ *
+ * Throws PanguInputError for a mint with no Pangu sale.
+ */
+declare function preflightBuy(input: PreflightBuyInput): Promise<BuyPreflight>;
+
+/** Everything a claim leaves the caller with. */
+interface ClaimFees {
+    transaction: Transaction;
+    /** Who the fees go to, read from the pool and its template, not passed in. */
+    claimer: PublicKey;
+    bytes: number;
+    computeUnitLimit: number;
+}
+interface ClaimFeesInput {
+    connection: Connection;
+    who: "partner" | "creator";
+    mint: PublicKey;
+}
+/**
+ * Claims the trading fees of a sale that is still running.
+ *
+ * Meteora's own `claimPartnerTradingFee` calls the older instruction, which
+ * refuses a transfer hook pool with `PoolTypeMismatch`. This builds the hook
+ * aware pair, `claim_trading_fee2` and `claim_creator_trading_fee2`, with the
+ * hook's accounts attached. See finding 2 in docs/measurements/fork-test.md.
+ *
+ * The claimer is read off the chain: the partner is the template's fee claimer
+ * and the creator is the pool's creator, so no address a caller typed in can
+ * receive this money. The sale's fees are collected in the paying token only
+ * (C11), so no sale token moves here.
+ *
+ * Throws PanguInputError for a mint with no Pangu sale.
+ */
+declare function claimFeesTransaction(input: ClaimFeesInput): Promise<ClaimFees>;
+
+/** How far a sale has got, in the numbers a judge or a buyer reads. */
+interface SaleProgress {
+    /** Raw units of the paying token the curve has taken in. */
+    quoteRaised: bigint;
+    /** What it has to reach before the sale graduates. */
+    threshold: bigint;
+    /** Between 0 and 1. */
+    percent: number;
+    /** True once the curve is full, whether or not anybody has migrated it yet. */
+    graduated: boolean;
+    /** The DAMM v2 pool, once migration has created it. */
+    dammPool: PublicKey | null;
+}
+interface GraduateInput {
+    connection: Connection;
+    /** Anyone may pay for this. It is permissionless. */
+    payer: PublicKey;
+    mint: PublicKey;
+}
+interface Graduate {
+    transaction: Transaction;
+    /** The two position accounts migration creates. Both sign this transaction. */
+    signers: Keypair[];
+    /** Where the liquidity lands. */
+    dammPool: PublicKey;
+    bytes: number;
+}
+/**
+ * Migrates a full curve into DAMM v2.
+ *
+ * Permissionless: anyone can send it, and the sale's own creator gets the
+ * locked liquidity whoever pays. No compute budget instruction is added, on
+ * purpose: migration measured 153,633 units against the 200,000 a single
+ * instruction gets by default, and the transaction is already 1,139 bytes.
+ *
+ * Throws PanguInputError when the curve is not full yet or has already been
+ * migrated.
+ */
+declare function graduateTransaction(input: GraduateInput): Promise<Graduate>;
+/**
+ * How far this sale has got, read from the pool and its template.
+ *
+ * `graduated` is the curve being full, which is the moment DBC takes the hook
+ * off the mint. `dammPool` stays null until somebody sends the migration, so
+ * the two questions the app asks, "is the sale over" and "where does it trade
+ * now", are answered separately.
+ *
+ * Throws PanguInputError for a mint with no Pangu sale.
+ */
+declare function saleProgress(connection: Connection, mint: PublicKey): Promise<SaleProgress>;
+
+/**
+ * A token account this transaction creates before the swap runs.
+ *
+ * Pangu derives a buyer's record from the owner field inside the receiving
+ * token account, so resolving the hook's accounts means reading that account.
+ * On a first buy it does not exist yet, and the chain cannot answer for it. The
+ * owner is not a guess though: the same transaction creates the account, so the
+ * bytes are filled in here from what is about to be written.
+ */
+interface PendingTokenAccount {
+    address: PublicKey;
+    mint: PublicKey;
+    owner: PublicKey;
+}
+interface HookAccountsInput {
+    connection: Connection;
+    mint: PublicKey;
+    /** The token account the sale token leaves. */
+    source: PublicKey;
+    /** The token account the sale token lands in. */
+    destination: PublicKey;
+    /** Whoever signs for the source account. */
+    authority: PublicKey;
+    amount: bigint;
+    pending?: PendingTokenAccount[];
+}
+/**
+ * The accounts Pangu's hook has to be called with, read from the list the
+ * program itself published on chain.
+ *
+ * Nothing here is a copy of what the program writes. The list is fetched, each
+ * entry is resolved against the real token accounts of this transfer, and the
+ * caller gets whatever that sale needs: a plain sale's four, a credential
+ * sale's seven, a banded sale's eleven. The Meteora SDK's own helper cannot do
+ * this because it resolves against placeholder accounts, and a record derived
+ * from the receiver's owner has nothing to read there. See finding 1 in
+ * docs/measurements/fork-test.md.
+ *
+ * Order matters and is the one Token-2022 rebuilds on chain: the published list
+ * itself, then its entries, then the hook program.
+ *
+ * Throws PanguInputError when the mint has no published list, which means it is
+ * not a Pangu sale.
+ */
+declare function hookAccounts(input: HookAccountsInput): Promise<AccountMeta[]>;
+/** DBC has to be told how many of the remaining accounts belong to the hook. */
+declare function hookAccountsInfo(accounts: AccountMeta[]): {
+    slices: {
+        accountsType: {
+            readonly transferHookBase: {};
+        };
+        length: number;
+    }[];
+};
+
+/** DBC's pool authority. Every pool vault is owned by it. */
+declare const DBC_POOL_AUTHORITY: PublicKey;
+/** The pool and its launch template: what a trade needs, whatever the rules say. */
+interface PoolMarket {
+    pool: PublicKey;
+    /** The account as DBC's own quote functions want it, with `.poolState` inside. */
+    poolAccount: VirtualPool;
+    config: PublicKey;
+    configState: PoolConfig;
+    baseMint: PublicKey;
+    quoteMint: PublicKey;
+    baseVault: PublicKey;
+    quoteVault: PublicKey;
+    /** The token program the paying token belongs to, SPL or Token-2022. */
+    quoteProgram: PublicKey;
+    /** The unit DBC counts the fee schedule in, a slot or a Unix second. */
+    currentPoint: BN;
+}
+/** Everything a Pangu action needs to know about one live DBC pool. */
+interface PoolView extends PoolMarket {
+    sale: Sale;
+}
+/**
+ * What a sell needs. The rules are there when this package can read them and
+ * null when it cannot, because a sell never depends on them.
+ */
+interface SellView extends PoolMarket {
+    sale: Sale | null;
+}
+declare function dbcProgram(connection: Connection): _coral_xyz_anchor.Program<_meteora_ag_dynamic_bonding_curve_sdk.DynamicBondingCurveTypes>;
+/** The sale's rules, refusing a mint that never had a Pangu sale. */
+declare function requireSale(connection: Connection, mint: PublicKey): Promise<Sale>;
+/**
+ * Reads the pool and its launch template in one go, for a buy or anything else
+ * that acts on the sale's rules.
+ *
+ * Everything downstream comes from these two accounts rather than from the
+ * caller, so a wrong vault or a wrong paying token cannot be passed in.
+ *
+ * Refuses a mint whose rules this package cannot read, because a buy is judged
+ * against them. Refuses a pool whose fee schedule needs the instructions sysvar
+ * as its first remaining account: a rate limiter, or the first-swap minimum fee.
+ * Pangu's hook accounts are the remaining accounts of every swap, and there is
+ * no room for a second thing in that list.
+ */
+declare function loadPool(connection: Connection, mint: PublicKey): Promise<PoolView>;
+/**
+ * Reads the pool and its launch template for a sell, which never needs the
+ * sale's rules.
+ *
+ * On chain a sell goes through whatever the rules account holds, including rules
+ * written by an older build or rules that are missing (C5). This is the same
+ * promise on the client side: the rules are read when they can be, and when
+ * they cannot, the pool is found by the mint it sells, straight from DBC, and
+ * the sell is built anyway. The hook's own accounts are still resolved from the
+ * list the program published, so nothing about the hook is guessed.
+ *
+ * Throws PanguInputError when no transfer hook pool sells this mint, when more
+ * than one does, or for the same template refusal as `loadPool`.
+ */
+declare function loadSellPool(connection: Connection, mint: PublicKey): Promise<SellView>;
+
+/** One Solana transaction, signatures included. */
+declare const TRANSACTION_SIZE_LIMIT = 1232;
+/**
+ * The compute limits this package asks for, each set from what the same action
+ * really used on a fork of mainnet. The measurements are in
+ * docs/measurements/fork-test.md. Roughly double the measured cost, because a
+ * banded or credential sale reads more accounts than the plain one that was
+ * measured, and running out of compute would look to a buyer like a refusal.
+ */
+declare const COMPUTE_LIMIT: {
+    /** Measured: 113,000 to 130,000 units for a buy, 83,000 for a sell. */
+    readonly swap: 300000;
+    /** Measured: 55,192 for the partner claim, 51,742 for the creator claim. */
+    readonly claim: 150000;
+};
+/**
+ * How many bytes this transaction will take on the wire.
+ *
+ * `serialize()` throws once a transaction passes the limit, and the point of
+ * measuring is to find out whether it does, so the size is worked out from the
+ * compiled message instead. The fee payer and a blockhash must already be set.
+ */
+declare function transactionBytes(transaction: Transaction): number;
+/** Refuses a transaction that could never be sent, with the action named. */
+declare function requireOneTransaction(transaction: Transaction, action: string): number;
+
+export { type BuyInput, type BuyPreflight, COMPUTE_LIMIT, type ClaimFees, type ClaimFeesInput, DBC_POOL_AUTHORITY, FORCED, type Graduate, type GraduateInput, type HookAccountsInput, type LaunchTemplate, type LaunchTemplateInput, type OpenSale, type OpenSaleInput, type PendingTokenAccount, type PoolMarket, type PoolView, type PreflightBuyInput, type SaleProgress, type SaleTerms, type SellInput, type SellView, TRANSACTION_SIZE_LIMIT, type TradeTransaction, buyTransaction, capFromShare, claimFeesTransaction, dbcProgram, graduateTransaction, hookAccounts, hookAccountsInfo, launchTemplateTransaction, loadPool, loadSellPool, openSaleTransaction, panguCurve, preflightBuy, requireOneTransaction, requireSale, saleProgress, sellTransaction, transactionBytes };