@forgedevv/core 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -3,13 +3,236 @@
 All notable changes to `@forge/core`. Versions follow semantic versioning. Consumers (the
 launchpad template, the signer, the web app) pin an exact version, never a range.
 
-## 0.1.0 — unreleased
+## 0.3.0 — 2026-10-17
 
-First version meant for publication on npm as `@forgedevv/core` (with `@forgedevv/shared`), through
-`node scripts/publish-core.mjs --publish`. Not published yet.
+Changes after 0.2.0. Publish `@forgedevv/shared` 0.3.0 with it (new kill switch `revenue_paused` in `FlagKey`).
 
-- `listCoinsOfCreator` (creator pools through SDK `getPoolsByCreator`), `DBC_POOL_CREATOR_OFFSET`, `DBC_POOL_CONFIG_OFFSET`.
+### Changed (Jupiter fixes)
+
+- **Jupiter referral fee.** `FEES.jupiterIntegratorFeeBps` (re-exported from `@forge/shared`) is
+  50 bps, was 30: the Jupiter Plugin passes `referralFee` to Ultra `/order`, which refuses any
+  value outside 50..255 bps, so every swap of a graduated coin failed. Jupiter keeps 20% of it.
+  `FEES.platformFeeBps` (30 bps, `PLATFORM_FEE_BPS` on swaps built by core) is unchanged.
+- **Jupiter referral claims.** `buildJupiterReferralClaimTx` refuses a referral account of another
+  project than Jupiter's Ultra project (`project_mismatch`; the new `expectedProject` parameter
+  overrides the default `JUPITER_ULTRA_REFERRAL_PROJECT`). A funded v2 collection account is only
+  claimed for a named referral account at the PDA `["referral", project, name]`, the only kind
+  `claim_v2` accepts: `referral_account_unnamed` or `referral_account_not_pda` otherwise (new
+  `JupiterReferralErrorCode` values; the whole build is refused). With an empty v2 account, an
+  unnamed account still claims its v1 collection account. Devnet is unchanged: any cluster but
+  mainnet-beta is still refused (`wrong_cluster`) before these reads.
+
+### Added (Jupiter fixes)
+
+- `JUPITER_REFERRAL_FEE_BPS_RANGE` (`{ min: 50, max: 255 }`) and
+  `assertJupiterReferralFeeBps(bps)` (constants.ts): returns a whole number of bps within the range
+  Jupiter Ultra accepts, throws a `RangeError` otherwise. The launchpad template runs the plugin
+  fee through it and fails closed outside it.
+- `JUPITER_ULTRA_REFERRAL_PROJECT` (`DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc`) and
+  `deriveJupiterReferralAccount(project, name, programId?)` (jupiter-referral.ts).
+
+### Added (revenue wallet referral accounts setup)
+
+Pure builders of the two accounts the revenue wallet must hold (docs/MAINNET.md section 5), for
+the signer's one-off `--setup-revenue-referrals` command. Only the payer signs: neither the
+revenue wallet nor the new accounts do.
+
+- **`meteora-referral.ts`** (re-exported by the index): `deriveMeteoraReferralAccount(payer,
+  seed?)` (`createWithSeed(payer, seed, SPL Token)`, default seed
+  `METEORA_REFERRAL_ACCOUNT_SEED` = `forge-meteora-referral`), `buildCreateMeteoraReferralAccountIxs`
+  / `buildCreateMeteoraReferralAccountTx({ payer, owner, seed?, rentLamports, blockhash,
+  lastValidBlockHeight, priorityFee? })`: System `createAccountWithSeed` (from = base = payer,
+  the rent of 165 bytes, SPL Token owned) then SPL Token `InitializeAccount3` (wrapped SOL,
+  owner = the revenue wallet, no owner signature), the compute budget pair first when the quote
+  has a price (`METEORA_REFERRAL_SETUP_COMPUTE_UNITS` = 30,000); `inspectMeteoraReferralAccount`
+  (pure: `absent`, `ready`, or `mismatch` with a reason: not a token account, wrong mint or owner,
+  the owner's associated account, frozen, delegated, closable by someone else) and
+  `readMeteoraReferralAccount` (any cluster); `MeteoraReferralError` (`invalid_params`).
+- **Jupiter referral setup** (jupiter-referral.ts), verified against the program source
+  (`initialize_referral_account_with_name.rs`, `lib.rs`, `claim_v2.rs`) and the SDK 0.3.0 IDL:
+  `JUPITER_INITIALIZE_REFERRAL_ACCOUNT_WITH_NAME_DISCRIMINATOR`, `JUPITER_REFERRAL_ACCOUNT_SIZE`
+  (274), `JUPITER_REFERRAL_NAME_MAX_CHARS` (19: the program requires fewer than 20 characters)
+  and `JUPITER_REFERRAL_NAME_MAX_BYTES` (32: a PDA seed), `assertJupiterReferralName` (also
+  refuses whitespace and control characters), `encodeJupiterReferralName` (Borsh),
+  `buildJupiterInitializeReferralAccountWithNameIx({ payer, partner, project, referralAccount },
+  name)` (the IDL's accounts: payer the only signer, partner read-only and not a signer, the
+  referral account the PDA `["referral", project, name]`),
+  `buildJupiterReferralTokenAccountV2Ix({ payer, referralAccount, mint, tokenProgram })` (the v2
+  collection account `claim_v2` empties is the referral account's associated token account: an
+  idempotent creation, what the SDK's `initializeReferralTokenAccountV2` sends),
+  `buildJupiterReferralSetupTx({ payer, partner, project?, name, createReferralAccount,
+  tokenAccounts, blockhash, lastValidBlockHeight, priorityFee? })` (Ultra project by default,
+  `JUPITER_REFERRAL_SETUP_COMPUTE_UNITS` = 150,000), `inspectJupiterReferralAccount` /
+  `inspectJupiterReferralTokenAccountV2` (pure statuses with mismatch reasons: partner, project,
+  name, owner, mint) and `readJupiterReferralSetup({ connection, partner, name, mints })`
+  (mainnet-beta only, `wrong_cluster` before any read; reads the project, the mints' token
+  programs, the referral account and its collection accounts).
+
+### Changed (revenue wallet, docs/DECISIONS.md D34)
+
+- **New address `FORGE_REVENUE_WALLET`** (`FORGE_ADDRESS_NAMES`, `getRevenueWallet`): the
+  signer-held wallet where the non-native trading revenue lands before the signer converts it to
+  SOL and forwards it to the multisig vault. It replaces the vault as the holder of the Meteora
+  referral account and as the partner of the Jupiter referral account; the platform fee goes to
+  it too (`FORGE_PLATFORM_FEE_WALLET` must be that wallet).
+- **Swaps.** `swapFeeAddresses` returns `revenueWallet` (was `multisigVault`), read from
+  `FORGE_REVENUE_WALLET` (optional, as before): when set, the Meteora referral token account must
+  be held by it (`REFERRAL_ACCOUNT_INVALID`, `assertReferralAccountReady(..., expectedOwner?)`)
+  and `FORGE_PLATFORM_FEE_WALLET` must be it (`PLATFORM_FEE_WALLET_MISMATCH`, checked before any
+  network call by `buildBuyTx`, `buildSellTx` and `assertSwapFeeAccountsReady`). Client sites
+  receive `NEXT_PUBLIC_FORGE_REVENUE_WALLET` instead of `NEXT_PUBLIC_FORGE_MULTISIG_VAULT`.
+- `buildJupiterReferralClaimTx` is unchanged: `expectedPartner` is now the revenue wallet.
+
+### Added (priority fees)
+
+- **`priority-fee.ts`** (browser-safe, re-exported by the index): `computePriorityFee` (pure: the
+  nearest-rank `percentile` of `getRecentPrioritizationFees`, at least `floorMicroLamports`, at
+  most `maxMicroLamports` per CU and `maxLamports` for the whole transaction; an empty list or a
+  failed read prices at the floor, reported in `source`), `estimatePriorityFee` (reads the fees
+  for the transaction's writable accounts, at most `MAX_PRIORITY_FEE_ACCOUNTS` = 32),
+  `readRecentPriorityFees`, `resolvePriorityFeePolicy`, `feePercentile`, `maxPriceForBudget`,
+  `maxPriorityFeeLamports` (the worst case of a setting, to show before building),
+  `fixedPriorityFee`, `priorityFeeInstructions` (unit limit then price; `priceOnly`),
+  `writableAccountsOf`, and `checkComputeBudgetInstructions` / `ComputeBudgetCheckError` for
+  transaction policies (no account, `SetComputeUnitLimit` / `SetComputeUnitPrice` only, at most
+  one of each, bounded values and fee; without a limit the fee is counted for 1.4M CU).
+  `DEFAULT_PRIORITY_FEE_POLICY`: 75th percentile, floor 10,000 micro-lamports per CU, at most
+  1,000,000 per CU and 500,000 lamports (0.0005 SOL) per transaction; hard ceilings
+  `MAX_PRIORITY_FEE_MICRO_LAMPORTS` (10 lamports per CU) and `MAX_PRIORITY_FEE_LAMPORTS`
+  (0.01 SOL). Types `PriorityFeeSetting`, `PriorityFeePolicy`, `PriorityFeeQuote`,
+  `PriorityFeeSource`, `RecentPrioritizationFee`.
+- **Builders accept an optional `priority` setting** (exclusive with their fixed price, if any),
+  which puts `setComputeUnitLimit` then `setComputeUnitPrice` first (after the nonce advance):
+  `buildBuyTx` / `buildSellTx` (`SwapBuildOptions.priority`; the pure `buildSwapTransaction`
+  refuses it), `buildPaymentTx` (`PaymentTxOptions.priority`, limit `PAYMENT_COMPUTE_UNITS` =
+  50,000), `buildLaunchCoinTx` and `buildUserCoinLaunchTx`, `buildCreateConfigTx`, the creator,
+  partner and pool creation fee claims (`ClaimOptions.priority`, limits `CLAIM_COMPUTE_UNITS` =
+  200,000 and `POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS` = 100,000), the DAMM v2 position claim
+  (`positionClaimComputeUnits`) and `buildJupiterReferralClaimTx`
+  (`JUPITER_REFERRAL_CLAIM_COMPUTE_UNITS` = 300,000). Their results report the quote
+  (`priorityFee`), and the claim costs count the fee. `CREATE_NONCE_ACCOUNT_COMPUTE_UNITS`
+  (10,000) names the limit of the nonce account builders.
+- **Launch sizes.** The launchpad coin launch keeps the 148-byte metadata budget: with a priority
+  fee it carries the unit limit and the price up to 136 bytes of metadata, the price alone up to
+  144 (priced for `MAX_TRANSACTION_COMPUTE_UNITS`), and no price beyond
+  (`LaunchCoinSummary.priorityFeePlacement`: `limit_and_price`, `price_only`,
+  `omitted_for_size`). A priced swap or user coin launch is 12 bytes larger.
+
+### Changed (priority fees)
+
+- `BuiltSwapTransaction.priorityFee`, `PaymentTxResult.priorityFee`, `CreateConfigTx.priorityFee`,
+  `ClaimSummary.priorityFee`, `PoolCreationFeeClaimSummary.priorityFee`,
+  `PositionClaimSummary.priorityFee`, `JupiterReferralClaimTx.priorityFee` and
+  `LaunchCoinSummary` / `UserCoinLaunchSummary` `.priorityFee` and `.priorityFeePlacement` are new
+  required fields: code that builds these objects itself (test fakes) must set them. Without a
+  `priority` setting every transaction is byte for byte what 0.2.0 built.
+- `ClaimCosts.networkFeeLamports` and `PositionClaimCosts.networkFeeLamports` include the
+  priority fee (0 without a setting).
+- Consumers: the launchpad template prices its trades, coin creations and creator fee claims with
+  the defaults, so client sites need this version, and the FORGE RPC relay must serve
+  `getRecentPrioritizationFees` (apps/web, same release).
+
+### Added (on-chain fallback of the coin data)
+
+- `listPoolStatesOfConfig(connection, config, options?)` (reads.ts): the decoded pools of a config
+  with the config state (`DbcPoolState[]`, sorted by pool address), from the SDK's
+  `getPoolsByConfig`; a pool whose decoded config differs is dropped. `listCoinsOfConfig` now
+  summarizes its result (unchanged output). The launchpad template lists its coins with it when
+  the Jupiter data API is unavailable (and always on devnet).
+- `poolSpotPrice(sqrtPrice, baseDecimals, quoteDecimals = 9)` (reads.ts): display price of one
+  whole coin in whole quote tokens from the pool's Q64.64 `sqrtPrice` (same value as the SDK's
+  `getPriceFromSqrtPrice`, as a float).
+
+## 0.2.0 — 2026-10-17
+
+Everything below was added after 0.1.0 and published on npm on 2026-10-17 with `@forgedevv/shared` 0.2.0.
+
+### Changed (security review)
+
+- **On-chain configs compared field by field.** New `onchainConfigMismatches(config, kind,
+  { spec?, owner?, poolCreationFeeLamports? })` (config.ts) compares a decoded config with the
+  parameters core builds for it: accounts, token, base fee (cliff, periods, period, reduction,
+  mode), dynamic fee, creator share, pool creation fee, first swap at the minimum fee, activation,
+  liquidity split and vesting, migration option / fee option / threshold, migration fee
+  percentages, migrated pool fee, locked vesting, token supply, start price and curve. Without a
+  spec, the spec fields are read from the config and must be values a FORGE spec can hold.
+  - `assertLaunchCoinConfig(config, owner, spec?)`: runs it (optional `spec`, recommended).
+    `BuildLaunchCoinTxParams.spec?` passes it. A coin config with a pool creation fee is now
+    `CONFIG_MISMATCH` (the current builder sets none).
+  - `assertUserCoinConfig(config, expected?)`: runs it against the launchpad config;
+    `BuildUserCoinLaunchTxParams.expectedConfig?` passes the expectation.
+- **validate.ts pins every value-moving field to FORGE's settings**: no migration fee
+  (`MIGRATION_FEE_NOT_ALLOWED`), no locked vesting (`LOCKED_VESTING_NOT_ALLOWED`), the fixed supply
+  of `FORGE_TOKEN_SETTINGS` (`TOKEN_SUPPLY_MISMATCH`), FORGE's curve and start price
+  (`CURVE_MISMATCH`, they decide the leftover), SPL token with 6 decimals, timestamp activation,
+  and the anti-sniper schedule exactly `ANTI_SNIPER_FEE_SCHEDULE` (a flat linear fee when
+  `spec.antiSniper` is off): an exponential schedule, another starting fee or one 300 s period at
+  99% are refused.
+- The fixed settings moved to `settings.ts` (re-exported by config.ts, unchanged values), with
+  `FORGE_TOKEN_SUPPLY_RAW`, `forgeFeeSchedulerParam`, `forgeBaseFee`, `forgeReferenceCurve`.
+  `curveParamsFor`, `creatorTradingFeePercentageFor` and `poolCreationFeeSolFor` accept just the
+  spec fields they read (`ConfigSpecFields`); a full `LaunchpadSpec` still fits.
+- **Platform fee on a user coin's first buy.** `buildUserCoinLaunchTx` adds ONE SystemProgram
+  transfer of `platformFeeLamports(firstBuyLamports)` (30 bps, rounded up) to
+  `FORGE_PLATFORM_FEE_WALLET` (read from `env`), as the last instruction; `chargePlatformFee:
+  false` turns it off. The wallet must be rent-exempt (`PLATFORM_FEE_WALLET_NOT_READY`). The
+  summary gains `platformFeeLamports` and `platformFeeWallet`; `LaunchCoinCosts.platformFeeLamports`
+  (optional) is set and counted in `ownerTotalLamports`.
+- **Swaps.** `MAX_SWAP_SLIPPAGE_BPS` is 2,500 (25%, was 50%). `buildBuyTx`, `buildSellTx`,
+  `quoteSwap`, `fetchSwapContext` and `fetchSwapPoolState` take an optional `allowedConfigs`: a
+  pool whose on-chain config is not listed is refused (`POOL_NOT_ALLOWED`) before its config is
+  read. The builders now require the platform fee wallet to be exactly `FORGE_PLATFORM_FEE_WALLET`
+  and a system account (`PLATFORM_FEE_WALLET_MISMATCH`), and, when the environment has
+  `FORGE_MULTISIG_VAULT`, the Meteora referral token account to be held by it
+  (`REFERRAL_ACCOUNT_INVALID`). `buildSwapTransaction(ctx, request, expected?)`,
+  `assertPlatformFeeWalletReady(..., expectedWallet?)`, `assertReferralAccountReady(...,
+  expectedOwner?)`, new `assertPoolConfigAllowed`, `readOptionalAddress` (addresses.ts);
+  `swapFeeAddresses` also returns `multisigVault`.
 - `checkPaymentTransaction` / `verifyPayment`: `transferLamports` on `amount_mismatch` when the transfer amount differs.
+- Jupiter referral fee claim (`jupiter-referral.ts`, mainnet-beta only): `buildJupiterReferralClaimTx`
+  reads the referral account, its project and the two collection accounts of a mint (classic
+  `referral_ata` PDA and the referral account's associated token account) and builds the
+  permissionless `claim` / `claim_v2` instructions to the referral account's partner (the FORGE
+  multisig vault, asserted with `expectedPartner`). Raw instructions from the referral program IDL
+  (no Anchor dependency), with the pure pieces exported (`decodeJupiterReferralAccount`,
+  `decodeJupiterProject`, `deriveJupiterReferralTokenAccount[V2]`, `buildJupiterReferralClaimIx`,
+  `buildJupiterCreateAdminTokenAccountIx`). Any cluster but mainnet-beta is refused
+  (`JupiterReferralError` `wrong_cluster`). The summary also carries the project's `admin` and
+  `projectAuthority`, so a caller can pin every account of the built claim.
+- Squads accounts of the buyback read in addresses.ts (PLANEXECUTE rule 7): `FORGE_SQUADS_MULTISIG`
+  and `FORGE_SQUADS_SPENDING_LIMIT` join `FORGE_ADDRESS_NAMES` as optional names;
+  `readSquadsAddresses(env)` returns them with `FORGE_SQUADS_VAULT_INDEX` (default 0) or `null`
+  when both are absent, and refuses half a configuration, an index without them, an index outside
+  0..255 or a spending limit equal to the multisig (`ForgeSquadsConfigError`). Deriving the vault
+  needs the Squads program id: the signer keeps that check.
+
+### Added (DAMM v2 position fee claims)
+
+- `position-claims.ts`: after a launchpad coin migrates, the FORGE creator wallet keeps a
+  permanently locked DAMM v2 position that earns the migrated pool's trading fees.
+  `buildCreatorPositionFeeClaimTx` builds the unsigned `claim_position_fee` of the creator's
+  position(s) to a receiver (`buildForgeCreatorPositionFeeClaimTx`: the multisig vault), creator
+  signing, optional fee payer: coin fees to the receiver's associated account, SOL fees to the
+  creator's temporary WSOL account closed to the receiver (fees plus rent as lamports). The
+  transaction never removes liquidity nor closes, locks or transfers the position or its NFT.
+  Summary, costs (`PositionClaimCosts`), skip reasons (`no_position`, `nothing_to_claim`,
+  `not_worthwhile`), `isPositionClaimWorthwhile`. Pure helpers: `migratedDammV2Pool` (the DAMM v2
+  pool of a migrated DBC pool, derived like the SDK migration), `positionPendingFees`,
+  `summarizePosition`, `sumPendingFees`; reads: `findCreatorDammV2Positions` (the creator's
+  positions, NFT ownership re-checked), `getDammV2PoolState`. Constants for policies:
+  `DAMM_V2_PROGRAM_ID`, `CLAIM_POSITION_FEE_DISCRIMINATOR`, `CLAIM_POSITION_FEE_ACCOUNTS`.
+  New `ClaimError` codes: `not_migrated`, `damm_pool_not_found`, `damm_pool_mismatch`,
+  `position_not_found`, `position_mismatch`, `position_not_owned`.
+- Dependency: `@meteora-ag/cp-amm-sdk` 1.5.1 (exact pin, like the DBC SDK).
+- Fixtures: `__fixtures__/cp-amm-devnet-accounts.json`, the devnet test 2 migration captured
+  read-only (`scripts/devnet-tests` `fixtures:cp-amm`).
+
+## 0.1.0 — 2026-10-14
+
+First version published on npm as `@forgedevv/core` (with `@forgedevv/shared`), through
+`node scripts/publish-core.mjs --publish`.
+
+- `listCoinsOfCreator` (creator pools through SDK `getPoolsByCreator`), `DBC_POOL_CREATOR_OFFSET`, `DBC_POOL_CONFIG_OFFSET`.
 
 ### Changed (wave 5 review)
 

package/README.md

@@ -1,9 +1,10 @@
 # @forgedevv/core
 
 The FORGE transaction core: it builds the Meteora Dynamic Bonding Curve configs, the launchpad coin
-launch, buys and sells with the FORGE platform fee and referral, creator fee claims, payment checks
-and the read helpers used by FORGE launchpad sites. Every function that builds a transaction
-returns it **unsigned**: the user signs in their wallet.
+launch, buys and sells with the FORGE platform fee and referral, creator fee claims (bonding curve
+share, and the DAMM v2 position fees of a migrated pool), payment checks and the read helpers used
+by FORGE launchpad sites. Every function that builds a transaction returns it **unsigned**: the
+user signs in their wallet.
 
 Inside the FORGE monorepo this package is `@forge/core`. It is published on the public npm registry
 as `@forgedevv/core` (with its contracts package `@forgedevv/shared`), and client projects install

package/dist/addresses.d.ts

@@ -9,17 +9,26 @@
  * Validation choice: a value is valid when the `PublicKey` constructor accepts it (base58 that
  * decodes to exactly 32 bytes) and it re-encodes to the same string. Being on the ed25519 curve is
  * NOT required, because some of these addresses are token accounts or PDAs (e.g. the Meteora
- * referral account, which is a WSOL token account held by the multisig, or a Squads vault PDA).
+ * referral account, which is a WSOL token account held by the revenue wallet, or a Squads vault
+ * PDA).
+ *
+ * The revenue wallet (`FORGE_REVENUE_WALLET`, docs/DECISIONS.md D34) is the signer-held wallet
+ * where the non-native trading revenue lands: the platform fee (`FORGE_PLATFORM_FEE_WALLET` must
+ * be that wallet), the Meteora referral WSOL account it holds, and the Jupiter referral claims
+ * (it is the referral account's partner). The signer converts and forwards it to the vault.
  * The all-zero key (`11111111111111111111111111111111`, the System Program) is rejected: fees
  * sent there would be lost.
  *
  * Error messages list variable names only, never values.
  */
 import { PublicKey } from '@solana/web3.js';
-export declare const FORGE_ADDRESS_NAMES: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "FORGE_CASHBOX_WALLET", "FORGE_MINT"];
+export declare const FORGE_ADDRESS_NAMES: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_REVENUE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "FORGE_CASHBOX_WALLET", "FORGE_MINT", "FORGE_SQUADS_MULTISIG", "FORGE_SQUADS_SPENDING_LIMIT"];
 export type ForgeAddressName = (typeof FORGE_ADDRESS_NAMES)[number];
