@forgedevv/core 0.1.0 → 0.3.0

package/dist/jupiter-referral.d.ts

@@ -0,0 +1,334 @@
+import { PublicKey, Transaction, TransactionInstruction, type AccountInfo, type Commitment, type Connection } from '@solana/web3.js';
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
+import { type RetryOptions } from './reads.js';
+/** Jupiter referral program (mainnet-beta). */
+export declare const JUPITER_REFERRAL_PROGRAM_ID: PublicKey;
+/**
+ * Jupiter's Ultra project in the referral program (mainnet-beta). The Jupiter Plugin and Ultra
+ * `/order` only collect the referral fee into referral accounts of this project.
+ * @see https://developers.jup.ag/docs/ultra/add-fees-to-ultra.md
+ */
+export declare const JUPITER_ULTRA_REFERRAL_PROJECT: PublicKey;
+export declare const JUPITER_REFERRAL_ACCOUNT_DISCRIMINATOR: Buffer;
+export declare const JUPITER_PROJECT_DISCRIMINATOR: Buffer;
+export declare const JUPITER_CLAIM_DISCRIMINATOR: Buffer;
+export declare const JUPITER_CLAIM_V2_DISCRIMINATOR: Buffer;
+export declare const JUPITER_CREATE_ADMIN_TOKEN_ACCOUNT_DISCRIMINATOR: Buffer;
+export type JupiterReferralClaimVersion = 'v1' | 'v2';
+export type JupiterReferralErrorCode = 'wrong_cluster' | 'invalid_params' | 'referral_account_not_found' | 'not_a_referral_account' | 'project_not_found' | 'not_a_project' | 'mint_not_found' | 'not_a_mint' | 'partner_mismatch'
+/** The referral account belongs to another project than the expected one (Jupiter Ultra's). */
+ | 'project_mismatch'
+/** Funds wait in the v2 collection account, but `claim_v2` needs a named referral account. */
+ | 'referral_account_unnamed'
+/** Named, but not the PDA `["referral", project, name]` that `claim_v2` signs with. */
+ | 'referral_account_not_pda';
+export declare class JupiterReferralError extends Error {
+    readonly code: JupiterReferralErrorCode;
+    constructor(code: JupiterReferralErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface JupiterReferralAccount {
+    /** Receives the claimed fees (FORGE: the revenue wallet, D34). */
+    partner: PublicKey;
+    project: PublicKey;
+    shareBps: number;
+    name: string | null;
+}
+export interface JupiterProject {
+    base: PublicKey;
+    admin: PublicKey;
+    name: string;
+    defaultShareBps: number;
+}
+/** `ReferralAccount { partner, project, share_bps: u16, name: Option<String> }`. */
+export declare function decodeJupiterReferralAccount(data: Buffer): JupiterReferralAccount;
+/** `Project { base, admin, name: String, default_share_bps: u16 }`. */
+export declare function decodeJupiterProject(data: Buffer): JupiterProject;
+/** Classic referral token account: PDA `["referral_ata", referral account, mint]`. */
+export declare function deriveJupiterReferralTokenAccount(referralAccount: PublicKey, mint: PublicKey, programId?: PublicKey): PublicKey;
+/**
+ * Named referral account: PDA `["referral", project, name]` (`initialize_referral_account_with_name`,
+ * and the signer seeds of `claim_v2`). Throws when the name is longer than a seed (32 bytes).
+ */
+export declare function deriveJupiterReferralAccount(project: PublicKey, name: string, programId?: PublicKey): PublicKey;
+/** V2 referral token account: the associated token account of the referral account. */
+export declare function deriveJupiterReferralTokenAccountV2(referralAccount: PublicKey, mint: PublicKey, tokenProgram: PublicKey): PublicKey;
+/** Project authority: PDA `["project_authority", project.base]`. */
+export declare function deriveJupiterProjectAuthority(base: PublicKey, programId?: PublicKey): PublicKey;
+export interface JupiterClaimAccounts {
+    /** Signer, pays the network fee (and the partner token account rent, the first time). */
+    payer: PublicKey;
+    project: PublicKey;
+    admin: PublicKey;
+    projectAdminTokenAccount: PublicKey;
+    referralAccount: PublicKey;
+    referralTokenAccount: PublicKey;
+    partner: PublicKey;
+    partnerTokenAccount: PublicKey;
+    mint: PublicKey;
+    tokenProgram: PublicKey;
+}
+/**
+ * `claim` (v1) or `claim_v2`: the IDL's accounts in the IDL's order. The two differ only in the
+ * position of the program accounts at the end (v1: associated token, system, token; v2: system,
+ * token, associated token). No arguments.
+ */
+export declare function buildJupiterReferralClaimIx(accounts: JupiterClaimAccounts, version: JupiterReferralClaimVersion, programId?: PublicKey): TransactionInstruction;
+export interface JupiterCreateAdminTokenAccountAccounts {
+    project: PublicKey;
+    /** Pays the rent of the admin token account (PDA of the project). */
+    projectAuthority: PublicKey;
+    admin: PublicKey;
+    projectAdminTokenAccount: PublicKey;
+    mint: PublicKey;
+    tokenProgram: PublicKey;
+}
+/** `create_admin_token_account`: needed once per mint before the first claim of that mint. */
+export declare function buildJupiterCreateAdminTokenAccountIx(accounts: JupiterCreateAdminTokenAccountAccounts, programId?: PublicKey): TransactionInstruction;
+export interface BuildJupiterReferralClaimTxParams {
+    connection: Connection;
+    /** FORGE_JUPITER_REFERRAL_ACCOUNT (read through addresses.ts by the caller). */
+    referralAccount: PublicKey;
+    /** Currency to claim (e.g. wrapped SOL or USDC). */
+    mint: PublicKey;
+    /** Fee payer and only signer. */
+    payer: PublicKey;
+    /** When given, the referral account's partner must be this key (the revenue wallet, D34). */
+    expectedPartner?: PublicKey;
+    /**
+     * The referral account's project must be this key. Default: `JUPITER_ULTRA_REFERRAL_PROJECT`,
+     * the only project the Jupiter Plugin pays.
+     */
+    expectedProject?: PublicKey;
+    commitment?: Commitment;
+    retry?: RetryOptions;
+    programId?: PublicKey;
+    /**
+     * Priority fee read from the cluster for the claim's writable accounts, bounded by this setting
+     * (priority-fee.ts): `setComputeUnitLimit` (`JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS`) then
+     * `setComputeUnitPrice`, first. Default: none.
+     */
+    priority?: PriorityFeeSetting;
+}
+/**
+ * Compute unit limit of a Jupiter referral claim with a priority fee: up to two token account
+ * creations and two claims (each a token transfer pair), with a wide margin.
+ */
+export declare const JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS = 300000;
+export interface JupiterReferralClaimItem {
+    version: JupiterReferralClaimVersion;
+    referralTokenAccount: PublicKey;
+    /** Raw units held by that referral token account when the transaction was built. */
+    amount: bigint;
+}
+export interface JupiterReferralClaimSummary {
+    referralAccount: PublicKey;
+    partner: PublicKey;
+    partnerTokenAccount: PublicKey;
+    project: PublicKey;
+    /** The project's admin (receives the project's share) and its authority PDA (pays its rent). */
+    admin: PublicKey;
+    projectAuthority: PublicKey;
+    mint: PublicKey;
+    tokenProgram: PublicKey;
+    /** The funded referral token accounts claimed by the transaction (empty: nothing to claim). */
+    claims: JupiterReferralClaimItem[];
+    /** True when the transaction also creates the partner's token account (rent paid by `payer`). */
+    createsPartnerTokenAccount: boolean;
+    /** True when the transaction also creates the project admin's token account (program-paid). */
+    createsAdminTokenAccount: boolean;
+}
+export interface JupiterReferralClaimTx {
+    /** Unsigned legacy transaction (fee payer and blockhash set), or null when nothing is claimable. */
+    transaction: Transaction | null;
+    lastValidBlockHeight: number | null;
+    summary: JupiterReferralClaimSummary;
+    /** The priority fee (price, fee, cap), or null without a `priority` setting or transaction. */
+    priorityFee: PriorityFeeQuote | null;
+}
+/**
+ * Reads the referral account, its project, the mint and the collection accounts, and builds the
+ * claim(s) of every funded collection account of `mint` to the partner's associated token account.
+ * Mainnet-beta only (genesis hash). Returns `transaction: null` when nothing is claimable.
+ * The referral account must belong to `expectedProject` (default: Jupiter's Ultra project), and a
+ * funded v2 collection account is only claimed for a named referral PDA (typed errors otherwise).
+ */
+export declare function buildJupiterReferralClaimTx(p: BuildJupiterReferralClaimTxParams): Promise<JupiterReferralClaimTx>;
+export declare const JUPITER_INITIALIZE_REFERRAL_ACCOUNT_WITH_NAME_DISCRIMINATOR: Buffer;
+/** `ReferralAccount::LEN` = 8 + 32 + 32 + 200 + 2: what the initialization allocates. */
+export declare const JUPITER_REFERRAL_ACCOUNT_SIZE = 274;
+/** `params.name.chars().count() < 20` in the program. */
+export declare const JUPITER_REFERRAL_NAME_MAX_CHARS = 19;
+/** The name is a PDA seed: at most 32 bytes. */
+export declare const JUPITER_REFERRAL_NAME_MAX_BYTES = 32;
+/**
+ * Compute unit limit of the setup transaction with a priority fee: one Anchor account
+ * initialization and up to a few associated token account creations, with a wide margin.
+ */
+export declare const JUPITER_REFERRAL_SETUP_COMPUTE_UNITS = 150000;
+/**
+ * Checks a referral account name: 1 to 19 characters (code points, the program's rule), at most
+ * 32 UTF-8 bytes (a PDA seed), and FORGE's own restriction to printable characters without
+ * whitespace (a name goes into environment files and documentation). Returns the name.
+ * @throws JupiterReferralError `invalid_params`
+ */
+export declare function assertJupiterReferralName(name: string): string;
+/** Borsh `String`: u32 little-endian byte length, then the UTF-8 bytes. */
+export declare function encodeJupiterReferralName(name: string): Buffer;
+export interface JupiterInitializeReferralAccountWithNameAccounts {
+    /** Signer: pays the network fee and the referral account rent. */
+    payer: PublicKey;
+    /** Receives the claimed fees (FORGE: the revenue wallet, D34). Does not sign. */
+    partner: PublicKey;
+    project: PublicKey;
+    /** Must be `deriveJupiterReferralAccount(project, name)`. */
+    referralAccount: PublicKey;
+}
+/**
+ * `initialize_referral_account_with_name`: the IDL's accounts in the IDL's order, the Anchor
+ * discriminator then the Borsh-encoded `{ name }`. Refuses a referral account that is not the
+ * PDA of the project and the name, and a payer, partner, project or referral account that
+ * coincide.
+ */
+export declare function buildJupiterInitializeReferralAccountWithNameIx(accounts: JupiterInitializeReferralAccountWithNameAccounts, name: string, programId?: PublicKey): TransactionInstruction;
+export interface JupiterReferralTokenAccountV2Params {
+    /** Signer: pays the rent of the token account. */
+    payer: PublicKey;
+    referralAccount: PublicKey;
+    mint: PublicKey;
+    /** The mint's program (classic SPL Token or Token-2022). */
+    tokenProgram: PublicKey;
+}
+export interface JupiterReferralTokenAccountV2Ix {
+    /** `deriveJupiterReferralTokenAccountV2(referralAccount, mint, tokenProgram)`. */
+    tokenAccount: PublicKey;
+    instruction: TransactionInstruction;
+}
+/**
+ * The v2 collection account of `mint` (what the Jupiter Plugin pays and `claim_v2` empties): an
+ * idempotent creation of the referral account's associated token account, paid by `payer`
+ * (the SDK's `initializeReferralTokenAccountV2`). Idempotent on-chain: an existing account is
+ * left as it is.
+ */
+export declare function buildJupiterReferralTokenAccountV2Ix(p: JupiterReferralTokenAccountV2Params): JupiterReferralTokenAccountV2Ix;
+export interface JupiterReferralSetupMint {
+    mint: PublicKey;
+    tokenProgram: PublicKey;
+}
+export interface BuildJupiterReferralSetupTxParams {
+    /** Fee payer and only signer. */
+    payer: PublicKey;
+    /** The referral account's partner: the revenue wallet. */
+    partner: PublicKey;
+    /** Default: `JUPITER_ULTRA_REFERRAL_PROJECT`, the only project the Jupiter Plugin pays. */
+    project?: PublicKey;
+    name: string;
+    /** False when the referral account already exists (only token accounts are then created). */
+    createReferralAccount: boolean;
+    /** The v2 collection accounts to create (those found absent), in this order. */
+    tokenAccounts: readonly JupiterReferralSetupMint[];
+    blockhash: string;
+    lastValidBlockHeight: number;
+    /**
+     * Priority fee quote of the caller (`JUPITER_REFERRAL_SETUP_COMPUTE_UNITS`): a unit limit then
+     * a unit price are put first when its price is not 0; nothing otherwise.
+     */
+    priorityFee?: Pick<PriorityFeeQuote, 'computeUnitLimit' | 'microLamports'>;
+    programId?: PublicKey;
+}
+export interface JupiterReferralSetupTokenAccount extends JupiterReferralSetupMint {
+    tokenAccount: PublicKey;
+}
+export interface JupiterReferralSetupTx {
+    /** Unsigned legacy transaction (fee payer = payer, blockhash set). */
+    transaction: Transaction;
+    lastValidBlockHeight: number;
+    referralAccount: PublicKey;
+    project: PublicKey;
+    name: string;
+    /** The token accounts the transaction creates (same order as the input). */
+    tokenAccounts: JupiterReferralSetupTokenAccount[];
+}
+/**
+ * Unsigned transaction setting up FORGE's Jupiter referral account: the optional compute budget,
+ * `initialize_referral_account_with_name` when `createReferralAccount`, then one v2 collection
+ * account creation per `tokenAccounts` entry. Refuses an empty plan and a duplicate mint. Does
+ * not read the chain: inspect first (`readJupiterReferralSetup`). Mainnet-beta is the only
+ * cluster where the program and the Ultra project exist; the read helper enforces it.
+ */
+export declare function buildJupiterReferralSetupTx(p: BuildJupiterReferralSetupTxParams): JupiterReferralSetupTx;
+export type JupiterReferralAccountMismatch = 'not_a_referral_account' | 'partner_mismatch' | 'project_mismatch' | 'name_mismatch';
+export type JupiterReferralAccountStatus = {
+    status: 'absent';
+} | {
+    status: 'ready';
+    account: JupiterReferralAccount;
+} | {
+    status: 'mismatch';
+    reason: JupiterReferralAccountMismatch;
+    detail: string;
+};
+export interface JupiterReferralAccountExpectation {
+    partner: PublicKey;
+    project: PublicKey;
+    name: string;
+    programId?: PublicKey;
+}
+/**
+ * What the referral account address holds, against the expected one: absent, ready (a referral
+ * account of `project` with `partner` and exactly `name`), or a mismatch with its reason. The
+ * caller derives the address as the PDA of the project and the name.
+ */
+export declare function inspectJupiterReferralAccount(info: AccountInfo<Buffer> | null, expected: JupiterReferralAccountExpectation): JupiterReferralAccountStatus;
+export type JupiterReferralTokenAccountMismatch = 'not_a_token_account' | 'wrong_mint' | 'wrong_owner';
+export type JupiterReferralTokenAccountStatus = {
+    status: 'absent';
+} | {
+    status: 'ready';
+    amount: bigint;
+} | {
+    status: 'mismatch';
+    reason: JupiterReferralTokenAccountMismatch;
+    detail: string;
+};
+/**
+ * What the v2 collection account address holds: absent, a token account of `mint` owned by the
+ * referral account, or not.
+ */
+export declare function inspectJupiterReferralTokenAccountV2(address: PublicKey, info: AccountInfo<Buffer> | null, expected: {
+    referralAccount: PublicKey;
+    mint: PublicKey;
+    tokenProgram: PublicKey;
+}): JupiterReferralTokenAccountStatus;
+export interface ReadJupiterReferralSetupParams {
+    connection: Connection;
+    partner: PublicKey;
+    name: string;
+    /** The currencies whose v2 collection accounts are wanted (e.g. wrapped SOL and USDC). */
+    mints: readonly PublicKey[];
+    /** Default: `JUPITER_ULTRA_REFERRAL_PROJECT`. */
+    project?: PublicKey;
+    programId?: PublicKey;
+    commitment?: Commitment;
+    retry?: RetryOptions;
+}
+export interface JupiterReferralSetupTokenAccountState extends JupiterReferralSetupTokenAccount {
+    status: JupiterReferralTokenAccountStatus;
+}
+export interface JupiterReferralSetupState {
+    project: PublicKey;
+    /** The project as decoded on-chain (its admin and default share). */
+    projectAccount: JupiterProject;
+    name: string;
+    referralAccount: PublicKey;
+    referral: JupiterReferralAccountStatus;
+    tokenAccounts: JupiterReferralSetupTokenAccountState[];
+}
+/**
+ * Reads what the setup needs: the project (must exist and decode), the mints (their token
+ * program), the named referral account and its v2 collection accounts, each inspected. Mainnet
+ * only (`wrong_cluster` on any other cluster, before any read). The caller decides what to
+ * create (the absent ones) and refuses on any mismatch.
+ */
+export declare function readJupiterReferralSetup(p: ReadJupiterReferralSetupParams): Promise<JupiterReferralSetupState>;