docs(tasks-plan): umermjd11 task plan 051026-2 — full-GI alignment: contracts check + richer GI states, dincli commands, integration suite on foundry, GI docs

[umermjd11]

New task plan for review: Developer/tasks-plan/umermjd11/task-plan-051026-2.md. It's written against develop @ a1fcce2. Same flow as before: review here, I apply amendments, then it's forwarded as one tasks/ spec.

Why. The task contracts have moved past what dincli and the full-GI integration suite exercise. On develop the suite (tests/dincli/) can't pass with either toolchain:

• It fails Phase 1 on the proxyAdmin key.
• It deploys the old hardhat task contracts.
• It overwrites the tracked dincli/abis/.
• It never funds the reward pool, registers auditor keys or reveals anything.
• It asserts GIended as 23.

dincli can't drive a full GI either:

• deploy uses the old constructors (BL-27).
• There are no commands for setDinToken, reward funding, encryption keys, claims, release slots (BL-28) or disputes.

The parts follow this order: contracts check → dincli → suite → docs.

#	Item	Estimate
TP-1	Contracts check. Records what a complete GI needs (modelId, setDinToken, funding, X25519 keys, seed blocks, the three reveal windows) and the dincli coverage table. Found: startLMsubmissionsEvaluation doesn't check that test data was assigned	0.5 d
TP-2	Richer GI states: AuditSeedLocked, AuditTestDataAssigned (closes the gap above), AggSeedLocked. Each is set by the function that already does the step, so there are no extra transactions. Ordinals are inserted in lifecycle position, and every dincli mirror, gate, doc and test is updated in the same PR. Ordinal table goes to PR #29. Size is measured against the 1,079 B margin	1.5 d
TP-3	dincli: deploy --model-id + setDinToken, a modelId check at approval, rewards deposit / fund-emission / claim / withdraw, per-wallet auditor register-encryption-key, gi release-slots, both dispute families, and fail-fast checks before gi start and create-testdataset	3 d
TP-4	The suite moves to foundry artifacts (no hardhat compile, no --official ABI writes) and runs a complete GI: funding, keys, seed locks, commit and reveal in all three phases, slash, end, claims, release slots. State is asserted after every phase	2 d
TP-5	GI docs: model-workflow, the role guides, getting-started, manifest, keystore-migration, din-workflow, the DINShared §2.2 diagram, CLAUDE.md	1.5 d

Decisions requested:

1. Which new states to add.
2. Whether the modelId check lives in dincli or the registry.
3. Whether the suite runs one GI or two.
4. Whether the dispute commands are part of this plan or split out.

Companion plan: PR #219 (task-plan-051026-1) is now narrowed to the contract follow-ups (#201 A4, #180, #193). The plan has a section on how the two coordinate. CI for the integration suite is a follow-up in #228 and is not part of this plan.

Docs-only PR. check_doc_links.py Developer is green.

🤖 Generated with Claude Code

[umeradl]

Review: deep verification

Reviewed against develop in an isolated worktree at PR head b40b0b4 (1 commit). Its merge-base is the current develop tip, a1fcce2, so there's nothing to drift against. git merge-tree --write-tree is clean locally, and GitHub reports mergeable: MERGEABLE, mergeStateStatus: CLEAN. Every file:line reference in the plan was re-resolved at a1fcce2. The task contracts, dincli and tests/dincli/ are byte-identical to 740a613 there, as the header says.

1. Integration-suite audit (the "Why" section)

Verified, with one precision fix.

