@forgedevv/core 0.1.0 → 0.3.0

package/dist/launch-metadata.d.ts

@@ -15,7 +15,9 @@
 import type { LaunchpadSpec } from '@forge/shared';
 export type LaunchCoinErrorCode = 'INVALID_INPUT' | 'CONFIG_NOT_FOUND' | 'CONFIG_MISMATCH' | 'POOL_EXISTS' | 'MINT_EXISTS'
 /** A referral was given for the first buy: it would lose the first-swap minimum fee. */
- | 'REFERRAL_UNSUPPORTED' | 'RENT_PAYER_REFUSED' | 'FIRST_BUY_EXCEEDS_CURVE' | 'QUOTE_FAILED' | 'UNEXPECTED_SIGNERS' | 'TX_TOO_LARGE';
+ | 'REFERRAL_UNSUPPORTED' | 'RENT_PAYER_REFUSED' | 'FIRST_BUY_EXCEEDS_CURVE' | 'QUOTE_FAILED' | 'UNEXPECTED_SIGNERS' | 'TX_TOO_LARGE'
+/** FORGE_PLATFORM_FEE_WALLET does not exist or is not rent-exempt (user coin launch). */
+ | 'PLATFORM_FEE_WALLET_NOT_READY';
 /** The launch transaction cannot be built. Nothing has been sent. */
 export declare class LaunchCoinError extends Error {
     readonly code: LaunchCoinErrorCode;
@@ -36,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>;

package/dist/meteora-referral.js

@@ -0,0 +1,188 @@
+/**
+ * Meteora referral account setup (docs/METEORA.md "The Meteora referral", docs/DECISIONS.md D34).
+ *
+ * The Meteora referral of every curve swap core builds is a wrapped-SOL token account held by
+ * the FORGE revenue wallet (`FORGE_METEORA_REFERRAL_ACCOUNT`). It must be a STANDALONE token
+ * account, never the wallet's associated token account: the Jupiter referral claims land in the
+ * associated account, and the revenue job books the two separately (`meteora_referral` /
+ * `jupiter_referral`).
+ *
+ * The account lives at an address derived from the fee payer and a fixed seed
+ * (`createAccountWithSeed`: no extra keypair to generate or keep, and the address can be
+ * re-derived at any time), 165 bytes owned by the SPL Token program, then `InitializeAccount3`
+ * sets its mint (wrapped SOL) and its owner (the revenue wallet) from the instruction data. The
+ * only signer is the payer: neither the owner nor the new account signs, so the revenue key never
+ * has to sign its own setup.
+ *
+ * Pure builders (byte-for-byte tested) and pure inspection of what the chain holds; the only
+ * network call is the optional `readMeteoraReferralAccount`. Any cluster: a WSOL token account
+ * exists on devnet too (the devnet proof of the revenue job uses one).
+ */
+import { createHash } from 'node:crypto';
+import { ACCOUNT_SIZE, NATIVE_MINT, TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, unpackAccount, } from '@solana/spl-token';
+import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from '@solana/web3.js';
+import { priorityFeeInstructions } from './priority-fee.js';
+import { retryRpc } from './reads.js';
+// ---------------------------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------------------------
+/** Default seed of the referral account address (`createWithSeed(payer, seed, SPL Token)`). */
+export const METEORA_REFERRAL_ACCOUNT_SEED = 'forge-meteora-referral';
+/** Longest seed `createWithSeed` accepts, in bytes (System program limit). */
+export 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 const METEORA_REFERRAL_SETUP_COMPUTE_UNITS = 30_000;
+/** SPL Token `InitializeAccount3` instruction tag (u8), followed by the 32-byte owner. */
+export const TOKEN_INITIALIZE_ACCOUNT3_TAG = 18;
+export class MeteoraReferralError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'MeteoraReferralError';
+        this.code = code;
+    }
+}
+function invalid(message) {
+    throw new MeteoraReferralError('invalid_params', message);
+}
+// ---------------------------------------------------------------------------------------------
+// Address
+// ---------------------------------------------------------------------------------------------
+/** Checks a `createWithSeed` seed: 1 to 32 UTF-8 bytes, no control character. */
+export function assertMeteoraReferralSeed(seed) {
+    if (typeof seed !== 'string' || seed.length === 0)
+        invalid('the seed must be a non-empty string');
+    if (/\p{Cc}/u.test(seed))
+        invalid('the seed must not contain control characters');
+    const bytes = Buffer.byteLength(seed, 'utf8');
+    if (bytes > MAX_METEORA_REFERRAL_SEED_BYTES) {
+        invalid(`the seed is ${bytes} bytes, at most ${MAX_METEORA_REFERRAL_SEED_BYTES} are allowed`);
+    }
+}
+/**
+ * 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 function deriveMeteoraReferralAccount(payer, seed = METEORA_REFERRAL_ACCOUNT_SEED) {
+    assertMeteoraReferralSeed(seed);
+    const digest = createHash('sha256')
+        .update(payer.toBuffer())
+        .update(Buffer.from(seed, 'utf8'))
+        .update(TOKEN_PROGRAM_ID.toBuffer())
+        .digest();
+    return new PublicKey(digest);
+}
+/**
+ * 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 function buildCreateMeteoraReferralAccountIxs(p) {
+    const seed = p.seed ?? METEORA_REFERRAL_ACCOUNT_SEED;
+    if (p.payer.equals(p.owner))
+        invalid('the payer must not be the owner of the referral account');
+    if (p.owner.equals(PublicKey.default))
+        invalid('the owner must not be the default key');
+    if (typeof p.rentLamports !== 'bigint' || p.rentLamports <= 0n) {
+        invalid('rentLamports must be a positive bigint');
+    }
+    if (p.rentLamports > BigInt(Number.MAX_SAFE_INTEGER))
+        invalid('rentLamports is too large');
+    const account = deriveMeteoraReferralAccount(p.payer, seed);
+    if (account.equals(getAssociatedTokenAddressSync(NATIVE_MINT, p.owner, true))) {
+        invalid('the derived address is the associated wrapped-SOL account of the owner');
+    }
+    const create = SystemProgram.createAccountWithSeed({
+        fromPubkey: p.payer,
+        basePubkey: p.payer,
+        seed,
+        newAccountPubkey: account,
+        lamports: Number(p.rentLamports),
+        space: ACCOUNT_SIZE,
+        programId: TOKEN_PROGRAM_ID,
+    });
+    const initialize = new TransactionInstruction({
+        programId: TOKEN_PROGRAM_ID,
+        keys: [
+            { pubkey: account, isSigner: false, isWritable: true },
+            { pubkey: NATIVE_MINT, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.concat([Buffer.from([TOKEN_INITIALIZE_ACCOUNT3_TAG]), p.owner.toBuffer()]),
+    });
+    return { account, seed, instructions: [create, initialize] };
+}
+/**
+ * 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 function buildCreateMeteoraReferralAccountTx(p) {
+    if (typeof p.blockhash !== 'string' || p.blockhash.length === 0)
+        invalid('blockhash required');
+    if (!Number.isInteger(p.lastValidBlockHeight) || p.lastValidBlockHeight < 0) {
+        invalid('lastValidBlockHeight must be a non-negative integer');
+    }
+    const built = buildCreateMeteoraReferralAccountIxs(p);
+    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));
+    }
+    transaction.add(...built.instructions);
+    return { ...built, transaction, lastValidBlockHeight: p.lastValidBlockHeight };
+}
+/**
+ * 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 function inspectMeteoraReferralAccount(address, info, expected) {
+    if (!info)
+        return { status: 'absent' };
+    const mismatch = (reason, detail) => ({ status: 'mismatch', reason, detail });
+    if (!info.owner.equals(TOKEN_PROGRAM_ID)) {
+        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, TOKEN_PROGRAM_ID);
+    }
+    catch {
+        return mismatch('not_a_token_account', 'the account data is not an SPL Token account');
+    }
+    if (!account.mint.equals(NATIVE_MINT)) {
+        return mismatch('wrong_mint', `the token account mint is ${account.mint.toBase58()}`);
+    }
+    if (!account.owner.equals(expected.owner)) {
+        return mismatch('wrong_owner', `the token account owner is ${account.owner.toBase58()}`);
+    }
+    if (address.equals(getAssociatedTokenAddressSync(NATIVE_MINT, expected.owner, true))) {
+        return mismatch('associated_account', 'the account is the associated wrapped-SOL account of the owner, not a standalone one');
+    }
+    if (account.isFrozen)
+        return mismatch('frozen', 'the token account is frozen');
+    if (account.delegate !== null) {
+        return mismatch('delegated', `the token account has a delegate ${account.delegate.toBase58()}`);
+    }
+    if (account.closeAuthority !== null && !account.closeAuthority.equals(expected.owner)) {
+        return mismatch('close_authority', `the token account can be closed by ${account.closeAuthority.toBase58()}`);
+    }
+    return { status: 'ready', lamports: BigInt(info.lamports), amount: account.amount };
+}
+/** Reads `address` and inspects it (`inspectMeteoraReferralAccount`). Any cluster. */
+export async function readMeteoraReferralAccount(p) {
+    const info = await retryRpc(() => p.connection.getAccountInfo(p.address, p.commitment ?? 'confirmed'), p.retry ?? {});
+    return inspectMeteoraReferralAccount(p.address, info, { owner: p.owner });
+}

