Skip to content

docs: truth audit across READMEs#26

Merged
mikemaccana merged 2 commits into
quicknode:mainfrom
mikemaccana-edwardbot:chore/docs-truth-audit-2026-05-14
May 14, 2026
Merged

docs: truth audit across READMEs#26
mikemaccana merged 2 commits into
quicknode:mainfrom
mikemaccana-edwardbot:chore/docs-truth-audit-2026-05-14

Conversation

@mikemaccana-edwardbot
Copy link
Copy Markdown

@mikemaccana-edwardbot mikemaccana-edwardbot commented May 14, 2026

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:

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).

Follow-up commit on this branch (23e0778): chore(token-minter): rename from spl-token-minter

This branch now also includes the directory + crate rename
tokens/spl-token-minter/tokens/token-minter/. The 'spl-' prefix
was 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:

  • Directories: tokens/spl-token-minter/ and the inner Anchor program
    dir anchor/programs/spl-token-minter/.
  • Cargo / package names: spl-token-minter, spl_token_minter (Anchor
    lib), quasar-spl-token-minter, quasar_spl_token_minter,
    spl-token-minter-native-program.
  • Anchor #[program] mod name, Anchor.toml [programs.localnet] key,
    test file path/name (test_spl_token_minter.rs
    test_token_minter.rs) and internal spl_token_minter::* refs.
  • Quasar #[program] mod name and the .so path in tests.
  • Native enum SplMinterIntstruction (also fixes the existing typo) →
    MinterInstruction; TS enum SplMinterInstruction
    MinterInstruction; describe('SPL Token Minter')
    describe('Token Minter'); it('Create an SPL Token!')
    it('Create a token').
  • Cross-repo path links: root README.md,
    tokens/nft-minter/README.md, tokens/transfer-tokens/README.md,
    tokens/create-token/quasar/src/lib.rs, and the two
    .github/.ghaignore entries.

cargo check inside tokens/token-minter/anchor passes cleanly.
git grep 'spl[-_]token[-_]minter' returns zero matches across the
tree. No program logic changed — rename + prose only.

Mike MacCana and others added 2 commits May 14, 2026 21:56
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.
@mikemaccana-edwardbot mikemaccana-edwardbot force-pushed the chore/docs-truth-audit-2026-05-14 branch from 23e0778 to 2c44580 Compare May 14, 2026 21:56
@mikemaccana mikemaccana merged commit 34b9660 into quicknode:main May 14, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants