[umermjd11]

Closes #274.

Abraham decided on issue No. 274 (comment) to keep the code's S5 behaviour: repeated liveness failures slash MIN_STAKE and jail for s5JailDuration, with no permanent blacklist. This PR updates Developer/design/MECHANISM_DESIGN.md to match.

Changes (Developer/design/MECHANISM_DESIGN.md only)

• S5 row (slashing taxonomy): tier changed from "Full + jail/blacklist" to "Escalated: MIN_STAKE + jail (no blacklist)".
• Full slash: now reserved for provable malice (S4) only. S5 (recidivism) has been removed from it.
• New "S5 escalation" entry under penalty tiers: describes the MIN_STAKE slash plus a s5JailDuration jail (7 days by default) and the reactivate() exit after the jail. It records the decision and its reasoning, including the correlated-outage concern from issue No. 155, and notes the possible mainnet escalation path (repeated S5 after a jail could lead to a full slash and blacklist).
• Removed: the old "Recorded here, not changed" implementation note.

Verification

• Checked against foundry/src/DinValidatorStake.sol on develop. In slashPartial, the escalation calls _applySlash(validator, MIN_STAKE, "S5_RECIDIVISM") and then _jailInternal(validator, s5JailDuration, ...). Nothing blacklists the validator. reactivate() requires the jail to have expired and activeStake >= MIN_STAKE.
• Documentation/technical/contracts/DinValidatorStake.md and Documentation/technical/mechanisms/staking-mechanism.md already describe this behaviour, so they are unchanged.
• The "full slash + jail" wording in the task specs task_100926_13 and task_240926_17 is historical spec text and was left as-is.

🤖 Generated with Claude Code

[Santiagocetran]

Thanks, Umer. Checked 8243ba6 against Abraham’s decision on #274 and DinValidatorStake. The S5 taxonomy and penalty description now match the agreed behavior, and the possible mainnet escalation is clearly marked as a follow-up rather than current policy.

One minor wording suggestion: “once the jail expires, the validator can reactivate if activeStake is at least MIN_STAKE, topping up if needed.” This avoids implying every jailed validator must top up.

No blocking content findings from me. Please sync with current develop and confirm fresh CI before merging.

[robertocarlous]

Verification — head 389121d5

Single substantive commit: 8243ba6c (Developer/design/MECHANISM_DESIGN.md, +5/-3).

Claimed / checked	Result
Merge-tree conflict check	✓ git merge-tree --write-tree --name-only origin/develop pr-286-review exits 0; GitHub: mergeable: MERGEABLE
DinValidatorStake.slashPartial S5 path: slashes MIN_STAKE, jails for s5JailDuration, no blacklist	✓ DinValidatorStake.sol lines 369–370: _applySlash(validator, MIN_STAKE, "S5_RECIDIVISM") then _jailInternal(validator, uint64(s5JailDuration), ...) — blacklistValidator is a separate, owner-only function untouched by the S5 path
s5JailDuration default = 7 days	✓ DinValidatorStake.sol line 239: s5JailDuration = 7 days
reactivate() available after jail	✓ Function at line 591 — a jailed validator who tops up can call it; no blacklist blocks this on S5
Abraham's decision recorded in issue No. 274	PR commit message cites "Abraham decided on issue 274" — recorded as a resolved decision in the doc body with date 2026-10-25
CI: Docs, Python	✓ Both pass on run for 389121d5; Solidity running (doc-only PR, not blocking)

Scope: Developer/design/MECHANISM_DESIGN.md only. No foundry/src/** touched — no second sign-off needed. This is Umer's PR documenting a mechanism decision Abraham already made on issue No. 274; the decision itself is already resolved, this PR is the record.

[robertocarlous]

Files changed (1) — as of 389121d5 (PR head)

One substantive commit (8243ba6c) diffed against merge-base ee996199 (develop). GitHub agrees: mergeable: MERGEABLE, mergeStateStatus: BLOCKED (approval only). Local git merge-tree --write-tree exits 0.

Developer/design/MECHANISM_DESIGN.md

Field	Value
Change	Modified
Lines	+5/-3
Diff	S5 taxonomy row: "Full + jail/blacklist" → "Escalated: MIN_STAKE + jail (no blacklist)". Penalty tiers: "Full slash" description narrowed to S4 only; new "S5 escalation" tier added documenting the code's behaviour, Abraham's decision (issue No. 274, 2026-10-25), the rationale, and a mainnet follow-up note. Old implementation note removed (superseded by the resolution).
Functionality — how & why	How: The design doc previously said S5 escalates to full slash + blacklist, while the code (DinValidatorStake.slashPartial) applies MIN_STAKE + jail with no blacklist. This closes the doc/code gap: the doc now matches the code and records the decision. Why: Without this fix, the design doc mis-states the live contract behaviour, which could lead contributors or integrators to expect a blacklist that never fires on S5. Abraham's decision on issue No. 274 resolved the question explicitly.
Diff vs current develop HEAD	None — no other PR has touched this file since the merge-base
Recommended merge proposal	Merged as-is — code claims verified against DinValidatorStake.sol ✓
Actual merge proposal	Soon
Pending proposal	None
Local merge conflict	No
GitHub merge conflict	No

Verification

Doc-only change. CI Docs and Python green. Code claims cross-checked against DinValidatorStake.sol (_applySlash(MIN_STAKE) + _jailInternal(s5JailDuration) in the S5 escalation branch, no blacklist call). Merge-tree clean.

Local vs. GitHub agree: both report no conflicts; BLOCKED is approval-only.

[robertocarlous]

Doc/code gap confirmed: DinValidatorStake.slashPartial S5 path applies MIN_STAKE + jail (no blacklist), matching the update. Code claims verified at lines 369-370. Merge-tree clean. Approving at 389121d.

Approval withdrawn: din_peer_check.py returns REFUSE — commit 389121d (develop-sync merge) was authored by robertocarlous, making them a co-author (MAINTAINING No. 7). Approval must come from a non-co-author: @Abidoyesimze, @Santiagocetran, or @abrahamnash.

[robertocarlous]

Correction to the review above: din_peer_check.py returns REFUSE — commit 389121d5 ("Merge branch 'develop' into docs/s5-penalty-matches-code") was authored by robertocarlous, making this a co-authored branch. The approval has been dismissed (MAINTAINING No. 7). The verification and merge-proposal comments stand; only the approval needs to come from someone else. Eligible: @Abidoyesimze, @Santiagocetran, or @abrahamnash.