docs: automated updates for api_change

[jessiemongeon1]

Summary

Automated documentation updates triggered by recent release notes.

Changes

Triggered by MystenLabs/hashi#568: [leader] drive guardian committee handoff

• 🔴 design/docs/service.mdx
• 🔴 design/docs/guardian.mdx
• 🔴 design/docs/reconfiguration.mdx
• 🟡 design/docs/committee.mdx

Review details

design/docs/service.mdx

Looking at this documentation page, I need to assess whether it covers the new SignCommitteeTransition RPC and the guardian committee handoff mechanism driven by the leader to match on-chain epochs.

Analysis

The page describes the gRPC HashiService interface that committee members expose, but it does not enumerate or describe specific RPCs. The page also discusses the on-chain state (committee, config, etc.) but does not describe:

1. The SignCommitteeTransition RPC — a new RPC endpoint where peers sign with historical epoch BLS keys. This is a new addition to the HashiService gRPC interface and should be documented.

2. Guardian committee handoff / epoch transition — the mechanism by which the leader drives guardian committee handoff to match the on-chain epoch. The page mentions the committee block in the on-chain state diagram but doesn't describe how committee transitions work or how the leader coordinates them.

Suggested Updates

1. Add a section on gRPC RPCs (or expand the existing description)

The page currently only says the service "serves a gRPC HashiService" without listing the RPCs. A section should be added (e.g., after the introductory paragraph or as a new heading like ## gRPC Interface or ## HashiService RPCs) that describes the available RPCs, including SignCommitteeTransition. This RPC should be described as an endpoint where peers sign committee transition messages using their historical epoch BLS keys.

2. Add a section on committee transitions / epoch handoff

Either as a new section (e.g., ## Committee Transitions) or as an expansion of the on-chain state description, the page should describe:

• How the leader drives guardian committee handoff to match the on-chain epoch
• That peers use historical epoch BLS keys when signing committee transitions via SignCommitteeTransition
• The relationship between on-chain epoch changes and the guardian committee state

3. Update the Mermaid diagram (optional)

The on-chain state diagram shows committee as a block but doesn't convey that committee state includes historical epoch information or that transitions are tracked. Consider annotating or expanding this to reflect epoch-aware committee state.

design/docs/guardian.mdx

The documentation page at guardian.md is essentially a stub — it contains only a brief conceptual description of the withdrawal guardian and a note that "Additional details about the guardian integration are added before Testnet."

The PR introduces a new SignCommitteeTransition RPC where peers sign with historical epoch BLS keys, and describes how the leader now drives guardian committee handoff to match on-chain epoch. This is directly relevant to the guardian's role in committee transitions.

What needs updating:

• The entire page needs to be expanded beyond its current stub state. Specifically:

1. New section: "Committee Transition Signing" (or similar) — The page should document the SignCommitteeTransition RPC, explaining:

   • Its purpose: enabling peers to sign committee transition messages using their historical epoch BLS keys (not just current-epoch keys).
   • The flow: the leader drives the guardian committee handoff process to ensure the guardian's view of the active committee matches the on-chain epoch.

2. New section or subsection: "Guardian Committee Handoff" — The page should explain:

   • How the leader coordinates the handoff of the guardian committee when an epoch transition occurs on-chain.
   • The relationship between on-chain epoch changes and the guardian committee state.

What is currently missing:

• There is no mention of any RPC, signing mechanism, epoch-based BLS keys, committee transitions, or leader-driven handoff logic. The page has no technical detail at all beyond the 2-of-2 multisig concept.

Suggested update:
Expand the page to include at minimum:

• A description of the SignCommitteeTransition RPC and its role in the guardian workflow.
• An explanation that peers use historical epoch BLS keys (not only current-epoch keys) when signing committee transition messages.
• A description of how the leader drives the guardian committee handoff to synchronize with on-chain epoch changes.
• How this fits into the broader 2-of-2 multisig guardian model already described on the page.

design/docs/reconfiguration.mdx

Looking at this documentation page against the PR description, I need to identify what's new:

1. New SignCommitteeTransition RPC - where peers sign with historical epoch BLS keys
2. Leader now drives guardian committee handoff to match on-chain epoch

Let me analyze what the current page covers:

The current page describes the reconfiguration flow, including the BLS signing step in the "DKG or Key Rotation" section:

"Each committee member then signs a ReconfigCompletionMessage containing the target epoch and the MPC public key using their BLS12-381 key. Nodes collect signatures from each other through RPC until a quorum (2/3 of committee weight) is reached, producing a BLS aggregate signature certificate."

However, the PR introduces a new and distinct concept: a SignCommitteeTransition RPC where peers sign with historical epoch BLS keys. This is different from the ReconfigCompletionMessage signing described above. The "committee transition" and "guardian committee handoff" driven by the leader appear to be a new mechanism related to how the guardian committee (which may be distinct from or related to the Hashi committee) is handed off to match the on-chain epoch.

Updates needed:

1. In the "DKG or Key Rotation" section or a new subsection — The page should document the SignCommitteeTransition RPC. This is a new RPC endpoint where peers sign using historical epoch BLS keys (not just current-epoch keys). The current text only mentions signing ReconfigCompletionMessage via generic "RPC" — it doesn't mention SignCommitteeTransition or the use of historical BLS keys. A brief description should be added explaining:

   • The SignCommitteeTransition RPC and its purpose
   • That peers sign with their BLS keys from a historical epoch (not necessarily the current one)
   • Why historical keys are needed (e.g., the signing committee for the transition may be the old/outgoing committee)

2. Leader-driven guardian committee handoff — The page does not mention the concept of a "guardian committee" or that a leader drives the handoff to match the on-chain epoch. This could be added either in the "End Reconfig" section or as a new subsection after it, explaining:

   • That a leader node drives the guardian committee transition to align with the on-chain epoch
   • How this handoff relates to the overall reconfiguration flow

The page currently treats reconfiguration as a relatively symmetric process among committee members. The introduction of a leader-driven handoff and a specific new RPC for committee transition signing with historical keys represents a meaningful architectural addition that should be documented.

design/docs/committee.mdx

Looking at this documentation page against the PR changes:

The PR introduces a new SignCommitteeTransition RPC where peers sign with historical epoch BLS keys, and describes how the leader now drives guardian committee handoff to match on-chain epoch.

The current documentation page covers the conceptual design of the committee — registration information, why the committee is a subset of validators, and the general need for hand-off between old and new committees. It does not cover:

1. Specific RPCs or protocol mechanics — The page doesn't mention any RPCs at all, so the new SignCommitteeTransition RPC isn't something that would naturally be documented here unless the page's scope is expanded.

2. How the hand-off is driven — The last paragraph mentions that hand-off "requires that 2f+1 stake-weighted members of the old committee are alive and willing to participate" but does not describe the mechanism by which the hand-off is coordinated. The PR introduces the concept that the leader drives the guardian committee handoff to match the on-chain epoch, and that peers sign with historical epoch BLS keys during this process.

Suggested updates:

• In the last paragraph (starting with "The one downside of not having tight coupling..."), the page should be expanded to describe the hand-off mechanism in more detail:

  • The leader node is responsible for driving the committee transition to match the on-chain epoch.
  • During committee transitions, peers sign using their BLS keys from the historical epoch (i.e., the epoch in which they were active committee members), via a SignCommitteeTransition RPC.
  • This allows the old committee to authorize the transition to the new committee even though the old committee members' keys may have since been rotated.

• Consider adding a subsection such as ## Committee Transition or ## Hand-off Process after the current last section, covering:

  • The role of the leader in initiating and driving the committee transition
  • The SignCommitteeTransition RPC and its purpose
  • The use of historical epoch BLS keys (not current-epoch keys) for signing the transition, explaining why this is necessary (committee members may have rotated keys since the epoch in which they served)

This is important because the page already discusses the hand-off conceptually but lacks the concrete mechanism that the PR implements.

---

This PR was automatically generated by the Docs Impact Monitor. Please review the changes carefully before merging.

Each file edit was generated by Claude based on the release notes and a review of the existing documentation content.

[jessiemongeon1]

Style Guide Audit

Audited 4 file(s) against the Sui Documentation Style Guide.

12 violation(s) found. All must be fixed before merge.

design/docs/committee.mdx (1 violation(s))

1 violation(s) (1 regex, 0 claude)

• Line 91 — Headings use sentence case (acronyms stay capitalized)
  • Current: The SignCommitteeTransition RPC
  • Fix: Capitalize only first word, proper nouns, and acronyms

design/docs/guardian.mdx (2 violation(s))

2 violation(s) (2 regex, 0 claude)

• Line 18 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 29 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain

design/docs/reconfiguration.mdx (4 violation(s))

4 violation(s) (2 regex, 2 claude)

• Line 120 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 131 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 120 — terminology
  • Current: on-chain epoch
  • Fix: onchain epoch
• Line 131 — terminology
  • Current: on-chain epoch
  • Fix: onchain epoch

design/docs/service.mdx (5 violation(s))

5 violation(s) (5 regex, 0 claude)

• Line 16 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 20 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 24 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 31 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain
• Line 34 — "on-chain" is one word → "onchain"
  • Current: on-chain
  • Fix: onchain

---

Automated audit using the Sui Documentation Style Guide.