@forgedevv/core 0.2.0 → 0.3.1

package/dist/jupiter-referral.js

@@ -1,13 +1,14 @@
 /**
  * Jupiter referral fee claim (docs/METEORA.md "The platform fee", after graduation; D7, D8).
  *
- * After a coin graduates, trades go through Jupiter and FORGE's 30 bps integrator fee is collected
+ * After a coin graduates, trades go through Jupiter and FORGE's 50 bps integrator fee is collected
  * by the Jupiter referral program into token accounts of FORGE's referral account
  * (`FORGE_JUPITER_REFERRAL_ACCOUNT`), one per currency Jupiter collects in. Claiming is
  * permissionless: it moves a token account's balance to the referral account's `partner` (the
- * owner of the referral account: the FORGE multisig vault), minus the project's share, so the
- * fees reach the treasury and feed the buyback (D8). The fee payer only pays the network fee and,
- * the first time, the rent of the partner's token account.
+ * owner of the referral account: the FORGE revenue wallet since D34), minus the project's share.
+ * The revenue job of the signer then converts the balances to SOL and forwards them to the vault,
+ * which feeds the buyback (D8). The fee payer only pays the network fee and, the first time, the
+ * rent of the partner's token account.
  *
  * Built from the referral program's IDL (program `REFER4ZgmyYx9c6He5XfaTMiGfdLwRnkV4RPp9t9iF3`,
  * `@jup-ag/referral-sdk` 0.3.0) with raw instructions: the SDK pulls Anchor, too heavy for the
@@ -16,23 +17,45 @@
  * - `claimV2`: the associated token account of the referral account (classic or Token-2022).
  * Account order, PDA seeds and Anchor discriminators are the IDL's; the unit tests pin them.
  *
+ * The Jupiter Plugin (Ultra) only pays referral accounts of Jupiter's Ultra project
+ * (`JUPITER_ULTRA_REFERRAL_PROJECT`), into their v2 collection accounts. `claim_v2` only accepts a
+ * NAMED referral account at the PDA `["referral", project, name]` (created with
+ * `initialize_referral_account_with_name`): an unnamed one (plain `initialize_referral_account`)
+ * can never claim them. So the builder refuses a referral account of another project
+ * (`project_mismatch`; `expectedProject` overrides the Ultra project), and builds a v2 claim only
+ * for a named PDA (`referral_account_unnamed` or `referral_account_not_pda` otherwise).
+ *
  * Mainnet only: the referral program and Jupiter's fee collection live on mainnet-beta. The
- * builder checks the connection's genesis hash and refuses any other cluster (`wrong_cluster`).
- * The partner can be asserted (`expectedPartner` = the vault): a referral account owned by
- * anyone else is refused (`partner_mismatch`), fees would not reach the treasury.
+ * builder checks the connection's genesis hash and refuses any other cluster (`wrong_cluster`)
+ * before it reads any account, so the project and name checks never run on devnet (where neither
+ * the Ultra project nor Jupiter's fee collection exist): the devnet behaviour is unchanged.
+ * The partner can be asserted (`expectedPartner` = the revenue wallet): a referral account owned by
+ * anyone else is refused (`partner_mismatch`), fees would not reach the revenue wallet.
+ *
+ * The last section builds the one-off SETUP of that referral account (the signer's
+ * `--setup-revenue-referrals` command): `initialize_referral_account_with_name` under the Ultra
+ * project with the revenue wallet as partner, and the v2 collection accounts of the currencies
+ * Jupiter collects in. Only the payer signs; the program facts are listed there.
  */
-import { createHash } from 'node:crypto';
+import { sha256 } from '@noble/hashes/sha2';
 import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, createAssociatedTokenAccountIdempotentInstruction, getAssociatedTokenAddressSync, unpackAccount, } from '@solana/spl-token';
 import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from '@solana/web3.js';
 import { PaymentError, assertCluster } from './payments.js';
