docs: add rationale comments to test configuration changes

- Bankrun projects (7): explain why [test.validator] was removed — these
  use in-process simulation and don't need the local validator
- Real-validator projects (2): explain why startup_wait is 120s — they
  clone programs from devnet which is slow in CI
- Escrow native: explain why Cargo.lock is committed and blake3 is pinned
  (edition 2024 incompatibility with solana-program 1.18.17's toolchain)
- Escrow test: comment explaining borsh deserializes pubkeys as byte arrays
- .gitignore: exception for escrow Cargo.lock with explanation

Author: rocketiotemp

.gitignore

@@ -8,6 +8,8 @@ node_modules/
 **/*/node_modules
 **/*/package-lock.json
 **/*/Cargo.lock
+# Exception: escrow native needs Cargo.lock to pin blake3 (see tokens/escrow/native/Cargo.toml)
+!tokens/escrow/native/Cargo.lock
 
 **/*/.anchor
 **/*/.DS_Store

tokens/create-token/anchor/Anchor.toml

@@ -18,6 +18,10 @@ wallet = "~/.config/solana/id.json"
 [scripts]
 test = "pnpm ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 shutdown_wait = 2000

tokens/escrow/native/Cargo.toml

@@ -1,3 +1,9 @@
 [workspace]
 members = ["program"]
 resolver = "2"
+
+# Cargo.lock is committed to pin blake3 to 1.5.5 (and constant_time_eq to 0.3.1).
+# blake3 >= 1.8.3 requires Rust edition 2024, which the Cargo bundled with
+# solana-program 1.18.17's platform-tools (Cargo 1.84.0) doesn't support.
+# When solana-program is upgraded to a version with edition 2024 support,
+# this Cargo.lock pin can be removed and the crate re-resolved freely.

tokens/escrow/native/tests/test.ts

@@ -64,6 +64,7 @@ describe('Escrow!', async () => {
     const vaultTokenAccount = AccountLayout.decode(vaultInfo.data);
 
     assert(offer.id.toString() === values.id.toString(), 'wrong id');
+    // borsh deserializes pubkeys as raw byte arrays, wrap in PublicKey for comparison
     assert(new PublicKey(offer.maker).toBase58() === values.maker.publicKey.toBase58(), 'maker key does not match');
     assert(new PublicKey(offer.token_mint_a).toBase58() === values.mintAKeypair.publicKey.toBase58(), 'wrong mint A');
     assert(new PublicKey(offer.token_mint_b).toBase58() === values.mintBKeypair.publicKey.toBase58(), 'wrong mint B');

tokens/nft-minter/anchor/Anchor.toml

@@ -19,6 +19,10 @@ wallet = "~/.config/solana/id.json"
 [scripts]
 test = "pnpm ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 shutdown_wait = 2000

tokens/nft-operations/anchor/Anchor.toml

@@ -18,6 +18,10 @@ url = "https://api.apr.dev"
 cluster = "localnet"
 wallet = "~/.config/solana/id.json"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 

tokens/pda-mint-authority/anchor/Anchor.toml

@@ -18,6 +18,10 @@ wallet = "~/.config/solana/id.json"
 [scripts]
 test = "pnpm ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 shutdown_wait = 2000

tokens/spl-token-minter/anchor/Anchor.toml

@@ -18,6 +18,10 @@ wallet = "~/.config/solana/id.json"
 [scripts]
 test = "pnpm ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 shutdown_wait = 2000

tokens/token-2022/basics/anchor/Anchor.toml

@@ -14,6 +14,10 @@ url = "https://api.apr.dev"
 cluster = "Localnet"
 wallet = "~/.config/solana/id.json"
 
+# Tests use solana-bankrun (in-process simulation), not the local validator.
+# No [test.validator] section needed — adding one (e.g. to clone programs from
+# mainnet) would slow down validator startup without benefit, since bankrun
+# loads programs directly from the local build.
 [test]
 startup_wait = 25000
 

tokens/token-2022/transfer-hook/hello-world/anchor/Anchor.toml

@@ -18,6 +18,9 @@ wallet = "~/.config/solana/id.json"
 [scripts]
 test = "pnpm ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
 
+# Tests use the real local validator (not bankrun) because transfer-hook
+# tests need the actual validator runtime. startup_wait is 120s because the
+# validator clones programs from devnet which is slow in CI.
 [test]
 startup_wait = 120000
 shutdown_wait = 2000