docs(tbtc-signer): spec doc updates for Decisions 5, 6, 7, 8, 9 (#4253) [DRAFT] - #4260
Draft
piotr-roslaniec wants to merge 2 commits into
Draft
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Updates FROST shadow-mode phase-freeze docs, opaque DKG session handle spec, ROAST adaptive timeout / terminal error class, and the per-(sender, key_group) interactive rate-limit spec to match the Decision 7 implementation in src/engine/policy.rs (env var names, defaults, and enforcement points corrected against the actual config.rs constants).
piotr-roslaniec
force-pushed
the
followup/4253-spec-doc-updates
branch
from
August 18, 2026 15:34
cb42033 to
e86cb66
Compare
piotr-roslaniec
changed the title
piotr-roslaniec
marked this pull request as draft
August 18, 2026 15:35
…ec addendum - roast-coordinator-seed-derivation.md: COORDINATOR_SHUFFLE_VERSION paragraph was written in present tense implying it's already fed into the attempt-context hash. It doesn't exist in the current derivation (0 matches in src/, roast_attempt_shuffle_seed hashes only key_group||session_id||rfc21_message_digest). Rewritten as an explicit design note for the eventual migration. - roast-phase-0-spec-freeze.md: addendum postscript said 'the other four' recoverable codes; the table lists five (consumed_nonce_replay, interactive_attempt_already_aggregated, interactive_rate_limit_exceeded, interactive_cross_operator_cap_exceeded, interactive_round1_rate_limit_exceeded).
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.
Status: DRAFT
This PR is a docs-only change. It targets
extraction/frost-signer-mirror-2026-05-26(PR #4005's head at555f2c514) so the diff against that base is the spec doc update only. It cannot be merged until the corresponding implementation lands in PR #4005 — the docs document the Decisions 5, 6, 7, 8, 9 implementations in that PR, none of which are in this PR's diff base. Marked draft until #4005 is merged (or this PR is re-targeted once #4005 lands).Summary
Updates the spec docs to match the Decisions 5, 6, 7, 8, 9 implementations in PR #4005.
Files updated
pkg/tbtc/signer/docs/permissioned-signer-hardening-rfc.md— FROST shadow-mode phase-freeze, opaque DKG session handle, ROAST adaptive timeout / terminal error class, per-(sender, key_group)interactive rate limits.pkg/tbtc/signer/docs/phase-7-interactive-session-spec-freeze.md— opaque DKG session handle.pkg/tbtc/signer/docs/roast-coordinator-seed-derivation.md— ROAST adaptive timeout, terminal error class.pkg/tbtc/signer/docs/roast-phase-0-spec-freeze.md— error taxonomy addendum (Decision 7 reason codes, including the newinteractive_cross_operator_cap_exceededfor the cross-operator cap atInteractiveSessionOpen).pkg/tbtc/signer/docs/roast-phase-5-security-rollout-gates.md— operator SOP cross-reference.Decision 7 rate-limit spec correction
The original draft of the Decision 7 rate-limit section had three bugs: invented env-var names, a wrong claim that the cross-operator cap was enforced at
InteractiveRound1(it is enforced atInteractiveSessionOpen), and a wrong claim thatInteractiveRound1reused the cross-operator bucket (it has its own independent primary bucket). All three are corrected in this commit against the actualsrc/engine/config.rsconstants and the actualenforce_interactive_*functions:TBTC_SIGNER_INTERACTIVE_OPEN_RATE_LIMIT_PER_MINUTE(default 60/min) — primary bucket atInteractiveSessionOpen, surfaces asinteractive_rate_limit_exceeded.TBTC_SIGNER_INTERACTIVE_OPEN_CROSS_OPERATOR_CAP_PER_MINUTE(default 5/min) — cross-operator cap atInteractiveSessionOpen, surfaces asinteractive_cross_operator_cap_exceeded.TBTC_SIGNER_INTERACTIVE_ROUND1_RATE_LIMIT_PER_MINUTE(default 60/min) — independent primary bucket atInteractiveRound1, surfaces asinteractive_round1_rate_limit_exceeded. There is no separate cross-operator cap onInteractiveRound1.The
roast-phase-0-spec-freeze.mderror taxonomy addendum was also corrected in the same pass — the original entry forinteractive_round1_rate_limit_exceededincorrectly described it as the cross-operator cap surface; it now correctly describes the Round1 own-bucket surface, and a newinteractive_cross_operator_cap_exceededentry is added for the actual cross-operator cap.Implementation dependency (this PR cannot be merged standalone)
The doc corrections above describe behavior that is implemented in PR #4005. None of the Decision 7 env-var constants,
enforce_interactive_*functions, or the newinteractive_cross_operator_cap_exceededreason code exist in this PR's base (555f2c514). The docs are correct against PR #4005's implementation, not against the base. Either:Marked draft to prevent the docs from being merged without the implementation they describe.
Out of scope