+import { estimatePriorityFee, priorityFeeInstructions, resolvePriorityFeePolicy, writableAccountsOf, } from './priority-fee.js';
 import { retryRpc } from './reads.js';
 // ---------------------------------------------------------------------------------------------
 // Constants (IDL)
 // ---------------------------------------------------------------------------------------------
 /** Jupiter referral program (mainnet-beta). */
 export const JUPITER_REFERRAL_PROGRAM_ID = new PublicKey('REFER4ZgmyYx9c6He5XfaTMiGfdLwRnkV4RPp9t9iF3');
+/**
+ * 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 const JUPITER_ULTRA_REFERRAL_PROJECT = new PublicKey('DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc');
 function anchorDiscriminator(name) {
-    return createHash('sha256').update(name).digest().subarray(0, 8);
+    return Buffer.from(sha256(new TextEncoder().encode(name))).subarray(0, 8);
 }
 export const JUPITER_REFERRAL_ACCOUNT_DISCRIMINATOR = anchorDiscriminator('account:ReferralAccount');
 export const JUPITER_PROJECT_DISCRIMINATOR = anchorDiscriminator('account:Project');
@@ -112,6 +135,13 @@ export function decodeJupiterProject(data) {
 export function deriveJupiterReferralTokenAccount(referralAccount, mint, programId = JUPITER_REFERRAL_PROGRAM_ID) {
     return PublicKey.findProgramAddressSync([Buffer.from('referral_ata', 'utf8'), referralAccount.toBuffer(), mint.toBuffer()], programId)[0];
 }
+/**
+ * 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 function deriveJupiterReferralAccount(project, name, programId = JUPITER_REFERRAL_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from('referral', 'utf8'), project.toBuffer(), Buffer.from(name, 'utf8')], programId)[0];
+}
 /** V2 referral token account: the associated token account of the referral account. */
 export function deriveJupiterReferralTokenAccountV2(referralAccount, mint, tokenProgram) {
     return getAssociatedTokenAddressSync(mint, referralAccount, true, tokenProgram);
@@ -175,6 +205,11 @@ export function buildJupiterCreateAdminTokenAccountIx(accounts, programId = JUPI
         data: Buffer.from(JUPITER_CREATE_ADMIN_TOKEN_ACCOUNT_DISCRIMINATOR),
     });
 }