• proxyAdmin key: test_01_platform.py:135-137 loops over (*DEPLOYMENT_KEYS, "proxyAdmin") and :164 asserts deployments["proxyAdmin"]. DeployPlatform.s.sol writes seven per-contract keys (proxyAdminTreasury … proxyAdminEmission, struct at :110-116), and deploy-platform.ts:50-53 reads per-contract admins. Phase 1 can't pass with either toolchain. ✅
• Hardhat task contracts: constants.py:50, ARTIFACT_BASE = DEVNET_ROOT / "hardhat" / "artifacts" / "contracts". ✅ I counted the enum members: hardhat GIstates has 23, and foundry's has 26 (AggregatorsSlashed // 24, GIended // 25). ✅
• Tracked ABIs overwritten: dump-abi --official appears 4× in test_01_platform.py:167-197 and 2× in test_02_task_contracts.py:74-107. ✅ The plan says test_02; the file is test_02_task_contracts.py.
• Wrong final state, precision fix: test_04_gi.py:478 asserts "GIended" in result.stdout or "23" in result.stdout. It passes on the name, so the bug is the stale or "23" fallback (the docstring says "index 23"), not a hard ordinal check. The plan's "asserts GIended as 23" overstates it; the fix (assert by name and the new ordinal) is right either way.
• _gi_state helper: defined at :52, and no test calls it. ✅

2. dincli gaps

Verified.

• deploy.py:35 sends constructor(din_validator_stake_address) and :77 sends (stake, coordinator). Foundry takes (address, uint256 modelId_) (DINTaskCoordinator.sol:290) and (stake, coordinator, modelId_) (DINTaskAuditor.sol:406).
• The latent NameError is real: din_validator_stake_address is only bound inside if … "stake" in din_info[...] (:27-28, :61-62), then used unconditionally.
• auditor.py:33-41 reads one shared CONFIG_DIR/auditor_x25519.key, and its error at :39 names dincli auditor register-encryption-key. A repo-wide grep finds no such command (the only hit is that error string).
• owner_x25519.key is written with no chmod (auditor_batches.py:170-177).
• stateDescription index 24 reads "Validators slashed" (utils.py, list at :640). It should be aggregators.
• DINShared.sol:30-34 says "24-member table"; the enum has 26 members.
• Reuse targets exist: build_and_send_tx (utils.py:947), the task-contract lookups (context.py:339, :357), stake_dintokens (dintoken.py:71), ensure_batch_seed_locked (utils.py:998), and bytecode.object handling (contract_utils.py:150-152).

3. Contract references

Verified, all resolve:

• DINTaskCoordinator.sol: :379-380 (TC_GIRewardPoolNotFunded), :519 (setTestDataAssignedFlag), :532-538 (startLMsubmissionsEvaluation: checks only AuditorsBatchesCreated), :1307 (setDinToken), :1368 (openDispute), :1459 (lockAggSeed), :1483 (lockAuditSeed), :1535 (resolveDispute), :1609 (settleRecomputation), :1671 (expireDispute).
• DINTaskAuditor.sol: :440 (setDinToken), :481 (depositRewards), :1000-1001 (TA_AuditorEncryptionKeyNotRegistered), :1601 (reassignAuditTestDataset).
• DinEmission.sol:174 (fundGI), DinValidatorStake.sol:501 (registerEncryptionKey), DINModelRegistry.sol:237 (modelId = models.length) with totalModels() at :390.

One small miss: :1584 is a line inside claimDisputeBond, which starts at :1575.

4. TP-2's test-data gap: the flag is already one-way and doesn't prove data was assigned

The plan says setTestDataAssignedFlag "only forwards a flag" and asks the reviewer "whether flag=false stays possible". On develop the auditor side (DINTaskAuditor.sol:1017-1029) already settles that:

• if (!flag) revert TA_FlagMustBeTrue();
• if (Is_testdataCIDs_Assigned[_GI]) revert TA_FlagAlreadySet();

So the flag is already one-way, and that sub-question can come out of Decision 1.

More important for the gap: neither side checks that every batch actually has test data. The flag is the owner's own claim. Gating startLMsubmissionsEvaluation on a new AuditTestDataAssigned state that the same flag sets still lets an owner start evaluation with batches that have no test data. To really close the gap, the transition should check, inside the existing setTestDataAssignedFlag, that every batch of the GI has a stored commitment (testDataCommitments[gi][b] != 0, written by assignAuditTestDataset). That costs DINTaskAuditor bytes, so it belongs in the size accounting with task-plan-051026-1's TP-1/TP-2.

