pangu-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,415 @@
+import { PublicKey, Connection, TransactionInstruction } from '@solana/web3.js';
+import { Idl } from '@anchor-lang/core';
+import { S as Sale, B as BuyerRecord, L as ListSalesOptions } from './accounts-BuD-oCcr.js';
+export { F as FeedId, P as PanguInputError, a as PanguLayoutError, b as attestationAddress, c as buyerRecordAddress, d as dbcBaseVaultAddress, e as decodeBuyerRecord, f as decodeSale, g as extraAccountListAddress, h as feedIdBytes, i as feedIdHex, j as getBuyerRecord, k as getSale, l as isSaleRunning, m as listBuyerRecords, n as listSales, p as priceFeedAddress, s as saleRulesAddress } from './accounts-BuD-oCcr.js';
+export { A as ApproveBuyerInput, C as CloseBuyerRecordInput, c as CreateSaleInput, O as OpenBuyerRecordInput, d as PANGU_ERRORS, e as PanguError, a as PanguErrorName, P as PriceBandInput, b as PriceReading, f as PriceUpdate, R as RevokeBuyerInput, g as approveBuyerInstruction, h as closeBuyerRecordInstruction, i as createSaleInstruction, j as decodePriceUpdate, k as explainPanguError, o as openBuyerRecordInstruction, p as panguErrorFromLogs, r as readPrice, l as revokeBuyerInstruction } from './feed-Zwu1irEx.js';
+export { TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
+
+/**
+ * The generated interface of the Pangu program, copied from the program's build
+ * by `npm run sync-idl`. Everything else in this package is derived from it, so
+ * a rebuilt program cannot leave a stale discriminator or error code behind.
+ */
+declare const PANGU_IDL: Idl;
+declare const PANGU_PROGRAM_ID: PublicKey;
+/** Meteora's Dynamic Bonding Curve. Source: programs/pangu/src/dbc.rs. */
+declare const DBC_PROGRAM_ID: PublicKey;
+/** The Solana Attestation Service. Source: programs/pangu/src/sas.rs. */
+declare const SAS_PROGRAM_ID: PublicKey;
+/**
+ * Pyth's price feed program. Every price feed account is a program address of
+ * this program over a shard id and a feed id, so a sale can name the address
+ * before anybody has ever refreshed it.
+ * Source: programs/pangu/src/price.rs, PRICE_FEED_PROGRAM_ID.
+ */
+declare const PYTH_PRICE_FEED_PROGRAM_ID: PublicKey;
+/**
+ * Pyth's receiver program, the only program that can write a price feed
+ * account, and only after checking the Wormhole guardians' signatures.
+ * Source: programs/pangu/src/price.rs, RECEIVER_PROGRAM_ID.
+ */
+declare const PYTH_RECEIVER_PROGRAM_ID: PublicKey;
+/**
+ * The Pyth shard Pangu refreshes. A shard is a second copy of the same feed at
+ * a second address, so a sale depends on a price Pangu's own refresher keeps
+ * fresh rather than on the sponsored one.
+ * Source: programs/pangu/src/price.rs, PANGU_SHARD_ID.
+ */
+declare const PANGU_SHARD_ID = 7700;
+
+/**
+ * The SaleRules layouts this package reads. Source: state.rs,
+ * SALE_RULES_OLDEST_READABLE_VERSION to SALE_RULES_LAYOUT_VERSION. Version 2
+ * added the paying token and the end of the offering period in what used to be
+ * spare bytes, so a version 1 account is the same size with every older field
+ * in place. An account carrying any other number was written by a different
+ * build of the program, so every field behind the version byte may sit
+ * somewhere else.
+ */
+declare const SALE_RULES_LAYOUT_VERSIONS: ReadonlySet<number>;
+declare const ACCESS_MODE: {
+    readonly open: 0;
+    readonly issuerList: 1;
+    readonly verifierCredential: 2;
+};
+type AccessMode = (typeof ACCESS_MODE)[keyof typeof ACCESS_MODE];
+/**
+ * The seed prefixes the program and its neighbours derive addresses from.
+ * Source: state.rs (sale, buyer, extra-account-metas), sas.rs (attestation),
+ * the attestation service source (credential, schema), dbc.rs (token_vault).
+ */
+declare const SEEDS: {
+    readonly sale: "sale";
+    readonly buyer: "buyer";
+    readonly extraAccountMetas: "extra-account-metas";
+    readonly attestation: "attestation";
+    readonly credential: "credential";
+    readonly schema: "schema";
+    readonly dbcTokenVault: "token_vault";
+};
+/**
+ * The limits the program itself enforces. Each one names the Rust constant or
+ * check it copies, so a change on chain has one place to land here.
+ */
+declare const LIMITS: {
+    /** price.rs MAX_BAND_BPS: half again over the live stock price. */
+    readonly maxBandBps: 5000;
+    readonly minBandBps: 1;
+    /** price.rs MAX_PRICE_AGE_SECS, and create_sale.rs check_band takes 1..=3600. */
+    readonly maxPriceAgeSecs: 3600;
+    readonly minPriceAgeSecs: 1;
+    /** price.rs MAX_CONF_BPS: ten percent, and check_band takes 1..=1000. */
+    readonly maxConfBps: 1000;
+    readonly minConfBps: 1;
+    /** price.rs MAX_DECIMALS. */
+    readonly maxDecimals: 18;
+    /** Every Pyth feed id is 32 bytes. */
+    readonly feedIdLength: 32;
+    /** A Pyth shard id is a u16, which is what the address seed holds. */
+    readonly maxShard: 65535;
+    /** u64 raw token units, the widest cap the program can hold. */
+    readonly maxCap: bigint;
+};
+/**
+ * The dollar tokens a banded sale can be paid in on `network`, in the order the
+ * program lists them. A fresh array each call, so a caller cannot change the
+ * list another caller reads.
+ *
+ * Covers the exact addresses the program checks. Does not say whether a listed
+ * stablecoin still holds its peg. Throws for any network other than "devnet" or
+ * "mainnet", because guessing a list would let a ceiling through the program
+ * then refuses.
+ */
+declare function dollarMints(network: "devnet" | "mainnet"): PublicKey[];
+
+/**
+ * Every price in this package is a dollar amount scaled by 1e18, which is the
+ * one scale the program compares on (PRICE_SCALE_DECIMALS in price.rs).
+ * Working in that scale means the band comparison never rounds twice.
+ */
+declare const DOLLAR_SCALE: bigint;
+/**
+ * A Pyth price turned into dollars scaled by 1e18, the way
+ * `stock_price_1e18` does it on chain.
+ *
+ * Pyth publishes a whole number and an exponent, and the real price is the
+ * number times ten to that exponent. A price at a finer scale than 1e18 rounds
+ * down, exactly as the program's integer division does, and a zero is what the
+ * program then refuses.
+ *
+ * Throws PanguInputError for a price that is not above zero, or an exponent no
+ * dollar price can use.
+ */
+declare function stockPriceDollars(price: bigint, exponent: number): bigint;
+/**
+ * Pyth's confidence interval as basis points of the price itself, rounded UP.
+ *
+ * Rounded up, so half a basis point of doubt counts as one and never as none.
+ * The same arithmetic as `require_confidence` in price.rs.
+ *
+ * Throws PanguInputError for a price that is not above zero.
+ */
+declare function confidenceBps(price: bigint, conf: bigint): bigint;
+/**
+ * The curve's price in dollars per whole token, scaled by 1e18 and rounded UP.
+ *
+ * `sqrtPrice` is DBC's Q64.64 square root of quote raw units per base raw unit,
+ * so the price is `(sqrtPrice / 2^64)^2` shifted by the two mints' decimals.
+ * Rounding goes up, always, matching `curve_price_ceil_1e18` in
+ * programs/pangu/src/price.rs, so a fraction of a unit can never be the reason
+ * a buy looks allowed here and is refused on chain.
+ *
+ * Throws PanguInputError for a negative square root price or for decimals past
+ * the program's own limit of 18.
+ */
+declare function curvePriceDollars(sqrtPrice: bigint, baseDecimals: number, quoteDecimals: number): bigint;
+/** The part of a sale's rules the ceiling is worked out from. */
+interface BandRules {
+    bandBps: number;
+}
+/**
+ * The highest curve price this sale allows, scaled by 1e18 and rounded DOWN.
+ *
+ * Rounding down here and up in `curvePriceDollars` is the program's own pairing
+ * (`band_ceiling_floor_1e18`): a buy that lands exactly on the ceiling passes,
+ * and nothing between the two roundings slips through.
+ *
+ * Throws PanguInputError when the sale has no band or the stock price is not
+ * above zero, which is what the program treats as an unusable price.
+ */
+declare function priceCeiling(sale: BandRules, stockPrice: bigint): bigint;
+/** The same 1e18 scaled number as dollars, for display only. */
+declare function dollars(scaled: bigint): number;
+
+/** How concentrated a sale is right now, from the records themselves. */
+interface SaleStanding {
+    /** Wallets holding more than zero net of what they sold back. */
+    buyers: number;
+    /** Everything the pool has sold, net of sells, in raw token units. */
+    totalNetBought: bigint;
+    /** The wallet holding the most, or null when nothing has been sold. */
+    largestWallet: PublicKey | null;
+    largestNetBought: bigint;
+    /** The largest wallet's share of everything sold, 0 to 1. */
+    largestShare: number;
+    /** What one wallet's cap is worth as a share of everything sold, 0 to 1 and above. */
+    capShare: number;
+    /**
+     * True once the sale's offering period has ended: from then on the hook
+     * counts nothing and the token moves freely. Always false for a sale with no
+     * end, which includes every version 1 sale.
+     */
+    offeringOver: boolean;
+}
+/**
+ * Works out how concentrated a sale is from its records.
+ *
+ * The counts come from the records, not from the rules account's own running
+ * totals, so what the app shows is the sum of the accounts a judge can open.
+ * Records belonging to another sale are refused rather than ignored: silently
+ * dropping them would understate the largest holder.
+ *
+ * `now` is the Unix second to judge the offering period against. Pass the
+ * chain's clock when you have it, because that is the clock the hook reads and
+ * a browser's can be minutes out; without it this machine's clock stands in,
+ * which can only misjudge the end within that drift.
+ */
+declare function saleStanding(sale: Sale, records: BuyerRecord[], now?: number): SaleStanding;
+
+/** A sale token's name, symbol and metadata link, as the mint itself carries them. */
+interface SaleTokenInfo {
+    name: string;
+    symbol: string;
+    uri: string;
+}
+/**
+ * The sale token's name, symbol and metadata link.
+ *
+ * DBC writes these into the Token-2022 metadata extension on the mint itself,
+ * with the mint's metadata pointer naming the mint, when the pool opens. Only
+ * that shape is read: a pointer naming some other account means the copy on the
+ * mint is not the one the token claims, so the answer is null rather than a
+ * guess. Null too when the mint does not exist, is not a Token-2022 mint, or
+ * carries no metadata.
+ *
+ * The text is whatever the issuer typed at launch and nothing checks it, so
+ * show it as a label, never trust it as an identity: two sales can carry the
+ * same name. The mint address is what identifies a sale.
+ */
+declare function saleTokenInfo(connection: Connection, mint: PublicKey): Promise<SaleTokenInfo | null>;
+/** One sale as a list page shows it. */
+interface SaleDirectoryEntry {
+    mint: PublicKey;
+    pool: PublicKey;
+    /** From the mint's metadata. Null when the mint carries none this package reads. */
+    name: string | null;
+    symbol: string | null;
+    /** True while the mint still names Pangu as its transfer hook, as `isSaleRunning`. */
+    running: boolean;
+    /**
+     * True once the curve is full, read from DBC's own record on the pool. Null
+     * when the pool the rules name cannot be read as the transfer hook pool
+     * selling this mint.
+     */
+    graduated: boolean | null;
+    /** True once the offering period has ended by the chain's clock. */
+    offeringOver: boolean;
+    hasBand: boolean;
+    accessMode: number;
+    quoteMint: PublicKey | null;
+    endsAt: number | null;
+    buyers: number;
+    issuer: PublicKey;
+    /** The full rules, with the token's decimals filled from the mint when the rules store none. */
+    sale: Sale;
+}
+/**
+ * Every Pangu sale on the chain with what a list page shows: the token's name
+ * and symbol, whether it is running, graduated or past its offering period,
+ * and the headline rules.
+ *
+ * Reads are batched: one scan for the rules (see `listSales`, whose skipping
+ * and `onSkipped` apply here unchanged), then every mint and pool plus the
+ * Clock sysvar in calls of 100 addresses. Fifty sales cost three calls. The
+ * scan and the batch are separate calls, so a sale that changes between them
+ * is shown as of two nearby moments.
+ *
+ * Nothing about one sale can stop the others being listed: a mint that cannot
+ * be read shows no name and not running, and a pool that cannot be read shows
+ * `graduated` as null. Throws only when the node refuses a call.
+ */
+declare function saleDirectory(connection: Connection, options?: ListSalesOptions): Promise<SaleDirectoryEntry[]>;
+
+/**
+ * The schema a Pangu sale is written for: one byte, named "verified".
+ *
+ * Pangu never reads an attestation's data. It reads who the attestation is
+ * about, who signed it, and when it runs out (programs/pangu/src/sas.rs), so
+ * the smallest shape the service accepts is the right one. The service checks
+ * every attestation's data against its schema's layout, which is why an
+ * attestation defaults to the one byte this layout expects.
+ */
+declare const VERIFIED_SCHEMA: {
+    readonly layout: readonly number[];
+    readonly fieldNames: readonly string[];
+    readonly attestationData: readonly number[];
+};
+interface CreateCredentialInput {
+    /** Pays the rent. May be the authority. */
+    payer: PublicKey;
+    /** Runs the credential and signs. The address is derived from it and the name. */
+    authority: PublicKey;
+    name: string;
+    /** The keys allowed to attest under this credential, one to 64 of them. */
+    signers: PublicKey[];
+}
+interface CreateSchemaInput {
+    payer: PublicKey;
+    /** The credential's authority, who alone can add a schema to it. */
+    authority: PublicKey;
+    credential: PublicKey;
+    name: string;
+    description: string;
+    /** The service's layout codes, one per field. Defaults to VERIFIED_SCHEMA. */
+    layout?: readonly number[];
+    fieldNames?: readonly string[];
+}
+interface CreateAttestationInput {
+    payer: PublicKey;
+    /** One of the credential's signers. Pangu checks it is still on the list at every buy. */
+    authorizedSigner: PublicKey;
+    credential: PublicKey;
+    schema: PublicKey;
+    /**
+     * The buyer. Used as the attestation's nonce, which is the convention Pangu
+     * requires: the hook derives the attestation address from the buying wallet
+     * and refuses an attestation about anyone else.
+     */
+    wallet: PublicKey;
+    /** Unix seconds at which the attestation runs out. Zero means it never does. */
+    expiry: number;
+    /** Bytes matching the schema's layout. Defaults to VERIFIED_SCHEMA's one byte. */
+    data?: Uint8Array | readonly number[];
+}
+/** A credential's address. Seeds "credential", the authority and the name. */
+declare function credentialAddress(authority: PublicKey, name: string): PublicKey;
+/** A schema's first version. Seeds "schema", the credential, the name and the version byte. */
+declare function schemaAddress(credential: PublicKey, name: string): PublicKey;
+/**
+ * Opens a credential on the attestation service: a named verifier with a list
+ * of keys allowed to attest under it.
+ *
+ * Throws PanguInputError for an empty or over-long name, no signers, a repeated
+ * signer, or more signers than Pangu will read. Sends nothing.
+ */
+declare function createCredentialInstruction(input: CreateCredentialInput): TransactionInstruction;
+/**
+ * Opens the first version of a schema under a credential. Only the credential's
+ * authority can send it.
+ *
+ * Throws PanguInputError for an empty or over-long name, an empty layout, a
+ * layout code outside one byte, or a field name list that does not match the
+ * layout one for one. Sends nothing.
+ */
+declare function createSchemaInstruction(input: CreateSchemaInput): TransactionInstruction;
+/**
+ * Attests one wallet under a credential and schema, with the wallet as the
+ * nonce, so the attestation lands at the one address Pangu's hook derives for
+ * that buyer.
+ *
+ * The expiry is unix seconds; zero means never. The service checks the signer
+ * is on the credential's list at this moment and never again, which is why
+ * Pangu checks it again on every buy. Throws PanguInputError for a missing key,
+ * the all zero wallet, a negative or fractional expiry, or data that is not
+ * bytes. Sends nothing.
+ */
+declare function createAttestationInstruction(input: CreateAttestationInput): TransactionInstruction;
+interface CloseAttestationInput {
+    /** Receives the attestation's rent. The verifier, when the verifier revokes. */
+    payer: PublicKey;
+    /** One of the credential's signers right now. Not necessarily the one who issued it. */
+    authorizedSigner: PublicKey;
+    credential: PublicKey;
+    schema: PublicKey;
+    /** The wallet the attestation is about, which is its nonce. */
+    wallet: PublicKey;
+}
+/**
+ * Revokes a wallet's credential by closing its attestation, the only
+ * revocation the service has. Pangu sees it at the next buy: the account is
+ * gone, so the buy is refused with CredentialInvalid.
+ *
+ * The service pays the attestation's rent to the payer, checks the signer is on
+ * the credential's list now, and refuses a tokenized attestation, which needs a
+ * different instruction. Throws PanguInputError for a missing key or the all
+ * zero wallet. Sends nothing.
+ */
+declare function closeAttestationInstruction(input: CloseAttestationInput): TransactionInstruction;
+/**
+ * Where a wallet stands with one verifier, judged the way Pangu's hook judges
+ * the attestation itself: there and in date, there and run out, or not there.
+ */
+type CredentialStanding = "valid" | "expired" | "absent";
+/** One credential a verifier has issued, as `listAttestations` reads it. */
+interface IssuedCredential {
+    /** The attestation account. */
+    address: PublicKey;
+    /** The wallet it is about, read from the nonce. */
+    wallet: PublicKey;
+    /** The key that signed it into existence. */
+    signer: PublicKey;
+    /** Unix seconds at which it runs out, or zero for never. */
+    expiry: number;
+    /**
+     * Unix seconds of the transaction that opened this attestation, or null when
+     * it was not found in the account's recent history. The service stores no
+     * date, so this comes from the transaction history.
+     */
+    created: number | null;
+    /** Judged against the chain's own clock at the time of the read. */
+    standing: Exclude<CredentialStanding, "absent">;
+}
+/**
+ * Every credential issued under one credential and schema, in no particular
+ * order, each judged against the chain's clock.
+ *
+ * One scan of the service's accounts, filtered by the node on the attestation
+ * discriminator, the credential and the schema. An attestation that does not
+ * sit at the address its own nonce derives is left out: Pangu's hook would never
+ * find it, so it approves nobody. Then, per attestation, a short read of its
+ * history for the date it was opened, so the cost grows with the list. An RPC
+ * that refuses getProgramAccounts throws rather than returning a short list.
+ */
+declare function listAttestations(connection: Connection, credential: PublicKey, schema: PublicKey): Promise<IssuedCredential[]>;
+/**
+ * Whether a wallet holds a credential from this verifier right now: valid,
+ * expired, or absent. Absent covers revoked, never issued, and anything at the
+ * address that is not a well formed attestation about this wallet.
+ *
+ * Reads the attestation and the chain's clock in one call. Not checked here:
+ * whether the key that signed it is still on the credential's list, which
+ * Pangu also checks at every buy.
+ */
+declare function credentialStatus(connection: Connection, credential: PublicKey, schema: PublicKey, wallet: PublicKey): Promise<CredentialStanding>;
+
+export { ACCESS_MODE, type AccessMode, type BandRules, BuyerRecord, type CloseAttestationInput, type CreateAttestationInput, type CreateCredentialInput, type CreateSchemaInput, type CredentialStanding, DBC_PROGRAM_ID, DOLLAR_SCALE, type IssuedCredential, LIMITS, ListSalesOptions, PANGU_IDL, PANGU_PROGRAM_ID, PANGU_SHARD_ID, PYTH_PRICE_FEED_PROGRAM_ID, PYTH_RECEIVER_PROGRAM_ID, SALE_RULES_LAYOUT_VERSIONS, SAS_PROGRAM_ID, SEEDS, Sale, type SaleDirectoryEntry, type SaleStanding, type SaleTokenInfo, VERIFIED_SCHEMA, closeAttestationInstruction, confidenceBps, createAttestationInstruction, createCredentialInstruction, createSchemaInstruction, credentialAddress, credentialStatus, curvePriceDollars, dollarMints, dollars, listAttestations, priceCeiling, saleDirectory, saleStanding, saleTokenInfo, schemaAddress, stockPriceDollars };