+/**
+ * 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 const JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS = 300_000;
 function tokenAmount(address, info, tokenProgram) {
     if (!info || !info.owner.equals(tokenProgram))
         return 0n;
@@ -186,15 +221,40 @@ function tokenAmount(address, info, tokenProgram) {
         return 0n;
     }
 }
+/**
+ * `claim_v2` signs with the PDA `["referral", project, name]`: refuses (typed error) a referral
+ * account without a name, or one that is not that PDA, before a v2 claim is built.
+ */
+function assertClaimableV2(referralAccount, referral, programId) {
+    if (referral.name === null) {
+        throw new JupiterReferralError('referral_account_unnamed', 'the referral account has no name: claim_v2 needs a referral account created with a name ' +
+            '(PDA ["referral", project, name]), so its v2 collection account cannot be claimed');
+    }
+    let expected;
+    try {
+        expected = deriveJupiterReferralAccount(referral.project, referral.name, programId);
+    }
+    catch (error) {
+        throw new JupiterReferralError('referral_account_not_pda', 'the referral account name is not a valid PDA seed, so claim_v2 cannot sign for it', { cause: error });
+    }
+    if (!expected.equals(referralAccount)) {
+        throw new JupiterReferralError('referral_account_not_pda', 'the referral account is not the PDA ["referral", project, name] that claim_v2 signs with');
+    }
+}
 /**
  * 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 async function buildJupiterReferralClaimTx(p) {
     const { connection } = p;
     const commitment = p.commitment ?? 'confirmed';
     const programId = p.programId ?? JUPITER_REFERRAL_PROGRAM_ID;
+    if (p.priority !== undefined)
+        resolvePriorityFeePolicy(p.priority);
+    const expectedProject = p.expectedProject ?? JUPITER_ULTRA_REFERRAL_PROJECT;
     const retry = p.retry ?? {};
     if (p.payer.equals(p.referralAccount) || p.mint.equals(p.referralAccount)) {
         throw new JupiterReferralError('invalid_params', 'payer, mint and referral account must differ');
@@ -219,6 +279,10 @@ export async function buildJupiterReferralClaimTx(p) {
     if (p.expectedPartner && !referral.partner.equals(p.expectedPartner)) {
         throw new JupiterReferralError('partner_mismatch', 'the referral account partner is not the expected receiver');
     }
+    if (!referral.project.equals(expectedProject)) {
+        throw new JupiterReferralError('project_mismatch', `the referral account belongs to project ${referral.project.toBase58()}, not to the ` +
+            `expected project ${expectedProject.toBase58()} (Jupiter Ultra by default)`);
+    }
     if (!mintInfo)
         throw new JupiterReferralError('mint_not_found', 'mint not found');
     const tokenProgram = mintInfo.owner;
@@ -242,8 +306,10 @@ export async function buildJupiterReferralClaimTx(p) {
     if (v1Amount > 0n)
         claims.push({ version: 'v1', referralTokenAccount: v1Account, amount: v1Amount });
     const v2Amount = tokenAmount(v2Account, v2Info ?? null, tokenProgram);
-    if (v2Amount > 0n)
+    if (v2Amount > 0n) {
+        assertClaimableV2(p.referralAccount, referral, programId);
         claims.push({ version: 'v2', referralTokenAccount: v2Account, amount: v2Amount });
+    }
     const projectAuthority = deriveJupiterProjectAuthority(project.base, programId);
     const summary = {
         referralAccount: p.referralAccount,
@@ -258,8 +324,9 @@ export async function buildJupiterReferralClaimTx(p) {
         createsPartnerTokenAccount: claims.length > 0 && !partnerInfo,
         createsAdminTokenAccount: claims.length > 0 && !adminInfo,
     };
-    if (claims.length === 0)
-        return { transaction: null, lastValidBlockHeight: null, summary };
+    if (claims.length === 0) {
+        return { transaction: null, lastValidBlockHeight: null, summary, priorityFee: null };
+    }
     const transaction = new Transaction();
     if (summary.createsPartnerTokenAccount) {
         transaction.add(createAssociatedTokenAccountIdempotentInstruction(p.payer, partnerTokenAccount, referral.partner, p.mint, tokenProgram));
@@ -288,8 +355,312 @@ export async function buildJupiterReferralClaimTx(p) {
             tokenProgram,
         }, claim.version, programId));
     }
+    let priorityFee = null;
+    if (p.priority !== undefined) {
+        priorityFee = await estimatePriorityFee({
+            connection,
+            writableAccounts: writableAccountsOf(transaction.instructions),
+            computeUnitLimit: JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS,
+            setting: p.priority,
+        });
+        transaction.instructions.unshift(...priorityFeeInstructions(priorityFee));
+    }
     const latest = await retryRpc(() => connection.getLatestBlockhash(commitment), retry);
     transaction.feePayer = p.payer;
     transaction.recentBlockhash = latest.blockhash;
-    return { transaction, lastValidBlockHeight: latest.lastValidBlockHeight, summary };
+    return { transaction, lastValidBlockHeight: latest.lastValidBlockHeight, summary, priorityFee };
+}
+// ---------------------------------------------------------------------------------------------
+// Setup of FORGE's referral account (pure builders; docs/MAINNET.md section 5)
+// ---------------------------------------------------------------------------------------------
+//
+// Verified against the program source (github.com/TeamRaccoons/referral, program/programs/
+// referral/src/instructions/initialize_referral_account_with_name.rs, lib.rs, claim_v2.rs; the
+// IDL of @jup-ag/referral-sdk 0.3.0 agrees):
+// - `initialize_referral_account_with_name(params: { name: String })`: accounts `payer` (mut,
+//   signer), `partner` (SystemAccount, read-only, NOT a signer), `project` (read-only, PDA
+//   `["project", base]`), `referral_account` (mut, init, PDA `["referral", project, name]`,
+//   `ReferralAccount::LEN` = 274 bytes, rent paid by `payer`), `system_program`. The share is the
+//   project's `default_share_bps`. Name: `params.name.chars().count() < 20`, so 1 to 19
+//   characters; the name is also a PDA seed, so at most 32 UTF-8 bytes.
+// - The v2 collection accounts `claim_v2` empties are the associated token accounts of the
+//   referral account (`associated_token::authority = referral_account`): the SDK's
+//   `initializeReferralTokenAccountV2` is a plain `CreateIdempotent` of the Associated Token
+//   program, paid by the payer, which is what `buildJupiterReferralTokenAccountV2Ix` builds.
+// Only the payer signs anywhere: the partner (the revenue wallet) never does.
+export const JUPITER_INITIALIZE_REFERRAL_ACCOUNT_WITH_NAME_DISCRIMINATOR = anchorDiscriminator('global:initialize_referral_account_with_name');
+/** `ReferralAccount::LEN` = 8 + 32 + 32 + 200 + 2: what the initialization allocates. */
+export const JUPITER_REFERRAL_ACCOUNT_SIZE = 274;
+/** `params.name.chars().count() < 20` in the program. */
+export const JUPITER_REFERRAL_NAME_MAX_CHARS = 19;
+/** The name is a PDA seed: at most 32 bytes. */
+export 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 const JUPITER_REFERRAL_SETUP_COMPUTE_UNITS = 150_000;
+/**
+ * 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 function assertJupiterReferralName(name) {
+    const fail = (reason) => new JupiterReferralError('invalid_params', reason);
+    if (typeof name !== 'string' || name.length === 0) {
+        throw fail('the name must be a non-empty string');
+    }
+    const chars = [...name].length;
+    if (chars > JUPITER_REFERRAL_NAME_MAX_CHARS) {
+        throw fail(`the name has ${chars} characters, at most ${JUPITER_REFERRAL_NAME_MAX_CHARS} are allowed`);
+    }
+    const bytes = Buffer.byteLength(name, 'utf8');
+    if (bytes > JUPITER_REFERRAL_NAME_MAX_BYTES) {
+        throw fail(`the name is ${bytes} bytes, at most ${JUPITER_REFERRAL_NAME_MAX_BYTES} are allowed`);
+    }
+    if (/[\s\p{Cc}\p{Cf}]/u.test(name)) {
+        throw fail('the name must not contain whitespace or control characters');
+    }
+    return name;
+}
+/** Borsh `String`: u32 little-endian byte length, then the UTF-8 bytes. */
+export function encodeJupiterReferralName(name) {
+    const bytes = Buffer.from(assertJupiterReferralName(name), 'utf8');
+    const length = Buffer.alloc(4);
+    length.writeUInt32LE(bytes.length);
+    return Buffer.concat([length, bytes]);
+}
+/**
+ * `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 function buildJupiterInitializeReferralAccountWithNameIx(accounts, name, programId = JUPITER_REFERRAL_PROGRAM_ID) {
+    const data = encodeJupiterReferralName(name);
+    const expected = deriveJupiterReferralAccount(accounts.project, name, programId);
+    if (!expected.equals(accounts.referralAccount)) {
+        throw new JupiterReferralError('invalid_params', 'referralAccount is not the PDA ["referral", project, name] of that name');
+    }
+    const keys = [accounts.payer, accounts.partner, accounts.project, accounts.referralAccount];
+    if (new Set(keys.map((k) => k.toBase58())).size !== keys.length) {
+        throw new JupiterReferralError('invalid_params', 'payer, partner, project and referral account must differ');
+    }
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: accounts.payer, isSigner: true, isWritable: true },
+            ro(accounts.partner),
+            ro(accounts.project),
+            rw(accounts.referralAccount),
+            ro(SystemProgram.programId),
+        ],
+        data: Buffer.concat([JUPITER_INITIALIZE_REFERRAL_ACCOUNT_WITH_NAME_DISCRIMINATOR, data]),
+    });
+}
+/**
+ * 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 function buildJupiterReferralTokenAccountV2Ix(p) {
+    assertTokenProgram(p.tokenProgram);
+    if (p.payer.equals(p.referralAccount) || p.mint.equals(p.referralAccount)) {
+        throw new JupiterReferralError('invalid_params', 'payer, mint and referral account must differ');
+    }
+    const tokenAccount = deriveJupiterReferralTokenAccountV2(p.referralAccount, p.mint, p.tokenProgram);
+    return {
+        tokenAccount,
+        instruction: createAssociatedTokenAccountIdempotentInstruction(p.payer, tokenAccount, p.referralAccount, p.mint, p.tokenProgram),
+    };
+}
+/**
+ * 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 function buildJupiterReferralSetupTx(p) {
+    const programId = p.programId ?? JUPITER_REFERRAL_PROGRAM_ID;
+    const project = p.project ?? JUPITER_ULTRA_REFERRAL_PROJECT;
+    const name = assertJupiterReferralName(p.name);
+    if (typeof p.blockhash !== 'string' || p.blockhash.length === 0) {
+        throw new JupiterReferralError('invalid_params', 'blockhash required');
+    }
+    if (!Number.isInteger(p.lastValidBlockHeight) || p.lastValidBlockHeight < 0) {
+        throw new JupiterReferralError('invalid_params', 'lastValidBlockHeight must be a non-negative integer');
+    }
+    if (!p.createReferralAccount && p.tokenAccounts.length === 0) {
+        throw new JupiterReferralError('invalid_params', 'nothing to set up');
+    }
+    const seen = new Set();
+    for (const { mint } of p.tokenAccounts) {
+        if (seen.has(mint.toBase58())) {
+            throw new JupiterReferralError('invalid_params', 'duplicate mint in tokenAccounts');
+        }
+        seen.add(mint.toBase58());
+    }
+    const referralAccount = deriveJupiterReferralAccount(project, name, programId);
+    const transaction = new Transaction({
+        feePayer: p.payer,
+        blockhash: p.blockhash,
+        lastValidBlockHeight: p.lastValidBlockHeight,
+    });
+    if (p.priorityFee && p.priorityFee.microLamports > 0) {
+        transaction.add(...priorityFeeInstructions(p.priorityFee));
+    }
+    if (p.createReferralAccount) {
+        transaction.add(buildJupiterInitializeReferralAccountWithNameIx({ payer: p.payer, partner: p.partner, project, referralAccount }, name, programId));
+    }
+    const tokenAccounts = [];
+    for (const entry of p.tokenAccounts) {
+        const built = buildJupiterReferralTokenAccountV2Ix({
+            payer: p.payer,
+            referralAccount,
+            mint: entry.mint,
+            tokenProgram: entry.tokenProgram,
+        });
+        transaction.add(built.instruction);
+        tokenAccounts.push({ ...entry, tokenAccount: built.tokenAccount });
+    }
+    return {
+        transaction,
+        lastValidBlockHeight: p.lastValidBlockHeight,
+        referralAccount,
+        project,
+        name,
+        tokenAccounts,
+    };
+}
+/**
+ * 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 function inspectJupiterReferralAccount(info, expected) {
+    if (!info)
+        return { status: 'absent' };
+    const programId = expected.programId ?? JUPITER_REFERRAL_PROGRAM_ID;
+    const mismatch = (reason, detail) => ({ status: 'mismatch', reason, detail });
+    if (!info.owner.equals(programId)) {
+        return mismatch('not_a_referral_account', `the address is in use by an account owned by ${info.owner.toBase58()}`);
+    }
+    let account;
+    try {
+        account = decodeJupiterReferralAccount(Buffer.from(info.data));
+    }
+    catch (error) {
+        return mismatch('not_a_referral_account', error.message);
+    }
+    if (!account.partner.equals(expected.partner)) {
+        return mismatch('partner_mismatch', `the referral account partner is ${account.partner.toBase58()}`);
+    }
+    if (!account.project.equals(expected.project)) {
+        return mismatch('project_mismatch', `the referral account project is ${account.project.toBase58()}`);
+    }
+    if (account.name !== expected.name) {
+        return mismatch('name_mismatch', account.name === null
+            ? 'the referral account has no name'
+            : `the referral account name is "${account.name}"`);
+    }
+    return { status: 'ready', account };
+}
+/**
+ * What the v2 collection account address holds: absent, a token account of `mint` owned by the
+ * referral account, or not.
+ */
+export function inspectJupiterReferralTokenAccountV2(address, info, expected) {
+    if (!info)
+        return { status: 'absent' };
+    const mismatch = (reason, detail) => ({ status: 'mismatch', reason, detail });
+    if (!info.owner.equals(expected.tokenProgram)) {
+        return mismatch('not_a_token_account', `the address is in use by an account owned by ${info.owner.toBase58()}`);
+    }
+    let account;
+    try {
+        account = unpackAccount(address, info, expected.tokenProgram);
+    }
+    catch {
+        return mismatch('not_a_token_account', 'the account data is not a token account');
+    }
+    if (!account.mint.equals(expected.mint)) {
+        return mismatch('wrong_mint', `the token account mint is ${account.mint.toBase58()}`);
+    }
+    if (!account.owner.equals(expected.referralAccount)) {
+        return mismatch('wrong_owner', `the token account owner is ${account.owner.toBase58()}`);
+    }
+    return { status: 'ready', amount: account.amount };
+}
+/**
+ * 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 async function readJupiterReferralSetup(p) {
+    const programId = p.programId ?? JUPITER_REFERRAL_PROGRAM_ID;
+    const project = p.project ?? JUPITER_ULTRA_REFERRAL_PROJECT;
+    const name = assertJupiterReferralName(p.name);
+    const commitment = p.commitment ?? 'confirmed';
+    const retry = p.retry ?? {};
+    if (p.mints.length === 0)
+        throw new JupiterReferralError('invalid_params', 'at least one mint');
+    if (new Set(p.mints.map((m) => m.toBase58())).size !== p.mints.length) {
+        throw new JupiterReferralError('invalid_params', 'duplicate mint');
+    }
+    try {
+        await assertCluster(p.connection, 'mainnet-beta', retry);
+    }
+    catch (error) {
+        if (error instanceof PaymentError && error.code === 'wrong_cluster') {
+            throw new JupiterReferralError('wrong_cluster', 'the Jupiter referral program and the Ultra project only exist on mainnet-beta', { cause: error });
+        }
+        throw error;
+    }
+    const referralAccount = deriveJupiterReferralAccount(project, name, programId);
+    const [projectInfo, referralInfo, ...mintInfos] = await retryRpc(() => p.connection.getMultipleAccountsInfo([project, referralAccount, ...p.mints], commitment), retry);
+    if (!projectInfo)
+        throw new JupiterReferralError('project_not_found', 'project not found');
+    if (!projectInfo.owner.equals(programId)) {
+        throw new JupiterReferralError('not_a_project', 'project is not owned by the referral program');
+    }
+    const projectAccount = decodeJupiterProject(Buffer.from(projectInfo.data));
+    const entries = p.mints.map((mint, i) => {
+        const info = mintInfos[i];
+        if (!info) {
+            throw new JupiterReferralError('mint_not_found', `mint ${mint.toBase58()} not found`);
+        }
+        if (!info.owner.equals(TOKEN_PROGRAM_ID) && !info.owner.equals(TOKEN_2022_PROGRAM_ID)) {
+            throw new JupiterReferralError('not_a_mint', `${mint.toBase58()} is not owned by a token program`);
+        }
+        return {
+            mint,
+            tokenProgram: info.owner,
+            tokenAccount: deriveJupiterReferralTokenAccountV2(referralAccount, mint, info.owner),
+        };
+    });
+    const tokenInfos = await retryRpc(() => p.connection.getMultipleAccountsInfo(entries.map((e) => e.tokenAccount), commitment), retry);
+    return {
+        project,
+        projectAccount,
+        name,
+        referralAccount,
+        referral: inspectJupiterReferralAccount(referralInfo ?? null, {
+            partner: p.partner,
+            project,
+            name,
+            programId,
+        }),
+        tokenAccounts: entries.map((entry, i) => ({
+            ...entry,
+            status: inspectJupiterReferralTokenAccountV2(entry.tokenAccount, tokenInfos[i] ?? null, {
+                referralAccount,
+                mint: entry.mint,
+                tokenProgram: entry.tokenProgram,
+            }),
+        })),
+    };
 }

package/dist/launch-metadata.d.ts

@@ -38,6 +38,8 @@ export declare const METADATA_LIMITS: {
  * buy): every byte of the three strings is one byte of the transaction, and a 32-byte name, a
  * 10-byte symbol and a 106-byte URI land at exactly 1,232 bytes (pool.test.ts, "size"). A smaller
  * launch (no first buy, no nonce) has more room; this is the bound for the signer's shape.
+ * A priority fee never shrinks it: up to 136 bytes the launch carries the unit limit and the
+ * price, up to 144 the price alone, beyond that no price (`priorityFeePlacement`, pool.ts).
  */
 export declare const LAUNCH_METADATA_BUDGET_BYTES = 148;
 /** Largest first buy (the spec bound, `launchpadCoin.firstBuySol` <= 10 SOL). */