Also: Is_testdataCIDs_Assigned has no reader anywhere. It's only written (:1026-1028). That matches plan 1's "unused" and this plan's coordination note.

5. Discussion No. 216 follow-ups

Discussion No. 216 (task_021026_19, closed) left these follow-ups outside that task. They belong in this plan:

Follow-up	Covered here?
model-owner deploy still uses the old constructors, without modelId	✅ TP-3 (BL-27)
No dincli commands for depositing/claiming rewards, registerEncryptionKey, disputes	✅ TP-3. Disputes depend on Decision 4
din-workflow.md still lists 4 contracts and withdraw	✅ TP-5
Old command names in roles/clients.md, roles/auditors.md, roles/model-owner.md, model-workflow.md	✅ TP-5
setup.md's broken @main#subdirectory=dist install line	❌ not in TP-5. Verified broken: Documentation/public/setup.md:42 runs pip install git+…@main#subdirectory=dist, but dist/ on main holds only wheels and sdists (dincli-0.1.0/0.2.0 .whl + .tar.gz), with no pyproject.toml/setup.py, so pip has no project to build. Option A on the same page also names dincli-0.1.0 while main ships 0.2.0
ROADMAP.md:19 "DevNet 3.0"	⚠️ TP-5 only flags it. The line is now factually wrong: it says DINTaskCoordinator "is 24,585 B … 9 B over EIP-170, so nothing on develop can deploy". PR No. 211 brought it to 23,497 B

Issue No. 223 (filed by PR No. 225 after this plan was written) tracks BL-27 + BL-28. TP-3 does both, so the spec should say TP-3 closes No. 223.

---

Amendments

1. Discussion No. 216 follow-ups: list them in "Why" as a source, with the link above, and mark each with its TP.
2. Issue No. 223: TP-3 closes it (BL-27 deploy constructors + BL-28 release slots). Name it in TP-3 and in the spec header's issue list.
3. TP-5 setup.md: add a row: replace Option B's @main#subdirectory=dist with a working install (e.g. pip install "git+https://github.com/InfiniteZeroFoundation/DevNet.git@main" from the repo root, or a direct wheel URL), and bring Option A's wheel name to the current version.
4. TP-5 ROADMAP.md:19: take it into scope. Rewrite the deploy-blocker sentence to reflect the PR No. 211 sizes and the CI gate. The "DevNet 3.0" vs "DevNet 2.0" naming stays Umer's call; flag it in the PR.
5. TP-2 test-data gate:
   • Drop the "flag=false stays possible?" sub-question; the flag is already one-way (TA_FlagMustBeTrue, TA_FlagAlreadySet).
   • Make AuditTestDataAssigned mean something by having setTestDataAssignedFlag check every batch has a stored commitment.
   • Add a test: with one batch unassigned, the flag reverts and evaluation can't start.
   • Count the bytes against DINTaskAuditor's budget, coordinated with plan 1.
6. TP-1 precision:
   • test_04_gi.py:478 passes on the name; the stale piece is the or "23" fallback.
   • test_02 → test_02_task_contracts.py.
   • :1584 → claimDisputeBond at :1575.

Everything else in the plan checks out against a1fcce2. The reviewer decisions are in a separate comment.

[umeradl]

Files changed (1) — as of b40b0b4 (PR head)

Diffed against merge-base a1fcce2, which is the current develop tip, so nothing overlaps. GitHub agrees: mergeable: MERGEABLE, mergeStateStatus: CLEAN. A local git merge-tree --write-tree dry run is clean (exit 0).

Developer/tasks-plan/umermjd11/task-plan-051026-2.md

