Contributing

Thanks for wanting to improve this repo. The single most valuable contribution is finding a flaw — this project deliberately keeps itself falsifiable. If a claim is wrong, a proof step does not follow, a quote is mis-attributed, or a script misleads, that is a welcome finding.

Audit, don’t trust — including this repo. See docs/AUDIT-REQUEST.md.

1. How to report a problem

Open an issue using the “Audit finding / correctness issue” template (.github/ISSUE_TEMPLATE/audit-finding.md).
Say which claim you are challenging (A / B / C — see docs/FAQ-EXCHANGE-DEPOSIT-VERIFY.md).
For code findings, paste the exact command line and the full output.
For source findings, link the official document so it can be checked.

2. Project rules (please keep these)

English only. Every document is written in English (*.md). Do not add translated copies.
Zero dependencies. Only Node 18+ built-ins (fetch, node:child_process, …). No npm install.
Read-only. Scripts may only issue GET requests against the public API (https://api.mainnet.minepi.com). No wallet, no keys, no passphrase, no signing, no writes. See SECURITY.md. (The single exception is the clearly-labelled maintenance tool examples/regenerate-snapshots.mjs, which only rewrites the local *-output.txt snapshots.)
Precise claims only. State exactly what is proven and what is not (price, identity-hiding, reserve backing are out of scope). Prefer the canonical wording: “A native Pi payment carries no observable per-unit mining origin on the Pi Mainnet ledger.”
No tool/AI names. Do not name any assistant, chatbot, or external tool anywhere in the repo.
Official sources. Back protocol claims with a link (docs.minepi.com, the MiCA whitepaper, the Platform API docs). Add them to docs/SOURCES.md.
Keep outputs honest. If you change a script’s output, regenerate the committed examples/*-output.txt snapshots with node examples/regenerate-snapshots.mjs (writes clean UTF-8/LF — avoid a shell >, which produces UTF-16 on Windows).

3. Adding a new FAQ (answering a new objection)

Create docs/FAQ-<TOPIC>.md.
Structure: the objection (stated fairly) → the short answer → the evidence (source + code) → what is not claimed.
Link both files from:
- README.md FAQ table
- docs/INDEX.md Part 1 and Part 2.
If the objection is common, also add it to docs/FAQ-ALL-OBJECTIONS.md.

4. Run everything locally

Requires Node 18+ and network access (only the live examples need the network).

node examples/run-all.mjs            # everything at once (+ summary); add --offline for no network
node examples/self-test.mjs          # 34 offline checks + 3 online end-to-end (37 total)
node examples/model-check.mjs        # offline ledger model + property check (2000 seeds)
node examples/exhaustive-check.mjs   # offline EXHAUSTIVE bounded check (all 1452 histories)
node examples/provenance-check.mjs   # live: no origin field on chain
node examples/coin-id-check.mjs      # live: balance is one scalar
node examples/verify-deposit.mjs <TXID> [TO_ADDRESS]
node examples/mixing-check.mjs

CI runs the offline checks on Node 20 & 22 for every push/PR (.github/workflows/self-test.yml). Keep them green.

5. Commits & style

Small, focused commits with a clear message; explain why, not just what.
Keep scripts short and readable — they are meant to be audited line by line.
Prefer comments that state assumptions and known limits.
By contributing you agree your work is released under the repo MIT license (LICENSE).

6. What we will not accept

Claims of price, future value, or guaranteed reserve backing.
Anything that weakens the read-only guarantee or adds dependencies.
Removing or softening the honest scope statements.

Goal: a repo a skeptic can verify end-to-end and, where possible, break.