2 Commits

Include renames

Author	SHA1	Message	Date
3 people	75d9087d05	feat(cookbook): launch any coin create_v2 supports, as a v0 or a v1 transaction (#234) ... * feat(cookbook): cover every create_v2 coin parameter in the launch scripts Both create scripts now build create_v2 through pumpfun_instructions_v2 instead of each carrying their own copy of the discriminators, PDAs and account list. - A holder-reward coin's curve creator is derived rather than assumed, so the opening buy finds the matching creator vault instead of reverting. - create_v2's three trailing arguments are settable independently. None omits an argument, a value sends it, so all four wire forms are reachable and an explicit default is distinct from an omission. - create_v2 carries all four remaining accounts, quote_control included. Without them the program ignores creator_fee_bps. - --creator, --creator-fee-bps and --quote-mint added. A creator fee on a SOL-paired coin warns, because the program stores zero for it; the create-and-buy script refuses one outright before sending anything. - The opening buy is sized from Global's reserves and fee rates. - Mayhem mode is off by default. Removes the fee-recipient lookup whose result was discarded and the buy wrapper whose parameters were unused. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(regression): verify the launch path's create_v2 arguments Eight offline checks: the substituted creator on a holder-reward coin, every committed create_v2 fixture round-tripping through the trailing argument encoder, all four wire forms being reachable, --creator reaching the wire, the opening buy following Global rather than constants, the Global decoder stopping cleanly on a short buffer, and the four quote accounts being present with the ATA under the quote mint's own program. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: correct create_v2's remaining accounts and the creator-fee rule create_v2 takes four remaining accounts, not three; the fourth is the QuoteControl PDA. Omitting them is accepted and yields a SOL-paired coin, which is also how a creator fee goes missing: the program applies creator_fee_bps only to a coin priced in something other than SOL, and otherwise stores zero without an error. Also records that solders documents TransactionConfig.priority_fee as micro-lamports while SIMD-0385 defines the field as total lamports. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): price a new coin in an asset other than SOL --quote-mint on both create scripts, checked against both registries that admit a quote asset. QuoteControl carries most of them with a per-mint opening reserve; Global.whitelisted_quote_mints carries USDC, which QuoteControl does not list, so consulting either alone refuses a mint the program accepts. A mint neither admits is refused rather than priced from a default, since the opening reserve spans orders of magnitude. The quote mint's token program and decimals are resolved from chain, and --amount is denominated in the quote asset rather than in SOL. A paused mint is refused before anything is sent, and a scaled-UI mint says so, because amounts here are raw units. A creator fee now works, since pump.fun applies one only to a coin priced in something other than SOL. On a SOL-paired coin it is refused instead of being accepted and stored as zero. The create-and-buy script requires the wallet to already hold the quote asset; it does not acquire one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): launch a coin in one v1 transaction Create, extend, the buyer's token account and the buy now travel under a single signature, so nobody can buy between the create and the opening buy. They were split because the two together are 1479 bytes against the 1232 a v0 transaction is held to; SIMD-0296 raised the limit to 4096 for v1 and the combined message uses about a third of it. v1 has no address lookup tables -- the larger limit exists so the whole account list goes inline -- and it carries the compute budget in the message header, so the script sends no ComputeBudget instructions. The priority fee is now one total in lamports rather than micro-lamports per compute unit; the constant is converted, not renamed. The two-transaction path is removed rather than kept behind a flag. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): state the loaded-accounts data size limit on the v1 launch A v1 message carries this limit in its header, and left unset it is zero rather than the network default, so the runtime rejects the transaction for exceeding it. The launch skips preflight, so the rejection never reached the caller: send returned a signature that never landed. Measured against a forked mainnet, the launch is rejected at 128 KiB and lands at 256 KiB. The limit is set to 1 MiB, which leaves room for a quote mint whose accounts are larger, and the verifier fails if it is dropped or set at or below the measured failing size. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): offer the launch as a v0 or a v1 transaction The Solana transaction version changes what a launch can be, so it is the script that changes rather than a flag on one of them. _txv1 sends create and buy under a single signature, so the coin is bought by the transaction that creates it. _txv0 sends them as two transactions, because together they do not fit what a v0 transaction can carry, and anyone watching the create can buy in the gap. Use it when the endpoint will not take a v1 send. The coin is identical either way: quote asset, creator fee, holder rewards and mayhem mode all behave the same. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(cookbook): drop the instruction version from script names The cookbook ships one form of each pump.fun action, so `_v2` in a basename distinguished nothing — and it read as a Solana transaction version, which is a different thing and now appears in the same names. `pumpfun_buy_token_exact_sol_in.py` already went without it. Every trade script loses the suffix, the shared module becomes `pumpfun_instructions.py`, and the retired path is named for what it is rather than for the instruction set it uses. The instruction each script builds is named in its docstring, where it cannot be mistaken for a transaction version. `txv0`/`txv1` is now the only version marker in any filename, and it is the one the reader chooses between. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): refuse mayhem mode paired with a non-SOL quote asset The program rejects the pairing with MayhemModeQuoteMintNotAllowed (6071), so a mayhem coin is always SOL-paired — and therefore can never carry a creator fee, which needs a non-SOL quote. Both create scripts now refuse the combination before sending, rather than letting it land as a reverted transaction that has already cost fees. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): size the v1 loaded-accounts limit for what mainnet loads The limit counts the executable data of every program a transaction touches, not just the accounts it names, and the pump program's own code is the bulk of it. The previous figure was set against a local fork, which does not charge for executables; on mainnet the launch was rejected with MaxLoadedAccountsDataSizeExceeded. Set to the network default a v0 transaction gets when nothing narrows it, which is the behaviour being reproduced. The verifier now holds the mainnet figure as its floor. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): a creator fee needs a QuoteControl quote mint, not just a non-SOL one Measured on mainnet: the fee is applied on a coin priced in a mint QuoteControl admits, whether that mint is SPL Token or Token-2022, and is not applied on wrapped SOL or on USDC — which the older Global whitelist carries and QuoteControl does not. The deciding property is registry membership, so the previous check let a USDC-priced coin through and the program stored zero without an error. Also stops the sell script calling a price "SOL" when the curve is priced in something else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): offer the create-only script as a v0 or a v1 transaction Same split as the create-and-buy pair, for the same reason: the Solana transaction version is the reader's choice, so it is the script that changes rather than a flag. _txv1 carries the compute budget in the message header and sends no ComputeBudget instructions; _txv0 sends them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): refuse a paused quote mint on the create-and-buy path too The check only ran in the create-only scripts, so a launch that also buys could reach the chain with a quote mint whose transfers are paused. On the two-transaction path that leaves a created coin nobody bought, after the create has already cost rent. Also corrects the v1 script's run docstring, which still described two transactions and a spend denominated in SOL. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): say --amount is in whole quote units, not raw ones The scaled-UI notice told the reader the opposite of what the scripts do: --amount is multiplied by the mint's decimals, so it is a whole-token figure. A reader who followed the notice would have overspent by a factor of the decimals. Reworded so the multiplier is described as what it is — a display scale a wallet applies — rather than as something the amount has to account for. The create-only scripts carried the same wording without even taking an amount. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-28 08:48:31 +02:00
3 people	41b971147a	refactor(cookbook): restructure learning-examples, add missing actions, fix quote decimals (#216) ... * refactor(tests): move the regression verifiers into tests/regression verify_*.py are not standalone examples: each imports src/, stubs the RPC client, and asserts one previously fixed bug stays fixed. Their checks are unchanged; PROJECT_ROOT, the usage lines and the bonk fixture lookup are adjusted for the new depth. run_all.py runs the set and reports failures. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(tools): move the dev harness and listener benchmarks into tools/ simulate_*, live_*, both compare_* scripts and the account cleanup import src/ and several spend real funds — they exercise the bot rather than teach anything. compare_listeners.py reaches the repo root one level higher than before; nothing else changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(cookbook): reorganise learning-examples into cookbook/ The directory is a reference collection — one runnable script per action — but nothing said so: no index, scripts grouped by the transport they happened to use, fixtures loose at the root. Now grouped by platform, then by what you are doing: pumpfun/{listen,read,trade,graduation,decode}, pumpswap, letsbonk, legacy. Fixtures sit beside the script that reads them, manual_sell.py becomes sell_token.py, and the legacy create example moves to legacy/ and says why. pump_v2.py and tx_status.py stay at the cookbook root as the only two shared helpers; subdirectories add that root to sys.path before importing them. cookbook/README.md indexes every script and marks the ones that spend funds. Also fixes create_v2's account list: the five mayhem accounts are mandatory whatever is_mayhem_mode says, so mint_and_buy_v2.py could never have worked with mayhem off. 11 accounts fails AnchorError 3005 (AccountNotEnoughKeys) on sol_vault, 16 succeeds with the argument either way — simulateTransaction against mainnet. Seven scripts gain a module docstring they were missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): add buy, create, balance and status examples buy_token.py <MINT> buy_v2 against one coin; --dry-run simulates create_token.py create_v2 on its own get_balances.py SOL and tokens across both token programs check_tx_status.py <SIG> success, reverted, or not visible yet Buying previously meant manual_buy.py, which waits for the next coin created anywhere before it trades — there was no way to buy a coin you already know. Creating one meant bundling a buy with it, and the transaction-status helper was a library with no entry point. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(cookbook): move pump_v2 next to the scripts that use it pump_v2.py holds the buy_v2/sell_v2 account layouts, and only the pump.fun trade scripts import it — it sat at the cookbook root because tx_status.py does, not because anything outside pumpfun/trade/ needed it. The five callers now pick it up as a plain sibling; legacy/ and the layout verifier reach into that directory. tx_status.py stays at the root, where all four platforms use it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(cookbook): name every script protocol_verb_noun_variant manual_buy.py did not just buy — it waited for the next coin created anywhere, then bought, so the verb was wrong. Protocol was encoded three different ways: directory, suffix, or not at all. And three scripts sat under pumpfun/ that have nothing to do with pump.fun. Filenames are now <protocol>_<verb>_<noun>[_<variant>].py, so a basename says which chain, what it does and which instruction version without opening it: manual_buy.py -> pumpfun_snipe_token_blocksubscribe.py manual_buy_geyser.py -> pumpfun_snipe_token_geyser.py buy_token.py -> pumpfun_buy_token_v2.py mint_and_buy_v2.py -> pumpfun_create_and_buy_token_v2.py manual_buy_pumpswap.py -> pumpswap_buy_token.py manual_buy_exact_in.py -> letsbonk_buy_token_exact_in.py legacy/mint_and_buy.py -> legacy/pumpfun_create_and_buy_token_v1.py The sniper was named for logsSubscribe in an earlier draft; it sends blockSubscribe, and the name now says so. Balances, transaction status and the Anchor discriminator calculator are not pump.fun-specific and move to a new cookbook/solana/. The two non-runnable helpers take no verb — pump_v2.py becomes pumpfun_instructions_v2.py beside its callers, tx_status.py becomes solana_transaction_status.py in solana/. Both are imported under a short alias so the 106 call sites stay readable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): resolve a coin's quote mint before pricing it quote_units() defaulted to 9 decimals for an unresolved mint, and every trade script called it before resolve_quote_token_program() warmed the decimals cache. pump.fun's QuoteControl registry admits mints at 6, 8 and 9 decimals — 79 of the 170 admitted are tokenized equities, 8 decimals for xStocks and 6 for Backpack Securities — so those coins were sized against the wrong power of ten. The error compounds rather than cancels: price_per_token() divides by the same wrong unit, so the price reads low by the factor, the token amount comes out high by it, and the inflated cap authorises the overspend instead of catching it. 10x on an xStock pair, 1000x on a Backpack one. This is not hypothetical. A 75s sample of live curve updates on 2026-09-22 caught 8 stock-paired curves out of 124 — IONQ across 5 of them, plus QUBT, PLTRx and COPX. quote_units() now raises for an unresolved mint instead of guessing, the four trade paths resolve before they price, and pumpfun_read_price.py reads decimals from chain rather than from a two-entry table. The geyser sniper never resolved at all: it also passed SPL Token as the quote token program, which fails the account constraints for any Token-2022 quote, and created no quote ATA. verify_quote_decimals_resolved.py checks the fail-closed contract, that resolution costs no extra RPC call, and that no function prices before it resolves — confirmed to fail when the ordering is put back. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * feat(cookbook): read the quote-mint registry and Token-2022 mint state Two reads that were unreachable without knowing an undocumented PDA seed. pumpfun_read_quote_mints.py decodes QuoteControl (PDA ["quote-control"]), the second quote-mint registry added in the 2026-09-15 upgrade. Reading only Global.whitelisted_quote_mints under-reports: a coin can be paired with a mint Global has never heard of. 170 admitted today, 79 of them tokenized equities, each with the initial virtual quote reserves that set a new curve's opening price. --stocks narrows to the equities, identified by the Token-2022 extension set create_v2 requires of them rather than by a name lookup. solana_read_token2022_mint.py reads the extensions that change what a balance means: scaled UI amount, pausable, permanent delegate, transfer hook, default account state. It exists mainly for one trap — the RPC returns both `multiplier` and `newMultiplier` with an effective timestamp, and once that timestamp passes the field named `multiplier` is the stale one. On AAPLx it passed on 2026-08-08, so the obvious field has been wrong for six weeks. This compares against the clock and says which is in force. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * feat(cookbook): add the exact-quote-in buy buy_exact_quote_in_v2 was uncovered. It is the mirror of buy_v2 — buy_v2 fixes the tokens received and caps the spend, this fixes the spend and floors the tokens — and it takes the same 27 accounts in the same order, so it reuses build_v2_accounts and differs only in discriminator and arguments. Worth having because pinning the spend is the natural direction once a coin is priced in something other than SOL: "spend exactly one AAPLx" is something you can mean, where a token count is a number derived from a price that moved while you derived it. Verified by simulateTransaction against a live COPX-paired coin: the program executes the full buy and stops at TransferChecked with insufficient funds, which is as far as a wallet holding none of the quote asset can go. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * feat(cookbook): add the exact-SOL-in buy buy_exact_sol_in was uncovered. SOL only — it pre-dates non-SOL quote assets and carries no quote accounts, so the script checks the curve and points at the exact-quote version for anything else rather than failing obscurely. Its account list is the reason to have it. The IDL lists 16; the program needs 18, the extras being the bonding-curve-v2 PDA and a buyback fee recipient. Determined by simulation rather than assumed: 16 accounts fails AnchorError 6062 (BuybackFeeRecipientMissing), 18 simulates clean at 96k CU. The v2 instructions are complete in the IDL and this family is not, which is worth a newcomer knowing before they trust the file. The docstring carries the IDL's own fee arithmetic, since fees come out of the amount you name rather than on top of it, and the printed estimate ignores that split while min_tokens_out is what the program enforces. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * feat(cookbook): add the creator-fee and cashback payouts Two payout paths that had no script. Both take no arguments and, per the IDL, no signer — the funds can only reach the wallet they already belong to, so either can be run for anyone, which --creator and --user expose. collect_creator_fee_v2 sweeps a creator vault. The vault is per creator and per quote asset, so a creator whose coins are priced in several assets collects each separately; --quote picks which. claim_cashback_v2 pays out an accrued cashback balance. create_v2 has rejected new cashback coins since 2026-09-15 (error 6082), but coins minted before that keep accruing and stay claimable, which is why the cashback handling elsewhere in this repo is not dead code. Both verified by simulateTransaction against mainnet: 10 accounts each, 8 data bytes, no error. Also repairs two cookbook README rows that the earlier rename mangled — pumpswap_buy_token.py had been rewritten to pumpswap_pumpfun_buy_token_v2.py because its name contains the string that rename matched on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * refactor(cookbook): take every script's input on the command line A reference collection only works if you can run a script against your own coin without editing it. Several carried the coin as a module-level constant instead: TOKEN_MINT = Pubkey.from_string(sys.argv[1] if len(sys.argv) > 1 else "...") which reads as optional but raises at import, so running the script the way its own usage line described it died on ValueError: Invalid Base58 string before printing anything. Nine scripts did this. Four more took their amount and slippage from environment variables that no usage line mentioned. Every script now builds an ArgumentParser in main(): required values are positionals, tunables are --options, and the literals live in DEFAULT_* constants that supply the defaults. --help works on all 32 that take input; the seven listeners take none and are exempt. The decode scripts keep defaulting to the fixture beside them, so they still run bare. Behaviour is unchanged. create_and_buy's mayhem flag defaulted to on, so it takes --mayhem/--no-mayhem via BooleanOptionalAction rather than a store_true that would have silently flipped it off. Two fixes found while threading the values through: the wallet listener read a global `wallet` from four functions that no longer had one, and find_pool raised IndexError on a coin that has not graduated instead of saying so. verify_cookbook_arguments.py enforces the shape — no module-level sys.argv, no placeholder values, argparse wherever there is input, and every default a usable value. Confirmed to fail when the old pattern is put back. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * fix(docs): replace three dead links and check the rest The Anchor discriminator citation in anchor_calculate_discriminator.py pointed at book.anchor-lang.com/anchor_bts/discriminator.html, which Anchor removed when it restructured its docs. Two links in the README had also moved: docs.chainstack.com/quickstart/ and docs.chainstack.com/docs/trader-nodes. book.anchor-lang.com/anchor_bts/discriminator.html -> www.anchor-lang.com/docs/basics/idl (has a Discriminators section) docs.chainstack.com/quickstart/ -> docs.chainstack.com/reference/blockchain-apis docs.chainstack.com/docs/trader-nodes -> docs.chainstack.com/docs/solana-trader-nodes All 28 real URLs in the repo now return 200, checked by fetching each one. verify_documentation_links.py keeps them honest: offline it asserts every URL is https and that none of the four dead endpoints has come back, and --live fetches each and fails on 4xx/5xx. It skips the unroutable hosts the offline verifiers point stub clients at, and example.com, which RFC 2606 reserves for exactly the placeholder metadata URI a test coin is created with. The discriminator script also still asked you to edit a constant, which the argument rule had just outlawed, so it takes the name on the command line and prints the u64, the byte list and the hex. Cross-checks against the constants in pumpfun_instructions_v2.py: global:buy_v2 gives [184, 23, 238, 97, 103, 197, 211, 61], which is BUY_V2_DISCRIMINATOR. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * fix(cookbook,tools): detect coins via logs so v1 transactions are not skipped Solana transaction v1 has been live since 2026-09-15 and solders cannot deserialize one until 0.29. Three scripts detected coins by deserializing the transaction envelope, so each went blind to v1: cookbook/pumpfun/listen/pumpfun_listen_tokens_blocksubscribe.py 30,080 "skipping a v1 transaction" lines in 150s tools/compare_listeners.py 601 "Failed to process transaction: io error: unexpected end of file" in 100s, which its own comment read as a transport difference cookbook/pumpfun/trade/pumpfun_snipe_token_blocksubscribe.py skipped v1 silently, so a coin created in one was never sniped All three now route on meta.logMessages, which the RPC has already decoded and which reads the same for every version. The blocks example keeps the envelope decode as a genuine fallback for providers that return blocks without logs; the sniper derives the associated bonding curve from the mint and curve instead of reading the instruction's account list, verified against pumpfun_derive_curve_addresses.py on a live coin. Measured live after the change: the blocks example decoded 88 v0, 6 v1 and 4 legacy creates with zero skips and zero errors, and compare_listeners' block lane now appears alongside logs and geyser for the same coins. Upgrading solders was tried first and reverted. 0.29 does decode v1 — 0.26, 0.27.1 and 0.28 all raise "io error: unexpected end of file" on the committed fixture — but it requires solana>=0.40, which moved TxOpts, MemcmpOpts and TokenAccountOpts out of solana.rpc.types. 22 files import them and 16 of 19 verifiers failed on the import alone, so that is a migration of its own. verify_transaction_v1.py gains a check that no cookbook or tools listener detects by opening the envelope. It found the sniper, which this had missed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR * fix(cookbook): label the transaction version and restore the lost fields The blocks listener printed "Found CreateEvent in a 0 transaction", which reads as a count rather than what it is — Solana's transaction version. It now prints v0, v1 or legacy. Routing detection through the CreateEvent also dropped two fields the instruction path used to fill, so every detection showed "Token Standard: N/A" and no Associated BC. Both come from the event's token_program: the standard is that program, and the associated bonding curve is an ordinary ATA of the curve under it. Verified against pumpfun_derive_curve_addresses.py on a live coin — curve E94izXvHd7dd... derives to He94dArnuprt..., matching what the listener now prints. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EZ5HdjTadNUad8i6xis3TR --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-23 09:34:40 +02:00