Field	Value
Change	New
Lines	+277/-0
Diff (what exactly is in this PR)	A five-item plan for running a full GI on the foundry contracts: TP-1 contracts check (read-only, plus two text fixes), TP-2 three new GI states (AuditSeedLocked, AuditTestDataAssigned, AggSeedLocked), TP-3 dincli commands (deploy with --model-id, rewards, encryption key, release slots, claims, both dispute families), TP-4 tests/dincli/ on foundry artifacts walking a complete GI, TP-5 GI docs. It also has a sequencing table, a coordination section with task-plan-051026-1 (PR No. 219), four decisions, and a deferred list.
Functionality — how & why	How: each gap is grounded in file:line references at a1fcce2, and all of them resolve (see the verification comment). The order (contracts → dincli → suite → docs) means the commands and the suite are built on the final state machine. Why: dincli and the integration suite stopped matching the task contracts as commit-reveal, seed locks, encrypted test data, reward pools, disputes and modelId landed. Phase 1 can't pass, the suite deploys hardhat task contracts (23 states vs foundry's 26), model-owner deploy fails at ABI encoding, and there's no command to fund, key, claim or dispute. So nobody can run a DevNet 2.0 GI from dincli today.
Diff vs current develop HEAD	None — new file, branch cut from the current tip
Recommended merge proposal	Merge after the amendments in the verification comment. (1) Add the Discussion No. 216 follow-ups as a source and name issue No. 223 as closed by TP-3. (2) TP-5 gains setup.md's broken @main#subdirectory=dist line and takes ROADMAP.md:19 (now wrong after PR No. 211) into scope. (3) TP-2's test-data state checks every batch has a commitment; the flag=false question goes, since the flag is already one-way. (4) Small reference fixes in TP-1.
Actual merge proposal	Soon
Pending proposal	Decisions 1–4 (separate comment), then forwarding as one Developer/tasks/task_DDMMYY_n.md.
Local merge conflict	No
GitHub merge conflict	No

Verification

Full detail is in the verification comment above. In short: all file:line references resolve at a1fcce2. The suite and dincli gaps reproduce, including the 23 vs 26 enum count, the missing register-encryption-key command and the unbound din_validator_stake_address. Three items need changes: the test-data gate (the flag is one-way but unchecked), setup.md (dist/ on main has no buildable project), and ROADMAP.md:19. check_doc_links.py Developer resolves. GitHub CI is green.

Local vs. GitHub agree: both report a clean merge; the branch is cut from the current tip.

[umeradl]

Reviewer decisions: options and recommendations

These are the plan's four "Decisions requested". Each lists the options and a recommendation, based on the verification comment above. @umermjd11, answer per decision; the plan gets amended to match.

Decision 1: new GI states

DINTaskCoordinator has a 1,079 B margin (CI fails below 1,024 B). Each state costs an enum entry, a _setGIstate in an existing function and a changed gate check. TP-2 already says to measure each one.

Option	Effect
A. All three, in table order (as proposed)	Most visibility. If the budget runs out, the table order drops AggSeedLocked or AuditTestDataAssigned first, but AuditTestDataAssigned is the one that closes a real gap.
B. All three, but AuditTestDataAssigned first, then AuditSeedLocked, then AggSeedLocked	Same end state if everything fits. If the margin runs short, the gap-closing state is the one kept.
C. Only AuditTestDataAssigned; expose seed-lock status as views	Smallest coordinator cost. The seed locks are already readable from the stored seeds.

Recommended: B, with verification amendment 5: the state only counts if setTestDataAssignedFlag checks every batch has a stored commitment. Drop the flag=false sub-question; the auditor side already reverts with TA_FlagMustBeTrue / TA_FlagAlreadySet.

Decision 2: where the modelId check lives