package/dist/payments.d.ts

@@ -5,6 +5,9 @@
  *   1. a System Program transfer of `lamports` from the payer to `FORGE_CASHBOX_WALLET`;
  *   2. an SPL Memo (v2) instruction, signed by the payer, whose UTF-8 data is
  *      `forge:job:<jobId>` (`jobId` = the job UUID, lowercase). See `paymentMemo`.
+ * With a `priority` option, two compute budget instructions come first (`setComputeUnitLimit`
+ * of `PAYMENT_COMPUTE_UNITS`, then `setComputeUnitPrice`, priced from the recent fees of the
+ * payer and the cashbox and bounded: priority-fee.ts), so a payment still lands under congestion.
  *
  * `verifyPayment` checks a transaction on-chain and returns a typed result; it never throws on a
  * transaction that is "not there yet" (it returns `pending`). It throws only on configuration
@@ -18,6 +21,7 @@
  */
 import { PublicKey, Transaction, TransactionInstruction, type Commitment, type Connection, type Finality, type VersionedTransactionResponse } from '@solana/web3.js';
 import { type AddressEnv } from './addresses.js';
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
 import { type RetryOptions } from './reads.js';
 /** SPL Memo program v2 (the one wallets and explorers decode). */
 export declare const MEMO_PROGRAM_ID: PublicKey;