-/** Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch. */
-export declare const OPTIONAL_FORGE_ADDRESS_NAMES: readonly ["FORGE_MINT"];
+/**
+ * Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch; the Squads
+ * accounts are absent while the buyback stays in simulation (see `readSquadsAddresses`).
+ */
+export declare const OPTIONAL_FORGE_ADDRESS_NAMES: readonly ["FORGE_MINT", "FORGE_SQUADS_MULTISIG", "FORGE_SQUADS_SPENDING_LIMIT"];
 export type OptionalForgeAddressName = (typeof OPTIONAL_FORGE_ADDRESS_NAMES)[number];
 /** Environment object to read from (defaults to `process.env`; injectable for tests). */
 export type AddressEnv = Readonly<Record<string, string | undefined>>;
@@ -41,15 +50,72 @@ export declare class ForgeAddressError extends Error {
  * @throws ForgeAddressError listing the missing and invalid names (never the values).
  */
 export declare function requireAddresses<N extends ForgeAddressName>(names: readonly N[], env?: AddressEnv): ForgeAddresses<N>;
-/** Squads multisig vault: receives the creator fees, the Meteora referral and the cashbox sweeps. */
+/**
+ * One FORGE address when it is set, `null` when it is absent or empty. A value that is set but is
+ * not a valid public key is refused, exactly as `requireAddresses` does. For checks that run
+ * wherever the address is known and are skipped elsewhere (e.g. the owner of the Meteora referral
+ * account, `FORGE_REVENUE_WALLET`, in a browser that was not given it).
+ *
+ * @throws ForgeAddressError (invalid value; names only).
+ */
+export declare function readOptionalAddress(name: ForgeAddressName, env?: AddressEnv): PublicKey | null;
+/**
+ * Squads multisig vault: receives the creator fees, the cashbox sweeps and the revenue wallet's
+ * forwards (the converted trading revenue).
+ */
 export declare function getMultisigVault(env?: AddressEnv): PublicKey;
-/** Meteora referral token account (WSOL, held by the multisig), passed as `referralTokenAccount`. */
+/** Meteora referral token account (WSOL, held by the revenue wallet), passed as `referralTokenAccount`. */
 export declare function getMeteoraReferralAccount(env?: AddressEnv): PublicKey;
-/** Wallet receiving the 0.3% platform fee on swaps built by @forge/core. */
+/**
+ * Wallet receiving the 0.3% platform fee on swaps built by @forge/core: the revenue wallet
+ * (`FORGE_REVENUE_WALLET`, D34). Kept as its own variable so the fee destination stays explicit;
+ * `swapFeeAddresses` refuses an environment where the two differ.
+ */
 export declare function getPlatformFeeWallet(env?: AddressEnv): PublicKey;
+/**
+ * Revenue wallet (D34): held by the signer (keystore role `revenue`), it receives the platform
+ * fee, holds the Meteora referral WSOL account and is the partner of the Jupiter referral
+ * account. The signer regularly converts what it holds to SOL and forwards it to the vault.
+ */
+export declare function getRevenueWallet(env?: AddressEnv): PublicKey;
 /** Jupiter referral account (integrator fee after graduation). */
 export declare function getJupiterReferralAccount(env?: AddressEnv): PublicKey;
 /** Cashbox wallet (held by the signer) receiving client payments. */
 export declare function getCashboxWallet(env?: AddressEnv): PublicKey;
 /** $FORGE mint, or `null` before the $FORGE launch (token-gating off, buyback simulated). */
 export declare function getForgeMint(env?: AddressEnv): PublicKey | null;
+/** Squads v4 accounts the buyback withdraws through, read from the environment. */
+export interface SquadsAddresses {
+    /** FORGE_SQUADS_MULTISIG: the multisig account. */
+    multisig: PublicKey;
+    /** FORGE_SQUADS_SPENDING_LIMIT: the spending limit account of the buyback wallet. */
+    spendingLimit: PublicKey;
+    /** FORGE_SQUADS_VAULT_INDEX (default 0): the vault index of the treasury vault. */
+    vaultIndex: number;
+}
+export type SquadsAddressProblem = 
+/** One of the two addresses without the other. */
+'incomplete'
+/** FORGE_SQUADS_VAULT_INDEX other than the default 0 without the addresses. */
+ | 'index_without_multisig'
+/** FORGE_SQUADS_VAULT_INDEX is not an integer between 0 and 255. */
+ | 'invalid_index'
+/** The spending limit account is the multisig account. */
+ | 'not_distinct';
+/** Thrown by `readSquadsAddresses` on a rule the names alone cannot express. Names only. */
+export declare class ForgeSquadsConfigError extends Error {
+    readonly problem: SquadsAddressProblem;
+    constructor(problem: SquadsAddressProblem, message: string);
+}
+/**
+ * FORGE_SQUADS_MULTISIG, FORGE_SQUADS_SPENDING_LIMIT and FORGE_SQUADS_VAULT_INDEX. Returns `null`
+ * when both addresses are absent (no withdrawer: the buyback stays in simulation). Rules: the
+ * two addresses are set together or not at all; an index other than the default `0` needs them
+ * (a lone `0` is the default spelled out, not a configuration); the index is an integer between
+ * 0 and 255 (default 0); the spending limit is a distinct account. Deriving the vault from the
+ * multisig and the index, and comparing it with FORGE_MULTISIG_VAULT, needs the Squads program
+ * id (pinned SDK): the caller (the signer) does it.
+ *
+ * @throws ForgeAddressError (invalid address, names only), ForgeSquadsConfigError (other rules).
+ */
+export declare function readSquadsAddresses(env?: AddressEnv): SquadsAddresses | null;

package/dist/addresses.js

@@ -9,7 +9,13 @@
  * Validation choice: a value is valid when the `PublicKey` constructor accepts it (base58 that
  * decodes to exactly 32 bytes) and it re-encodes to the same string. Being on the ed25519 curve is
  * NOT required, because some of these addresses are token accounts or PDAs (e.g. the Meteora
- * referral account, which is a WSOL token account held by the multisig, or a Squads vault PDA).
+ * referral account, which is a WSOL token account held by the revenue wallet, or a Squads vault
+ * PDA).
+ *
+ * The revenue wallet (`FORGE_REVENUE_WALLET`, docs/DECISIONS.md D34) is the signer-held wallet
+ * where the non-native trading revenue lands: the platform fee (`FORGE_PLATFORM_FEE_WALLET` must
+ * be that wallet), the Meteora referral WSOL account it holds, and the Jupiter referral claims
+ * (it is the referral account's partner). The signer converts and forwards it to the vault.
  * The all-zero key (`11111111111111111111111111111111`, the System Program) is rejected: fees
  * sent there would be lost.
  *
@@ -20,13 +26,21 @@ export const FORGE_ADDRESS_NAMES = [
     'FORGE_MULTISIG_VAULT',
     'FORGE_METEORA_REFERRAL_ACCOUNT',
     'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_REVENUE_WALLET',
     'FORGE_JUPITER_REFERRAL_ACCOUNT',
     'FORGE_CASHBOX_WALLET',
     'FORGE_MINT',
+    'FORGE_SQUADS_MULTISIG',
+    'FORGE_SQUADS_SPENDING_LIMIT',
 ];
-/** Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch. */
+/**
+ * Addresses that may be absent. `FORGE_MINT` is absent before the $FORGE launch; the Squads
+ * accounts are absent while the buyback stays in simulation (see `readSquadsAddresses`).
+ */
 export const OPTIONAL_FORGE_ADDRESS_NAMES = [
     'FORGE_MINT',
+    'FORGE_SQUADS_MULTISIG',
+    'FORGE_SQUADS_SPENDING_LIMIT',
 ];
 /** Thrown when required addresses are missing or invalid. Holds names only, never values. */
 export class ForgeAddressError extends Error {
@@ -101,18 +115,47 @@ export function requireAddresses(names, env = defaultEnv()) {
         throw new ForgeAddressError(missing, invalid);
     return result;
 }
-/** Squads multisig vault: receives the creator fees, the Meteora referral and the cashbox sweeps. */
+/**
+ * One FORGE address when it is set, `null` when it is absent or empty. A value that is set but is
+ * not a valid public key is refused, exactly as `requireAddresses` does. For checks that run
+ * wherever the address is known and are skipped elsewhere (e.g. the owner of the Meteora referral
+ * account, `FORGE_REVENUE_WALLET`, in a browser that was not given it).
+ *
+ * @throws ForgeAddressError (invalid value; names only).
+ */
+export function readOptionalAddress(name, env = defaultEnv()) {
+    const value = env[name];
+    if (value === undefined || value === '')
+        return null;
+    return requireAddresses([name], env)[name];
+}
+/**
+ * Squads multisig vault: receives the creator fees, the cashbox sweeps and the revenue wallet's
+ * forwards (the converted trading revenue).
+ */
 export function getMultisigVault(env) {
     return requireAddresses(['FORGE_MULTISIG_VAULT'], env).FORGE_MULTISIG_VAULT;
 }
-/** Meteora referral token account (WSOL, held by the multisig), passed as `referralTokenAccount`. */
+/** Meteora referral token account (WSOL, held by the revenue wallet), passed as `referralTokenAccount`. */
 export function getMeteoraReferralAccount(env) {
     return requireAddresses(['FORGE_METEORA_REFERRAL_ACCOUNT'], env).FORGE_METEORA_REFERRAL_ACCOUNT;
 }
-/** Wallet receiving the 0.3% platform fee on swaps built by @forge/core. */
+/**
+ * Wallet receiving the 0.3% platform fee on swaps built by @forge/core: the revenue wallet
+ * (`FORGE_REVENUE_WALLET`, D34). Kept as its own variable so the fee destination stays explicit;
+ * `swapFeeAddresses` refuses an environment where the two differ.
+ */
 export function getPlatformFeeWallet(env) {
     return requireAddresses(['FORGE_PLATFORM_FEE_WALLET'], env).FORGE_PLATFORM_FEE_WALLET;
 }
+/**
+ * Revenue wallet (D34): held by the signer (keystore role `revenue`), it receives the platform
+ * fee, holds the Meteora referral WSOL account and is the partner of the Jupiter referral
+ * account. The signer regularly converts what it holds to SOL and forwards it to the vault.
+ */
+export function getRevenueWallet(env) {
+    return requireAddresses(['FORGE_REVENUE_WALLET'], env).FORGE_REVENUE_WALLET;
+}
 /** Jupiter referral account (integrator fee after graduation). */
 export function getJupiterReferralAccount(env) {
     return requireAddresses(['FORGE_JUPITER_REFERRAL_ACCOUNT'], env).FORGE_JUPITER_REFERRAL_ACCOUNT;
@@ -125,3 +168,51 @@ export function getCashboxWallet(env) {
 export function getForgeMint(env) {
     return requireAddresses(['FORGE_MINT'], env).FORGE_MINT;
 }
+/** Thrown by `readSquadsAddresses` on a rule the names alone cannot express. Names only. */
+export class ForgeSquadsConfigError extends Error {
+    problem;
+    constructor(problem, message) {
+        super(message);
+        this.name = 'ForgeSquadsConfigError';
+        this.problem = problem;
+    }
+}
+const VAULT_INDEX_RE = /^(0|[1-9][0-9]?|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;
+/**
+ * FORGE_SQUADS_MULTISIG, FORGE_SQUADS_SPENDING_LIMIT and FORGE_SQUADS_VAULT_INDEX. Returns `null`
+ * when both addresses are absent (no withdrawer: the buyback stays in simulation). Rules: the
+ * two addresses are set together or not at all; an index other than the default `0` needs them
+ * (a lone `0` is the default spelled out, not a configuration); the index is an integer between
+ * 0 and 255 (default 0); the spending limit is a distinct account. Deriving the vault from the
+ * multisig and the index, and comparing it with FORGE_MULTISIG_VAULT, needs the Squads program
+ * id (pinned SDK): the caller (the signer) does it.
+ *
+ * @throws ForgeAddressError (invalid address, names only), ForgeSquadsConfigError (other rules).
+ */
+export function readSquadsAddresses(env = defaultEnv()) {
+    const multisigRaw = env.FORGE_SQUADS_MULTISIG ?? '';
+    const limitRaw = env.FORGE_SQUADS_SPENDING_LIMIT ?? '';
+    const indexRaw = env.FORGE_SQUADS_VAULT_INDEX ?? '';
+    if (multisigRaw === '' && limitRaw === '') {
+        if (indexRaw !== '' && indexRaw !== '0') {
+            throw new ForgeSquadsConfigError('index_without_multisig', 'FORGE_SQUADS_VAULT_INDEX needs FORGE_SQUADS_MULTISIG');
+        }
+        return null;
+    }
+    if (multisigRaw === '' || limitRaw === '') {
+        throw new ForgeSquadsConfigError('incomplete', 'FORGE_SQUADS_MULTISIG and FORGE_SQUADS_SPENDING_LIMIT must be set together');
+    }
+    const multisig = readOptionalAddress('FORGE_SQUADS_MULTISIG', env);
+    const spendingLimit = readOptionalAddress('FORGE_SQUADS_SPENDING_LIMIT', env);
+    let vaultIndex = 0;
+    if (indexRaw !== '') {
+        if (!VAULT_INDEX_RE.test(indexRaw)) {
+            throw new ForgeSquadsConfigError('invalid_index', 'FORGE_SQUADS_VAULT_INDEX must be an integer between 0 and 255');
+        }
+        vaultIndex = Number(indexRaw);
+    }
+    if (spendingLimit.equals(multisig)) {
+        throw new ForgeSquadsConfigError('not_distinct', 'FORGE_SQUADS_SPENDING_LIMIT must be a distinct account');
+    }
+    return { multisig, spendingLimit, vaultIndex };
+}

package/dist/claims.d.ts

@@ -1,10 +1,19 @@
-import { PublicKey, Transaction, type Commitment, type Connection } from '@solana/web3.js';
+import { PublicKey, Transaction, type Commitment, type Connection, type TransactionInstruction } from '@solana/web3.js';
 import { type AddressEnv } from './addresses.js';
-import { type RetryOptions, type TokenAmounts } from './reads.js';
-/** Base fee per signature (lamports); claims set no priority fee. */
+import { type PriorityFeeQuote, type PriorityFeeSetting } from './priority-fee.js';
+import { type DbcPoolState, type RetryOptions, type TokenAmounts } from './reads.js';
+/** Base fee per signature (lamports); a priority fee comes on top with `ClaimOptions.priority`. */
 export declare const CLAIM_LAMPORTS_PER_SIGNATURE = 5000n;
+/**
+ * Compute unit limit of a trading fee claim with a priority fee: two idempotent token account
+ * creations (about 25,000 CU each when they create), the DBC claim (two token transfers and its
+ * event), a token self-transfer, a close and a SOL transfer, about 100,000 CU at most: 2x margin.
+ */
+export declare const CLAIM_COMPUTE_UNITS = 200000;
+/** Compute unit limit of a pool creation fee claim (one DBC instruction moving lamports). */
+export declare const POOL_CREATION_FEE_CLAIM_COMPUTE_UNITS = 100000;
 export { PARTNER_POOL_CREATION_FEE_CLAIMED_BIT, partnerPoolCreationFeeShare } from './reads.js';
-export type ClaimErrorCode = 'not_pool_creator' | 'not_fee_claimer' | 'unsupported_quote_mint' | 'invalid_receiver' | 'receiver_mismatch' | 'receiver_not_rent_exempt' | 'claimer_wsol_not_empty' | 'unexpected_sdk_instructions';
+export type ClaimErrorCode = 'not_pool_creator' | 'not_fee_claimer' | 'unsupported_quote_mint' | 'invalid_receiver' | 'receiver_mismatch' | 'receiver_not_rent_exempt' | 'claimer_wsol_not_empty' | 'unexpected_sdk_instructions' | 'not_migrated' | 'damm_pool_not_found' | 'damm_pool_mismatch' | 'position_not_found' | 'position_mismatch' | 'position_not_owned';
 export declare class ClaimError extends Error {
     readonly code: ClaimErrorCode;
     constructor(code: ClaimErrorCode, message: string);
@@ -12,7 +21,7 @@ export declare class ClaimError extends Error {
 export type ClaimKind = 'creator' | 'partner';
 /** Lamport costs of a trading fee claim, as bigint. */
 export interface ClaimCosts {
-    /** Signature fees (signers x 5000 lamports; no priority fee), paid by the payer. */
+    /** Signature fees (signers x 5000 lamports) plus the priority fee, if any; paid by the payer. */
     networkFeeLamports: bigint;
     /**
      * Rent of the receiver's coin account, created on the first claim of a pool (paid by the payer,
@@ -43,6 +52,12 @@ export interface ClaimSummary {
      */
     receiverQuoteLamports: bigint;
     quoteIsExact: boolean;
+    /**
+     * WSOL the claimer's temporary account already held when the transaction was built and that
+     * the close hands to the receiver (counted in `receiverQuoteLamports`). Zero when the account
+     * is empty or new, and when the close returns it to a claimer paying its own claim.
+     */
+    existingWsolLamports: bigint;
     /** Zero costs when there is no transaction. */
     costs: ClaimCosts;
     /**
@@ -50,6 +65,8 @@ export interface ClaimSummary {
      * costs are paid (negative when it costs more than it collects). Base tokens are not valued.
      */
     netLamports: bigint;
+    /** The priority fee of the transaction (price, fee, cap), or null without one. */
+    priorityFee: PriorityFeeQuote | null;
 }
 export type ClaimSkipReason = 'nothing_to_claim' | 'not_worthwhile';
 export interface ClaimTxResult {
@@ -69,7 +86,21 @@ export interface ClaimOptions {
      * than this many lamports (see `isClaimWorthwhile`). Default: never skip a non-empty claim.
      */
     minNetLamports?: bigint;
+    /**
+     * Priority fee read from the cluster for the claim's writable accounts, bounded by this setting
+     * (`{}` = `DEFAULT_PRIORITY_FEE_POLICY`, at most 0.0005 SOL). Default: none.
+     */
+    priority?: PriorityFeeSetting;
 }
+/** Checks `options.priority` before any network call. @throws RangeError. */
+export declare function assertClaimPriority(options: {
+    priority?: PriorityFeeSetting;
+}): void;
+/** The priced compute budget of a claim, or nothing without `priority`. */
+export declare function claimPriorityFee(connection: Connection, instructions: readonly TransactionInstruction[], computeUnitLimit: number, priority: PriorityFeeSetting | undefined): Promise<{
+    quote: PriorityFeeQuote | null;
+    instructions: TransactionInstruction[];
+}>;
 export interface CreatorClaimParams {
     pool: PublicKey;
     /** Pool creator (must match the pool state); signs the claim. */
@@ -100,6 +131,10 @@ export declare function minimumWorthwhileClaimLamports(costs: ClaimCosts, minNet
  * callers skip claims below it. Base tokens are not valued (FORGE configs collect SOL fees only).
  */
 export declare function isClaimWorthwhile(summary: ClaimSummary, minNetLamports?: bigint): boolean;
+/** @throws ClaimError `unsupported_quote_mint` unless the pool is quoted in SOL. */
+export declare function assertSolQuotedPool(state: DbcPoolState): void;
+/** @throws ClaimError `invalid_receiver` for anything but a usable wallet address. */
+export declare function assertClaimReceiver(receiver: PublicKey): void;
 /**
  * Builds the creator claim of `pool` to `receiver` (see the module comment for the transaction).
  * @throws ClaimError when `creator` is not the pool creator, the pool is not SOL-quoted, the
@@ -153,10 +188,12 @@ export interface PoolCreationFeeClaimSummary {
     alreadyClaimed: boolean;
     /** SOL the receiver gets from the transaction (0 when there is none), lamports. */
     claimableLamports: bigint;
-    /** Signature fees of the transaction (0 when there is none), paid by the payer. */
+    /** Signature fees plus the priority fee of the transaction (0 when there is none). */
     networkFeeLamports: bigint;
     /** `claimableLamports - networkFeeLamports` (0 when there is no transaction). */
     netLamports: bigint;
+    /** The priority fee of the transaction (price, fee, cap), or null without one. */
+    priorityFee: PriorityFeeQuote | null;
 }
 export type PoolCreationFeeSkipReason = 'no_pool_creation_fee' | 'already_claimed';
 export interface PoolCreationFeeClaimTxResult {