quicknode/solana-finance-claude-plugin/solana

Coding Guidelines

Apply these rules to ensure code quality, maintainability, and adherence to project standards.

Fight for Truth

Don't write things that aren't currently true - anywhere. Chat, code comments, variable names, PR titles, READMEs, commit messages.

• Documentation and comments that do not match the code are considered untrue.
• Variable names that do not match the purpose of the variable are considered untrue. For example, a struct called InitializeMarket is not true because a struct cannot 'initialize a market' - structs do not do things, only functions can do things.
• Temporary workarounds that aren't labelled as such are lying through omission - there is an issue you aren't telling the next programmer about. Mark them with a TODO comment with a link to a git issue (if it exists) and telling the next programmer when they can delete the workaround.
• If unsure of something, say so. Bluffing is lying.
• Ambiguity is a soft lie: if a phrase could be read two ways and only one is true, it's misleading. Disambiguate before sending - pick the term that says exactly what's meant, name the antecedent of every "it"/"this"/"that".
• A wrong statement is worse than no statement.
• Separate scratch labels from real identifiers.

Actively fix untrue things when you see them. Don't let "close enough" wording stand in for the truthful one.

Grep before naming. Before sending any prose, walkthrough, README, comment, or commit message that names a specific identifier (function, struct, file, account, module, field, constant), grep the source for that exact identifier and confirm it exists. "I'm pretty sure that's the name" is not enough. If the identifier doesn't exist, either use the real name or apply the rename to the code first, then write the prose.

Describe what is, not what was removed. READMEs, doc-comments, and code comments document current state - not history. Lines like "no floats", "no longer uses X", "replaces the previous Y approach" belong in CHANGELOGs and PR descriptions, not source artefacts. A first-time reader has no history and "no longer uses I64F64" creates ambient confusion ("wait, should I be worried?"). Sweep before sending: grep for no longer, removed, previously, used to, formerly, dropped, now uses, replaces the previous - each hit is a candidate for deletion.

Do the whole thing

The marginal cost of completeness is near zero with AI. Do the whole thing.

Do it right. Do it with tests. Do it with documentation. Do it so well that the user is genuinely impressed - not politely satisfied, actually impressed. Never offer to "table this for later" when the permanent solve is within reach. Never leave a dangling thread when tying it off takes five more minutes. Never present a workaround when the real fix exists.

The standard isn't "good enough" - it's "holy shit, that's done." Search before building. Test before shipping.

Ship the complete thing. When the user asks for something, the answer is the finished product, not a plan to build it. Time is not an excuse. Fatigue is not an excuse. Complexity is not an excuse. Boil the ocean.

A caveat is not a fix. When you find a gap while doing the work - missing test coverage, a CI job that doesn't run, an untested path, a stale doc - close it as part of the task. Do not downgrade a fixable defect into a disclaimer. If you catch yourself writing "note: X isn't covered / isn't built / isn't tested / won't get a CI signal," stop: that sentence is a TODO, not a caveat. Fix X so there is nothing to note. Reserve caveats for what you genuinely cannot fix (out of scope, needs a decision, external blocker) - and for those, state what you would do and offer to do it.

Success Criteria

• Before declaring success, declaring that work is complete, or celebrating, run the project's actual tests using the correct command for that project (for example: anchor test for Anchor workspaces, the project's TypeScript test command for TypeScript clients/tests, or cargo test for Rust crates). If the tests fail, there is more work to do. Don't stop until the relevant test command passes on the code you have made.
• Create all program state through the program's own instruction handlers in tests. Injecting pre-fabricated accounts (hand-built account data passed straight into the SVM) hides missing init instructions and missing constraints - a program can pass every test while being unusable onchain. Pre-fabricated accounts are only acceptable for accounts a foreign program would have created (an oracle's price account, a mainnet-dumped fixture).
• Tests that use a zero or degenerate value for a parameter (e.g. duration: 0) test only the boundary where opposite comparisons coincide. Use nonzero, asymmetric values and test both sides of every boundary.
• Do not write placeholder tests. Placeholder tests don't count as tests, placeholder tests passing does not achieve your task.
• Tests that just do assert.ok(true) or similar are placeholder tests and do not count as tests
• Tests that do not call the program's instruction handlers are placeholder tests and do not count as tests
• Tests must: initialize accounts, send transactions, verify state changes, check balances
• If you find yourself writing placeholder tests, stop and write real integration tests instead
• DO NOT mark "Write tests" as complete until tests actually call the program instructions
• DO NOT ask "should I write real tests now?" - if the tests are placeholders, write real ones immediately

• Do not stop until documentation like README.md and CHANGELOG.md are also updated with your changes. If you have made a feature, and it is not documented in the README or changelog, there is more work to do and you must continue working.

• When summarizing your work, show the work items you have achieved with this symbol '✅' and if there is any more work to do, add a '❌' for each remaining work item.