@@ -30,6 +34,11 @@ export declare const PAYMENT_MEMO_PREFIX = "forge:job:";
  * against a unit mistake upstream.
  */
 export declare const MAX_PAYMENT_LAMPORTS: bigint;
+/**
+ * Compute unit limit of a payment with a priority fee: a System transfer (150 CU) and a memo of
+ * about 46 bytes signed by the payer (a few thousand CU), with a wide margin.
+ */
+export declare const PAYMENT_COMPUTE_UNITS = 50000;
 /** Genesis hashes of the Solana clusters FORGE uses (public network constants). */
 export declare const CLUSTER_GENESIS_HASH: {
     readonly devnet: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
@@ -61,6 +70,12 @@ export interface PaymentTxOptions {
     env?: AddressEnv;
     commitment?: Commitment;
     retry?: RetryOptions;
+    /**
+     * Priority fee read from the cluster for the payer and the cashbox, bounded by this setting
+     * (`{}` = `DEFAULT_PRIORITY_FEE_POLICY`, at most 0.0005 SOL). Without it the transaction holds
+     * the transfer and the memo only.
+     */
+    priority?: PriorityFeeSetting;
 }
 export interface PaymentTxResult {
     /** Unsigned transaction: fee payer = payer, recent blockhash set. The payer signs it. */
@@ -69,6 +84,8 @@ export interface PaymentTxResult {
     recipient: PublicKey;
     lamports: bigint;
     memo: string;
+    /** The priority fee (price, fee, cap), or null without a `priority` option. */
+    priorityFee: PriorityFeeQuote | null;
 }
 /**
  * Builds the payment transaction of `jobId`. Checks that the cashbox will be rent-exempt after

package/dist/payments.js

@@ -5,6 +5,9 @@
  *   1. a System Program transfer of `lamports` from the payer to `FORGE_CASHBOX_WALLET`;
  *   2. an SPL Memo (v2) instruction, signed by the payer, whose UTF-8 data is
  *      `forge:job:<jobId>` (`jobId` = the job UUID, lowercase). See `paymentMemo`.
+ * With a `priority` option, two compute budget instructions come first (`setComputeUnitLimit`
+ * of `PAYMENT_COMPUTE_UNITS`, then `setComputeUnitPrice`, priced from the recent fees of the
+ * payer and the cashbox and bounded: priority-fee.ts), so a payment still lands under congestion.
  *
  * `verifyPayment` checks a transaction on-chain and returns a typed result; it never throws on a
  * transaction that is "not there yet" (it returns `pending`). It throws only on configuration
@@ -20,6 +23,7 @@ import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from '
 import { Base58Signature, Uuid } from '@forge/shared';
 import { requireAddresses } from './addresses.js';
 import { LAMPORTS_PER_SOL_BIGINT } from './constants.js';
+import { estimatePriorityFee, priorityFeeInstructions, } from './priority-fee.js';
 import { retryRpc } from './reads.js';
 import { encodeBase58 } from './tx.js';
 /** SPL Memo program v2 (the one wallets and explorers decode). */
@@ -33,6 +37,11 @@ export const PAYMENT_MEMO_PREFIX = 'forge:job:';
  * against a unit mistake upstream.
  */
 export const MAX_PAYMENT_LAMPORTS = 100n * LAMPORTS_PER_SOL_BIGINT;
+/**
+ * Compute unit limit of a payment with a priority fee: a System transfer (150 CU) and a memo of
+ * about 46 bytes signed by the payer (a few thousand CU), with a wide margin.
+ */
+export const PAYMENT_COMPUTE_UNITS = 50_000;
 /** Genesis hashes of the Solana clusters FORGE uses (public network constants). */
 export const CLUSTER_GENESIS_HASH = {
     devnet: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG',
@@ -96,9 +105,17 @@ export async function buildPaymentTx(connection, params, options = {}) {
     const cashbox = resolveCashbox(options.env);
     const instructions = buildPaymentInstructions({ ...params, cashbox });
     const commitment = options.commitment ?? 'confirmed';
-    const [rentExempt, cashboxBalance] = await Promise.all([
+    const [rentExempt, cashboxBalance, priorityFee] = await Promise.all([
         retryRpc(() => connection.getMinimumBalanceForRentExemption(0, commitment), options.retry),
         retryRpc(() => connection.getBalance(cashbox, commitment), options.retry),
+        options.priority === undefined
+            ? Promise.resolve(null)
+            : estimatePriorityFee({
+                connection,
+                writableAccounts: [params.payer, cashbox],
+                computeUnitLimit: PAYMENT_COMPUTE_UNITS,
+                setting: options.priority,
+            }),
     ]);
     if (BigInt(cashboxBalance) + params.lamports < BigInt(rentExempt)) {
         throw new PaymentError('cashbox_not_rent_exempt', 'The cashbox would not be rent-exempt after this payment: fund it first');
@@ -108,13 +125,14 @@ export async function buildPaymentTx(connection, params, options = {}) {
         feePayer: params.payer,
         blockhash,
         lastValidBlockHeight,
-    }).add(...instructions);
+    }).add(...(priorityFee ? priorityFeeInstructions(priorityFee) : []), ...instructions);
     return {
         transaction,
         lastValidBlockHeight,
         recipient: cashbox,
         lamports: params.lamports,
         memo: paymentMemo(params.jobId),
+        priorityFee,
     };
 }
 const genesisCache = new WeakMap();