docs(protocol): slashing, auth surface, upgrade discipline#145
Merged
docs(protocol): slashing, auth surface, upgrade discipline#145
Conversation
Three new pages under /developers: - slashing.mdx: lifecycle (Pending/Disputed/Executed/Cancelled), authorization table with preconditions, configuration parameters with bounds and defaults, operator runbook (received-a-slash, leave-the-network), SLASH_ADMIN runbook (review-a-dispute, detect-stuck-state), dispute economics including bond fallback semantics, per-asset commitment slashing, and the future-evolution path through UUPS upgrade. - auth-surface.mdx: every privileged function in Tangle, MultiAssetDelegation (split across StakingAdminFacet/StakingAssetsFacet/StakingSlashingFacet/ StakingOperatorsFacet), MBSMRegistry, the beacon stack (ValidatorPodManager/L2SlashingReceiver/L2SlashingConnector), and governance (TangleTimelock/TangleGovernor/TangleToken). Role registry clarifies that Tangle and MAD do not share role constants and that MAD has neither UPGRADER_ROLE nor PAUSER_ROLE; both flow through ADMIN_ROLE. - upgrade-discipline.mdx: per-contract _authorizeUpgrade gate (UPGRADER_ROLE on most peripherals, ADMIN_ROLE on MAD, onlyGovernance on TangleGovernor, onlySelf on TangleTimelock), storage gap rules with discipline checklist, the OZ ERC-7201 namespaced slot used for TangleTimelock._minDelay (0x9a37c2aa...fb3600 + 1, pinned to OZ Upgradeable 5.1.0), parameter migration playbook, and post-deploy role-renunciation assertions. Code links pin to tangle-network/tnt-core@main. No em dashes; ASCII punctuation only. Headings in title case to match neighboring developer docs. All three pages were cross-checked by parallel audit subagents against the on-chain code and corrected for factual accuracy: dispute bond fallback semantics (bond restored on transfer fail rather than silently lost), instant slash flag is reserved (not exposed through the public proposeSlash entrypoint), MAD's actual role surface (no UPGRADER_ROLE), TangleMetrics added to the upgradeable list. Wired into pages/developers/_meta.ts under "Protocol Integration".
✅ Deploy Preview for tangle-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three new pages in
/developers/covering protocol mechanics that the docs site previously had no canonical home for. Each page was cross-checked by an audit subagent against the live tnt-core source and corrected for factual accuracy.slashing.mdxLifecycle (Pending / Disputed / Executed / Cancelled), authorization with preconditions, all six
SlashConfigparameters with bounds and defaults, operator runbook (received-a-slash, leave-the-network), SLASH_ADMIN runbook (review-a-dispute, detect-stuck-state), dispute economics including bond fallback semantics, per-asset commitment slashing, and the upgrade-driven evolution path.auth-surface.mdxEvery privileged function in:
Tangle(Base / Slashing / Blueprints / Operators / Services / Payments)MultiAssetDelegationsplit by facet (Admin / Assets / Slashing / Operators)MBSMRegistryValidatorPodManager,L2SlashingReceiver,L2SlashingConnector)TangleTimelock,TangleGovernor,TangleToken)Plus a role registry that clarifies Tangle and MAD do NOT share role constants, and that MAD has neither
UPGRADER_ROLEnorPAUSER_ROLE.upgrade-discipline.mdxPer-contract
_authorizeUpgradegate, storage gap rules and discipline checklist, the ERC-7201 namespaced slot used forTangleTimelock._minDelay(with the OZ-version pinning rule), parameter migration playbook, post-deploy role-renunciation assertions.Style
protocol-architecture.mdxandoperators/runbook.mdx.tangle-network/tnt-core@main.Cross-check evidence
Audit subagents ran against
~/code/tnt-core/and found the following errors which are now corrected:_authorizeUpgradeonUPGRADER_ROLE". False for MAD (ADMIN_ROLE), Governor (onlyGovernance), Timelock (onlySelf).TangleMetricswas missing from the upgradeable list.setTreasuryandsetPaymentSplitare NOTwhenNotPaused(they live inPayments.sol, notBase.sol); the blanket "all admin setters arewhenNotPaused" claim is now qualified.setMinOperatorStake,setSlasher); replaced with the real functions fromStakingAdminFacet/StakingAssetsFacet/StakingSlashingFacet/StakingOperatorsFacet.addVersionrejects EOA targets, not callers; clarified._startLeavingrequires zero pending slashes AND zero active services; the runbook previously listed only the slash precondition.instantSlashEnabledflag has no effect through the standard publicproposeSlash(which hardcodesinstant=false); doc now reflects that it is reserved for future use.Test plan
next devand confirm the three new pages render under/developers/{slashing,auth-surface,upgrade-discipline}.