Documentation Sources

Use these official documentation sources:

• Anchor: https://www.anchor-lang.com/docs
• LiteSVM: https://www.anchor-lang.com/docs/testing/litesvm
• Anchor Error Codes: https://github.com/otter-sec/anchor/blob/master/lang/error/src/lib.rs
• Quasar: https://quasar-lang.com/docs
• Solana Kite: https://solanakite.org
• Solana Kit: https://solanakit.com
• Agave (Solana CLI): https://docs.anza.xyz/ (Anza makes the Solana CLI and Agave).
• Arcium (if used): https://docs.arcium.com/developers
• Quicknode Solana Program Examples: https://github.com/quicknode/solana-program-examples
• Anatoly Yakovenko's GitHub: https://github.com/aeyakovenko in particular the 'Percolator' perps project repositories.

Terminology

• Remember this is Solana not Ethereum. Ethereum is not relevant to any documentation you write. Do not assume people know or care about Ethereum.
• Don't tell me about 'smart contracts' or 'protocols' (use 'programs' instead)
• Don't tell me about 'gas' (use 'transaction fees' instead)
• There are no 'mempools'.
• Do not tell me about other things that are not relevant to Solana.

• Token program terminology:
• Use 'Token Extensions Program' or 'Token extensions' for the newer token program (not 'Token 2022' which is just a code name)
• Use 'Classic Token Program' for the older token program
• Use 'Token' rather than 'SPL Token' unless you are specifically discussing the distinction between the native token (SOL) and all other tokens (SPL Tokens)

• Onchain / offchain (one word, no hyphen)
• Always write 'onchain' and 'offchain' as single, unhyphenated words - like 'online' and 'offline'.
• Never write 'on-chain' or 'off-chain'. The hyphenated forms are wrong.
• Apply the same rule to related terms: 'crosschain' (not 'cross-chain'), etc.
• Sources:
• Solana Foundation style guide
• US Government usage
• Cat (catmcgee) will make fun of you if you write 'on-chain'

• Token amount units: a major unit is the human-scale denomination - dollar, pound, yen, SOL. A minor unit is the smallest denomination, the raw integer programs operate on - cent, penny, sen, lamport. Use these terms; do not say 'base units'.

• Some tools in Solana unfortunately use the same word 'instructions' for both the input and the functions. To avoid confusion, use 'instruction handlers' for the functions that handle instructions, and 'instructions' for the input to those functions.

• Name handlers by one rule: if the domain has a word for it, use the domain's word; if the handler only stamps out a container, it is `initialize_`. Domain verbs are what make a program read like finance, and they come in pairs: make_offer()/take_offer(), open_position()/close_position(), place_order()/cancel_order(), plus borrow, repay, liquidate, contribute, refund. Setup has no domain meaning, so it is always initialize_x(), naming what it initializes: initialize_market(), initialize_pool(), initialize_config(), never create_pool(), init_reserve(), or a bare initialize(). The test is whether the handler moves tokens or takes a market action, or only writes parameters into a new account. A third family, add_x(), extends a container that already exists: add_liquidity(), add_outcome(), add_asset().

• A key pair is two keys: a private key that signs, and a public key. The public key is the address; the pair is not an address, is not an account, and is never "at" one, and the private key is never shown or named as if it were public. An address made from a key pair is always on the Ed25519 curve, whoever generated the pair and whatever they did with the private key afterwards; only a PDA, or a built-in address such as the System Program's or a sysvar's, is drawn off it. So never write "a keypair address", "the keypair's account", "an off-curve keypair", or a caption such as A CLIENT KEYPAIR; write "a public key the client generated", "the account's address", or name the account. Never write a bare "key" for either half: say "private key" where it signs, is held or can be lost ("the market owner's private key signed the price", "a single private key on one person's laptop"), and "public key" where it is stored, recorded or checked ("her public key is stored as the market's admin"). Where the point is who signs rather than the key, "signer" or "signature" is often shorter ("a single trusted signer", "requiring the operator's signature"). "Key" in the database sense (a key/value store, a tree's sort key) is a different word; say so where the two could be confused.

• Say PDA for an address and account for the data at it. They are not synonyms: a program derives the offer PDA and then writes the offer account. Use PDA where the subject is derivation, seeds, authority, ownership, or signing, and account where the subject is fields, balances, rent, creation, or closure. Introduce a program's state as an account that lives at a PDA ("the market account lives at a PDA with seeds "market" and the two mints, and holds...", or "the reserve account (PDA seeds: ...)"), never as "the market is a PDA holding...". Don't write "PDA account": it names both halves at once and blurs them back together. Name the account by its role and add "at a PDA" only when the address model matters. The reverse slip is as common: a vault's authority is the offer PDA, not "the offer account", because authority is signing, and signing is the PDA's.

Do not use

• Do not use 'Solana Labs' documentation. The company has been replaced by Anza.