docs: truth audit across READMEs#26
Merged
mikemaccana merged 2 commits intoMay 14, 2026
Merged
Conversation
Read every README against the underlying code and fixed claims that no longer hold. Also applied the agreed token-terminology rules across prose: no 'SPL Token(s)', no 'Token-2022' / 'Token 2022'. Use 'tokens', 'Classic Token Program', 'Token Extensions' / 'Token Extensions Program'. 'instruction handler' (not 'instruction') when referring to the Rust pub fn under #[program]. Behaviour changes: - Delete orphan dir tokens/token-extensions/transfer-hook/pblock-list/. PR solana-developers#20 renamed pblock-list → block-list but left the parent shell behind with a stale README that referenced a non-existent pinocchio/ subdir. Real claim drift fixed (README claimed X, code does Y): - tokens/token-fundraiser/anchor: duration field is u16 (not u8); Contributor struct has a bump field; handlers are free pub fn handle_*(accounts: &mut X, ...) (not impl<'info>); amount >= MIN_AMOUNT_TO_RAISE (not >); 1_u64.pow (not 1_u8.pow); FundraiserError::FundraiserEnded (not FundraisingEnded); added missing check_contributions handler description; documented the duration-check semantics (see WARNING below). - tokens/nft-operations/anchor: code pattern shifted from impl<'info> X<'info> { pub fn ... } to free pub fn handler(accounts: &mut X, bumps: &XBumps). Rewrote all three handler code blocks. Also fixed INSTRUCTIONS_ID → INSTRUCTIONS_SYSVAR_ID with a note about the Anchor 1.0 sysvar-id move. - basics/close-account/anchor: README described a 'destroy-an-account' program with TypeScript tests using fetchNullable. Actual program is 'close-account', files are create_user.rs and close_user.rs, tests are Rust litesvm (cargo test). Rewrote the README to match. - basics/cross-program-invocation: dependency uses features = ["cpi"] (which enables no-entrypoint), not features = ["no-entrypoint"] directly. Documented the cpi feature. - tokens/token-extensions/nft-meta-data-pointer/anchor-example: MAX_ENERGY = 100 (not 10); programs/extension_nft (underscore, not hyphen); there is no update_energy.rs instruction handler (the refill is computed in PlayerData::update_energy in state/player_data.rs); file tree updated to match actual layout. - compression/cnft-burn, cnft-vault, cutils anchor READMEs: stripped references to non-existent tests/ directories and stale devnet program IDs (the lib.rs declare_id! values are different and the README values can't be verified). cutils also claimed 'pins Anchor 0.26.0' but Cargo.toml uses anchor-lang = "1.0.0". - tokens/token-extensions/transfer-hook/whitelist/anchor: fixed broken link to ../../pblock-list/ → ../../block-list/. - tokens/token-extensions/transfer-hook/block-list/readme.md: this lowercase readme.md was not updated in the May 12 style pass. Rewrote to match the styled tone and the actual handler names (Init, BlockWallet, UnblockWallet, SetupExtraMetas, TxHook) and dispatcher in pinocchio/program/src/lib.rs. Removed the unverifiable devnet links and dead transaction URLs; left only the declare_id! with a note on how to check deployment. Terminology sweep (prose only; directory paths and Rust identifiers like Program<'info, Token2022> / TOKEN_2022_PROGRAM_ID unchanged): - 'SPL Token', 'SPL Tokens', 'the SPL Token Program' → 'tokens', 'Classic Token Program' depending on context. - 'Token-2022', 'Token 2022' → 'Token Extensions' / 'Token Extensions Program'. - 'the transfer() instruction provided by the SPL Token Program' → 'the Classic Token Program's transfer instruction handler'. WARNING — code bugs noticed but not fixed in this PR: token-fundraiser/anchor has comparison operators that look inverted relative to their error names: contribute.rs:72 — require!(duration <= elapsed_days, FundraiserEnded) refund.rs:60 — require!(duration >= elapsed_days, FundraiserNotEnded) One of these is wrong. The README now describes what the code actually does and flags this for any future reader. Did not change program logic in a docs PR. Out of scope (deliberately not touched): - spl-token-minter directory rename (would break links). - Whether the block-list/pinocchio Pinocchio program is currently shippable / CI-green (separate ongoing investigation). - block-list/readme.md → README.md rename (file rename, not content).
The 'spl-' prefix is redundant. Everything onchain is an SPL token (per
Solana's terminology page) — the prefix adds nothing and clutters paths
and crate names. The directory, crates, and prose mentions are now just
'token-minter' / 'Token Minter'.
Renamed:
Directories:
tokens/spl-token-minter/ -> tokens/token-minter/
tokens/token-minter/anchor/programs/spl-token-minter/ -> tokens/token-minter/anchor/programs/token-minter/
Crate / package names:
spl-token-minter (anchor) -> token-minter
spl_token_minter (anchor lib) -> token_minter
quasar-spl-token-minter -> quasar-token-minter
quasar_spl_token_minter (Quasar.toml) -> quasar_token_minter
spl-token-minter-native-program -> token-minter-native-program
Source identifiers:
Anchor #[program] mod name -> token_minter
Anchor.toml [programs.localnet] key -> token_minter
Anchor test file: test_spl_token_minter.rs -> test_token_minter.rs
Anchor test internal refs (spl_token_minter::*) -> token_minter::*
Quasar #[program] mod name -> quasar_token_minter
Quasar test .so path -> quasar_token_minter.so
Native processor enum SplMinterIntstruction (sic) -> MinterInstruction
Native TS enum SplMinterInstruction -> MinterInstruction
Native TS describe('SPL Token Minter') -> describe('Token Minter')
Native TS it('Create an SPL Token!') -> it('Create a token')
Cross-repo path references updated:
README.md (root)
tokens/nft-minter/README.md
tokens/transfer-tokens/README.md
tokens/create-token/quasar/src/lib.rs (prose path)
.github/.ghaignore (two entries)
Verified:
- cargo check inside tokens/token-minter/anchor compiles cleanly
- git grep 'spl[-_]token[-_]minter' returns zero matches
- rename is behaviour-preserving (no program logic changed)
Out of scope (pre-existing on this branch, unrelated to rename):
- tokens/token-minter/quasar fails cargo check because quasar-spl on
branch=master has the zeropod 0.3.0 regression; fix lands when PR solana-developers#24
is rebased into this branch's base.
- tokens/token-minter/native/program does not standalone-compile because
it is inside the repo's [workspace] but not listed as a member; same
state as tokens/nft-minter/native/program. CI ignores it via .ghaignore.
23e0778 to
2c44580
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs: truth audit across READMEs
Read every README against the underlying code and fixed claims that no
longer hold. Also applied the agreed token-terminology rules across
prose: no 'SPL Token(s)', no 'Token-2022' / 'Token 2022'. Use 'tokens',
'Classic Token Program', 'Token Extensions' / 'Token Extensions
Program'. 'instruction handler' (not 'instruction') when referring to
the Rust pub fn under #[program].
Behaviour changes:
PR chore: rename pblock-list directory to block-list #20 renamed pblock-list → block-list but left the parent shell
behind with a stale README that referenced a non-existent
pinocchio/ subdir.
Real claim drift fixed (README claimed X, code does Y):
Contributor struct has a bump field; handlers are free
pub fn handle_*(accounts: &mut X, ...) (not impl<'info>);
amount >= MIN_AMOUNT_TO_RAISE (not >); 1_u64.pow (not 1_u8.pow);
FundraiserError::FundraiserEnded (not FundraisingEnded); added
missing check_contributions handler description; documented the
duration-check semantics (see WARNING below).
impl<'info> X<'info> { pub fn ... } to free pub fn handler(accounts:
&mut X, bumps: &XBumps). Rewrote all three handler code blocks.
Also fixed INSTRUCTIONS_ID → INSTRUCTIONS_SYSVAR_ID with a note
about the Anchor 1.0 sysvar-id move.
program with TypeScript tests using fetchNullable. Actual program is
'close-account', files are create_user.rs and close_user.rs, tests
are Rust litesvm (cargo test). Rewrote the README to match.
(which enables no-entrypoint), not features = ["no-entrypoint"]
directly. Documented the cpi feature.
MAX_ENERGY = 100 (not 10); programs/extension_nft (underscore, not
hyphen); there is no update_energy.rs instruction handler (the
refill is computed in PlayerData::update_energy in state/player_data.rs);
file tree updated to match actual layout.
references to non-existent tests/ directories and stale devnet
program IDs (the lib.rs declare_id! values are different and the
README values can't be verified). cutils also claimed 'pins Anchor
0.26.0' but Cargo.toml uses anchor-lang = "1.0.0".
link to ../../pblock-list/ → ../../block-list/.
lowercase readme.md was not updated in the May 12 style pass.
Rewrote to match the styled tone and the actual handler names
(Init, BlockWallet, UnblockWallet, SetupExtraMetas, TxHook) and
dispatcher in pinocchio/program/src/lib.rs. Removed the unverifiable
devnet links and dead transaction URLs; left only the declare_id!
with a note on how to check deployment.
Terminology sweep (prose only; directory paths and Rust identifiers
like Program<'info, Token2022> / TOKEN_2022_PROGRAM_ID unchanged):
'Classic Token Program' depending on context.
'Token Extensions Program'.
'the Classic Token Program's transfer instruction handler'.
WARNING — code bugs noticed but not fixed in this PR:
token-fundraiser/anchor has comparison operators that look inverted
relative to their error names:
contribute.rs:72 — require!(duration <= elapsed_days, FundraiserEnded)
refund.rs:60 — require!(duration >= elapsed_days, FundraiserNotEnded)
One of these is wrong. The README now describes what the code
actually does and flags this for any future reader. Did not change
program logic in a docs PR.
Out of scope (deliberately not touched):
shippable / CI-green (separate ongoing investigation).
Follow-up commit on this branch (23e0778):
chore(token-minter): rename from spl-token-minterThis branch now also includes the directory + crate rename
tokens/spl-token-minter/→tokens/token-minter/. The 'spl-' prefixwas redundant per the terminology rule applied in the docs audit
itself — every onchain token is an SPL token, so the prefix carries no
information. The rename covers:
tokens/spl-token-minter/and the inner Anchor programdir
anchor/programs/spl-token-minter/.spl-token-minter,spl_token_minter(Anchorlib),
quasar-spl-token-minter,quasar_spl_token_minter,spl-token-minter-native-program.#[program]mod name,Anchor.toml [programs.localnet]key,test file path/name (
test_spl_token_minter.rs→test_token_minter.rs) and internalspl_token_minter::*refs.#[program]mod name and the.sopath in tests.SplMinterIntstruction(also fixes the existing typo) →MinterInstruction; TS enumSplMinterInstruction→MinterInstruction;describe('SPL Token Minter')→describe('Token Minter');it('Create an SPL Token!')→it('Create a token').README.md,tokens/nft-minter/README.md,tokens/transfer-tokens/README.md,tokens/create-token/quasar/src/lib.rs, and the two.github/.ghaignoreentries.cargo checkinsidetokens/token-minter/anchorpasses cleanly.git grep 'spl[-_]token[-_]minter'returns zero matches across thetree. No program logic changed — rename + prose only.