Option	Effect
A. dincli-side at approval (as proposed)	No contract change. approve-registration-request compares each contract's modelId() with totalModels() and refuses on a mismatch unless --force is passed. A DIN-Rep who approves with another tool skips it.
B. Contract-side in DINModelRegistry.approveModel	Enforced for everyone. But it's a platform upgrade, and the registry has to call into task contracts it doesn't reference today.

Recommended: A for this plan. Note B as a follow-up for the mainnet registry; it's in the same area as BL-34 / issue No. 224 (the registry and task contracts don't know about each other).

Decision 3: one GI or two in the suite

Option	Effect
A. One complete GI (as proposed)	Proves every phase, claims and release-slots once. It's the shortest path to green, and issue No. 228 can then put it in CI.
B. Two GIs	Also proves startGI from GIended, the next-GI funding check and that released slots are reusable. It roughly doubles the suite's runtime.

Recommended: A, with the second GI added as an optional test (kept out of CI, with an integration + slow marker) once the first passes.

Decision 4: dispute commands in TP-3 or split out

Option	Effect
A. In TP-3 (as proposed)	Role docs (TP-5) can document disputes as they ship. It's also a Discussion No. 216 follow-up ("no commands yet for … disputes"). It adds about a day to TP-3.
B. Split into a follow-up	TP-3 and TP-4 ship sooner, but the docs keep saying "no dincli command yet" for disputes.

Recommended: A. The test-data dispute changed shape in PR No. 215: owner-only resolve, an unanswered dispute upheld on expiry, no penalty after settlement, and TA_RewardsAlreadySettled. The commands should be built and documented against that once, here.

[umermjd11]

Decisions and amendments applied (30c51e7)

Decisions (the recommended option each time):

