feat(tooling): scripts/preflight.py — contributor environment preflight check (issue #245)

.gitignore

@@ -22,6 +22,7 @@ tasks/local/0x4657105FC932625CD289107aAE7B2174a822b709/services/__pycache__/*
 /bashscripts/*
 /tasks/*
 /scripts/*
+!scripts/preflight.py
 /hardhat/ignition/*
 # /hardhat/scripts/*
 # /hardhat/test/*

Developer/BACK_LOG.md

@@ -38,7 +38,7 @@
 | BL-29 | Solidity/foundry (fees) | `DinFeeRouter`'s non-treasury shares accrue with no way out | `routeFeeETH`/`routeFeeDIN` pay the treasury share out immediately but only *count* the `validatorPool`, `storage` and `publicGoods` shares in `accruedEth`/`accruedDin`. No function withdraws or distributes them, so with the default 95% validator-pool split, 95% of every swept faucet/registry fee stays in the router until an upgrade adds a path. Needs a decision on who can pull each bucket and where the validator-pool share goes (reward pools? `DinEmission`?). | P3/P4 | PR No. 204 review (`DinCoordinator.md` §14 No. 2), Sep 30, 2026; related to issue #43's open items | 🆕 New — unaddressed; tracked in [#221](https://github.com/InfiniteZeroFoundation/DevNet/issues/221) |
 | BL-30 | Solidity/foundry (task contracts) | No recovery from a stalled GI | If a T1/T2 batch never reaches the reveal quorum, `finalizeT1Aggregation`/`finalizeT2Aggregation` revert forever (`TC_NoSubmissions`/`TC_InsufficientSubmissions`), and there is no owner path to skip the batch or abort the GI. `endGI` needs `AggregatorsSlashed` and `startGI` needs `GIended`, so the model is stuck: its reward pool and its validators' registration slots stay locked. This is also why BL-26's contract-side re-anchor cap was deferred. Needs a GI-abort design: who may abort, when, and where the reward pool goes. | P3/P4 | PR No. 191 review (BL-26); PR No. 204 review (`DINTaskCoordinator.md` §10 No. 6) | 🆕 New — unaddressed; tracked in [#222](https://github.com/InfiniteZeroFoundation/DevNet/issues/222) |
 | BL-31 | Solidity/foundry (slashing) | S6 no-participation slashing is implemented but not wired | `DinValidatorStake.recordNoParticipation` (escalating 10%-per-breach slash past `s6NoParticipationThreshold`) exists and is tested, but no task contract calls it. They deliberately skip it where `slashPartial` (S1/S2, with S5 escalation) already penalises the same missed work, to avoid stacking past `MIN_STAKE`. So S6 never fires. Decide whether S6 should cover something S1/S2 don't (e.g. registered but never assigned or never active), or whether to remove it and its parameters. | P3 | PR No. 204 review (`DinValidatorStake.md` §14 No. 1), Sep 30, 2026; slashing taxonomy S6 (issue #38) | 🆕 New — unaddressed; tracked in [#224](https://github.com/InfiniteZeroFoundation/DevNet/issues/224) |
-| BL-32 | Tooling / onboarding | Contributor environment preflight check | No single command checks a dev machine before work starts. Each of these has already cost time: (1) Python ≥ 3.12; (2) `forge`/`anvil` installed and solc 0.8.28 available; (3) `foundry/node_modules` present. Without `npm ci`, `forge test`'s parallel tests race to fetch `@openzeppelin/upgrades-core` over npx (see [CLAUDE.md](../CLAUDE.md)); (4) `eth-account` and `py-multibase` import; (5) `torch` imports in the active venv, which the full `pytest` run needs; (6) `.env` / `.env.<network>` exist, the RPC endpoint answers, and `resolve_ipfs_config()` resolves. Proposal: `scripts/preflight.sh` or `dincli system doctor`, one line per check, `OK` or `MISSING → <fix hint>`, non-zero exit on any failure. Also usable as the first CI step and in the onboarding docs. Read-only: it reports missing packages and never installs them. | P3/P4 (onboarding; small, ~half a day) | `preflight.sh` pattern from [Osomudeya/devops-scripting-labs](https://github.com/Osomudeya/devops-scripting-labs) (reviewed 2026-10-02); no existing equivalent (the only "preflight" in `dincli/cli/system.py` is the bridge's tx preflight) | 💭 Idea |
+| BL-32 | Tooling / onboarding | Contributor environment preflight check | No single command checks a dev machine before work starts. Each of these has already cost time: (1) Python ≥ 3.12; (2) `forge`/`anvil` installed and solc 0.8.28 available; (3) `foundry/node_modules` present — without `npm ci`, `forge test`'s parallel tests race to fetch `@openzeppelin/upgrades-core` over npx (see [CLAUDE.md](../CLAUDE.md)); (4) `eth-account` and `py-multibase` import; (5) `torch` imports in the active venv (full `pytest` run); (6) `.env`/`.env.<network>` exist, the RPC endpoint answers, and `resolve_ipfs_config()` resolves. | P3/P4 (onboarding; small, ~half a day) | `preflight.sh` pattern from [Osomudeya/devops-scripting-labs](https://github.com/Osomudeya/devops-scripting-labs) (reviewed 2026-10-02); no existing equivalent (note: the only "preflight" in `dincli/cli/system.py` is the bridge's tx preflight — unrelated) | ✅ Fixed — PR [#255](https://github.com/InfiniteZeroFoundation/DevNet/pull/255) (issue [#245](https://github.com/InfiniteZeroFoundation/DevNet/issues/245)). `scripts/preflight.py` added: stdlib-only for Python/forge/anvil/node_modules/package checks; `--network` flag for RPC and IPFS checks; 13 tests in `tests/test_preflight.py`; preflight section added to `Documentation/public/getting-started.md`. |
 | BL-33 | Tooling / deploy | On-chain deployment drift check | Nothing verifies that `foundry/deployments/<network>.json` (and the `din_info` that `dincli system import-deployments` writes) still matches the chain. Proposal: a read-only check, either a forge script or `dincli system verify-deployment`, that for each recorded contract compares (1) the proxy's EIP-1967 implementation and admin slots against the recorded implementation/`proxyAdmin*` addresses; (2) the deployed runtime code hash against the current `forge build` artifact (immutables masked); (3) owner / DIN-Representative addresses; (4) wiring: `DinCoordinator` ↔ `DinToken`/`DinValidatorStake`/`DinModelRegistry`/fee router/treasury links and slasher authorizations on `DinValidatorStake`. Report per-item `OK` / `DRIFT` with expected vs. actual. Caveat: it only covers what the deployments JSON records, so a clean run doesn't prove nothing else was deployed or authorized. | P3 (before the DevNet 3.0 deploy; re-run after every `UpgradePlatform.s.sol` run) | Terraform state-vs-live drift pattern from [Osomudeya/devops-scripting-labs](https://github.com/Osomudeya/devops-scripting-labs) `03-drift-detection` (reviewed 2026-10-02); no existing code reads EIP-1967 slots or code hashes in `dincli/` or `foundry/script/` | 💭 Idea |
 | BL-34 | Solidity/foundry (task contracts) | `DINModelRegistry.disableModel()` kill-switch doesn't reach the live task contracts | `modelDisabled[modelId]` only gates `requestModelRegistration`/`requestManifestUpdate` inside the registry itself. `DINTaskCoordinator`/`DINTaskAuditor` have no dependency on, or awareness of, the registry (confirmed: zero functional references; the auditor has two doc comments naming `DINModelRegistry` by name (L31, L434) plus two more referencing "model registry" generically without naming the type (L393, L405) — none are functional checks). A model the DIN-Representative has disabled — e.g. because its task contracts are wrongfully slashing honest validators — keeps running full GIs completely unaffected. The task contracts' own doc table calls this a "kill-switch," which it isn't. Needs a decision: wire the task contracts to check `modelDisabled` before state-changing calls (requires threading the model ID + registry address into contracts that don't know about the registry today), or document `disableModel` as registry-metadata-only. | P3/P4 | 2026-07 security review M-2 (`Documentation/technical/audits/foundry-src-security-review.md`) | 🆕 New — unaddressed; tracked in [#224](https://github.com/InfiniteZeroFoundation/DevNet/issues/224) |
 | BL-35 | Solidity/foundry (registry) | `rejectModel()`'s non-refund of the registration fee was never confirmed as intentional | `feePaid` (set at `requestModelRegistration`) is never refunded on `rejectModel()`, but it's also never refunded on `approveModel()` either — the fee appears to be a deliberate pay-to-apply cost regardless of outcome (anti-spam), not an oversight specific to rejection. Never written down as a deliberate choice anywhere. Needs confirmation and a doc note in `DINModelRegistry.md` / the dinrep role docs, so a future reader doesn't "fix" it into an inconsistent partial-refund state. | P4 (doc-only once confirmed) | 2026-07 security review L-4 (`Documentation/technical/audits/foundry-src-security-review.md`) | 🆕 New — unaddressed; tracked in [#224](https://github.com/InfiniteZeroFoundation/DevNet/issues/224) |

Documentation/public/getting-started.md

@@ -218,6 +218,40 @@ If you are unable to obtain funds through the faucets above, you may also reques
 ---
 
 
+# 🩺 Environment Preflight Check
+
+> **For contributors working from a clone of this repo.** Participants who
+> installed dincli from the wheel (per [setup.md](setup.md)) can skip this
+> section — forge and anvil are not required for network participation.
+
+Before starting development, verify your environment with:
+
+```bash
+python3 scripts/preflight.py
+```
+
+The script checks each of the following and prints `[OK]`, `[WARN]`, or `[MISSING]` with a fix hint:
+
+| Check | Pass condition |
+|-------|----------------|
+| Python version | ≥ 3.12 |
+| `forge` on PATH | Foundry installed |
+| `anvil` on PATH | Foundry installed |
+| `foundry/node_modules` | `cd foundry && npm ci` has been run |
+| `eth-account`, `py-multibase`, `web3` | importable after `pip install -e .` |
+| `torch` | importable after `pip install -e .[test]` (optional — tests skip without it) |
+
+Exits 0 when all required checks pass; exits 1 on Python version or Foundry failures.
+
+To also verify the configured RPC endpoint (read from `os.environ` or `.env`, the same lookup dincli uses) and the IPFS config:
+
+```bash
+python3 scripts/preflight.py --network sepolia_op_devnet
+# or: python3 scripts/preflight.py --network local
+```
+
+---
+
 # ⚙️ DIN CLI Installation and Setup
 
 Before participating, ensure dincli is correctly installed and configured.