package/dist/launch-metadata.js

@@ -25,6 +25,8 @@ export const METADATA_LIMITS = { name: 32, symbol: 10, uri: 200 };
  * buy): every byte of the three strings is one byte of the transaction, and a 32-byte name, a
  * 10-byte symbol and a 106-byte URI land at exactly 1,232 bytes (pool.test.ts, "size"). A smaller
  * launch (no first buy, no nonce) has more room; this is the bound for the signer's shape.
+ * A priority fee never shrinks it: up to 136 bytes the launch carries the unit limit and the
+ * price, up to 144 the price alone, beyond that no price (`priorityFeePlacement`, pool.ts).
  */
 export const LAUNCH_METADATA_BUDGET_BYTES = 148;
 /** Largest first buy (the spec bound, `launchpadCoin.firstBuySol` <= 10 SOL). */

package/dist/meteora-referral.d.ts

@@ -0,0 +1,119 @@
+import { PublicKey, Transaction, TransactionInstruction, type AccountInfo, type Commitment, type Connection } from '@solana/web3.js';
+import { type PriorityFeeQuote } from './priority-fee.js';
+import { type RetryOptions } from './reads.js';
+/** Default seed of the referral account address (`createWithSeed(payer, seed, SPL Token)`). */
+export declare const METEORA_REFERRAL_ACCOUNT_SEED = "forge-meteora-referral";
+/** Longest seed `createWithSeed` accepts, in bytes (System program limit). */
+export declare const MAX_METEORA_REFERRAL_SEED_BYTES = 32;
+/**
+ * Compute unit limit of the setup transaction with a priority fee: one `createAccountWithSeed`
+ * and one `InitializeAccount3` (a few thousand units each), with a wide margin.
+ */
+export declare const METEORA_REFERRAL_SETUP_COMPUTE_UNITS = 30000;
+/** SPL Token `InitializeAccount3` instruction tag (u8), followed by the 32-byte owner. */
+export declare const TOKEN_INITIALIZE_ACCOUNT3_TAG = 18;
+export type MeteoraReferralErrorCode = 'invalid_params';
+export declare class MeteoraReferralError extends Error {
+    readonly code: MeteoraReferralErrorCode;
+    constructor(code: MeteoraReferralErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Checks a `createWithSeed` seed: 1 to 32 UTF-8 bytes, no control character. */
+export declare function assertMeteoraReferralSeed(seed: string): void;
+/**
+ * Address of the referral account created by `buildCreateMeteoraReferralAccountTx` for `payer`
+ * and `seed`: `createWithSeed(payer, seed, SPL Token program)`, i.e.
+ * `sha256(payer || seed || program)`, the same derivation as `PublicKey.createWithSeed`
+ * (synchronous here, so the builders stay pure).
+ */
+export declare function deriveMeteoraReferralAccount(payer: PublicKey, seed?: string): PublicKey;
+export interface CreateMeteoraReferralAccountParams {
+    /** Fee payer, rent payer and base of the address derivation: the only signer. */
+    payer: PublicKey;
+    /** Owner of the token account: the FORGE revenue wallet (D34). */
+    owner: PublicKey;
+    /** Seed of the address (default `METEORA_REFERRAL_ACCOUNT_SEED`), 1 to 32 bytes. */
+    seed?: string;
+    /** Rent-exempt minimum of a token account (`ACCOUNT_SIZE` = 165 bytes), read by the caller. */
+    rentLamports: bigint;
+}
+export interface MeteoraReferralAccountInstructions {
+    /** The new token account: `deriveMeteoraReferralAccount(payer, seed)`. */
+    account: PublicKey;
+    seed: string;
+    /** `createAccountWithSeed` (payer -> account, rent, 165 bytes, SPL Token) then `InitializeAccount3`. */
+    instructions: TransactionInstruction[];
+}
+/**
+ * The two instructions creating the standalone wrapped-SOL token account of `owner`:
+ * System `createAccountWithSeed` (from = base = payer; exactly the rent of 165 bytes; owner
+ * program = SPL Token) and SPL Token `InitializeAccount3` (account, wrapped SOL mint; owner in
+ * the data, no owner signature). Refuses an owner equal to the payer, a zero rent, and a seed
+ * whose address is the owner's associated wrapped-SOL account (impossible in practice: the
+ * associated account is a PDA, this address is a hash; checked all the same).
+ */
+export declare function buildCreateMeteoraReferralAccountIxs(p: CreateMeteoraReferralAccountParams): MeteoraReferralAccountInstructions;
+export interface BuildCreateMeteoraReferralAccountTxParams extends CreateMeteoraReferralAccountParams {
+    blockhash: string;
+    lastValidBlockHeight: number;
+    /**
+     * Priority fee quote of the caller (`METEORA_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'>;
+}
+export interface CreateMeteoraReferralAccountTx extends MeteoraReferralAccountInstructions {
+    /** Unsigned legacy transaction (fee payer = payer, blockhash set). */
+    transaction: Transaction;
+    lastValidBlockHeight: number;
+}
+/**
+ * Unsigned transaction creating the Meteora referral account (`buildCreateMeteoraReferralAccountIxs`
+ * after the optional compute budget). It does not check that the address is free: inspect it
+ * first (`readMeteoraReferralAccount`); creating it twice fails on-chain, nothing is lost but
+ * the fee.
+ */
+export declare function buildCreateMeteoraReferralAccountTx(p: BuildCreateMeteoraReferralAccountTxParams): CreateMeteoraReferralAccountTx;
+export type MeteoraReferralMismatch = 
+/** The address holds something that is not an SPL Token account (or none that decodes). */
+'not_a_token_account' | 'wrong_mint' | 'wrong_owner'
+/** The account is the owner's associated wrapped-SOL account: Jupiter claims would land in it. */
+ | 'associated_account' | 'frozen'
+/** A delegate or a close authority could move or close it: not acceptable for a fee account. */
+ | 'delegated' | 'close_authority';
+export type MeteoraReferralAccountStatus = 
+/** No account at the address: the setup creates it. */
+{
+    status: 'absent';
+}
+/** A wrapped-SOL token account held by the expected owner, standalone: nothing to do. */
+ | {
+    status: 'ready';
+    lamports: bigint;
+    amount: bigint;
+}
+/** Something else lives there: never create, never reuse (the caller refuses). */
+ | {
+    status: 'mismatch';
+    reason: MeteoraReferralMismatch;
+    detail: string;
+};
+export interface MeteoraReferralExpectation {
+    /** The FORGE revenue wallet. */
+    owner: PublicKey;
+}
+/**
+ * What `address` holds, against the expected shape of the Meteora referral account: absent,
+ * ready (a standalone wrapped-SOL token account of `owner`, neither frozen, delegated nor
+ * closable by someone else), or a mismatch with its reason.
+ */
+export declare function inspectMeteoraReferralAccount(address: PublicKey, info: AccountInfo<Buffer> | null, expected: MeteoraReferralExpectation): MeteoraReferralAccountStatus;
+export interface ReadMeteoraReferralAccountParams extends MeteoraReferralExpectation {
+    connection: Pick<Connection, 'getAccountInfo'>;
+    address: PublicKey;
+    commitment?: Commitment;
+    retry?: RetryOptions;
+}
+/** Reads `address` and inspects it (`inspectMeteoraReferralAccount`). Any cluster. */
+export declare function readMeteoraReferralAccount(p: ReadMeteoraReferralAccountParams): Promise<MeteoraReferralAccountStatus>;