1. New states: B. All three, prioritised as AuditTestDataAssigned > AuditSeedLocked > AggSeedLocked. AuditTestDataAssigned needs every batch to have a stored commitment, with a new TA_TestDataNotAssigned. That costs +75 B on DINTaskAuditor (measured), and the combined budget lives in task_061026_20. The flag=false question is dropped.
2. modelId check: A. dincli does it at approval, with --force. A registry-side check is noted as a mainnet follow-up (BL-34 / Three dormant/no-op mechanisms awaiting a product decision: disableModel kill-switch, rejectModel fee handling, S6 slashing (M-2, L-4, BL-31) #224).
3. Suite: A. One complete GI. A second GI comes later as an optional integration + slow test, kept out of CI.
4. Disputes: A. They stay in TP-3, built against the PR fix(task-auditor): close the test-data dispute reward-pool drain (#205) #215 dispute shape.

Amendments:

1. The Discussion task_021026_19 — P3 Deploy Blocker + Open Security/dincli Findings: EIP-170 Size Gate (#201 A), onlyCurrentGI (#206), Sender-Bound Audit Commit (#192), Auditor Commit Retry (#202), Test-Data Dispute Drain (#205), Wiki DIN-Rep (#207) (Umer Majeed) #216 follow-ups are listed as a source and mapped to TPs.
2. TP-3 closes dincli model-owner: deploy sends stale constructor args (broken); no command for releaseGIRegistrationSlots (BL-27, BL-28) #223.
3. setup.md is added to TP-5.
4. ROADMAP.md:19 is in scope, with the 2.0 vs 3.0 naming flagged.
5. The commitment-check gate and its test are added.
6. Precision fixes: the or "23" fallback, test_02_task_contracts.py, and claimDisputeBond at :1575.

Forwarding as task_061026_21 follows in a separate PR.

🤖 Generated with Claude Code

[umermjd11]

Forwarded in #232: task_061026_20 (contracts, tracked in Discussion #230) and task_061026_21 (full-GI, tracked in Discussion #231). #232 also closes task_021026_19.

[umeradl]

Re-review: amendments and decisions applied

Reviewed the fix commit: b40b0b4 (reviewed) → 30c51e7 (current HEAD), 1 file. develop is still at a1fcce2, the merge-base. git merge-tree --write-tree is clean, and GitHub reports MERGEABLE / CLEAN.

Amendments

No.	Asked	In 30c51e7
1	Discussion No. 216 follow-ups listed and mapped to TPs	New "Discussion No. 216 follow-ups" table with 6 rows, linking the real closing comment (discussioncomment-18761447) ✅
2	Issue No. 223 named in TP-3	Named in Why, in the follow-ups table and in the TP-3 heading ✅ (the spec-header issue list is in PR No. 232's task_061026_21, under Tracking)
3	TP-5 setup.md row	Added ✅
4	ROADMAP.md:19 in scope, naming flagged	Added as a TP-5 row and removed from "flagged, not changed" ✅
5	Commitment-check gate, test, bytes	setTestDataAssignedFlag checks every batch's commitment, with a new TA_TestDataNotAssigned and a new test bullet. The flag=false question is dropped (already one-way). +75 B is counted against the shared budget ✅
6	Precision fixes	or "23" fallback ✅, test_01_platform.py / test_02_task_contracts.py ✅, claimDisputeBond ⚠️ see below

+75 B re-measured: a prototype of the every-batch check on a1fcce2 (via_ir) takes DINTaskAuditor from 22,718 B to 22,793 B, exactly +75 B. Stacked with plan 1's TP-1 + TP-2, it comes to 22,575 B, matching. Details are on PR No. 219.

Decisions

All four record the recommended option: B with the priority order, A with --force and a BL-34 / issue No. 224 follow-up, A with the optional slow second GI, and A against the PR No. 215 dispute shape. The anchors were renamed to #reviewer-decisions, and they resolve.

Correction to my amendment 6

My review said ":1584 → claimDisputeBond at :1575". That was wrong. claimDisputeBond() is at DINTaskCoordinator.sol:1583, both at 740a613 and at a1fcce2. :1575 is _burnAndForward(d.bond); inside resolveDispute. So the plan's original :1584 was off by one, and my "fix" made it worse.

Fix before merge (one line)

• :188: claimDisputeBond at :1575 → :1583. The same line appears in PR No. 232's task_061026_21 Part C table and is flagged there too.

Optional nit, inherited from the original plan (:175): the NameError reference deploy.py:61-62 should be :63-64. Line 61 is blank, and the auditor-side if "stake" in … guard is at :63-64; the coordinator side, :27-28, is correct.

check_doc_links.py Developer resolves. Approved once :1583 is fixed. The status line links task_061026_21 on develop, so merge together with PR No. 232.

[umeradl]

Actual outcome — PR No. 229 merged (pushed)

This supersedes the pre-merge merge-proposal comment above with what actually happened.

Fix commit reviewed: 30c51e7 (re-reviewed) → 4ad8247 (final head). It applies the re-review fix, claimDisputeBond :1575 → :1583 (:188), and the nit, deploy.py:61-62 → :63-64 (:175). Nothing else changed.

One commit on origin/develop:

1. 9d5fa7c: a real merge of this PR (merge commit, not squash), authored by umermjd11. 0 conflicts, as predicted. GitHub agrees: the PR shows MERGED.

No deviation commit was needed. develop had moved a1fcce2 → e36f20c (only the new Developer/tasks/task_061026_22.md), which doesn't touch this PR's files.

Files unchanged from the PR (1 of 1: Developer/tasks-plan/umermjd11/task-plan-051026-2.md)

Every file landed exactly as authored at 4ad8247.

Verification

Merged in order: PR No. 219 → PR No. 229 → PR No. 232 (0a9fc54 → 9d5fa7c → 29abe22), so the plans' status links to task_061026_20.md / task_061026_21.md resolve on develop. A local CI mirror on 29abe22 was green: check_doc_links.py for Documentation and Developer, and pytest -m "not integration" with an empty HOME. Solidity was skipped because nothing under foundry/, hardhat/ or .github/ changed. Pushed e36f20c..29abe22.