docs: automated updates for api_change

[jessiemongeon1]

Summary

Automated documentation updates triggered by recent release notes.

Changes

Triggered by MystenLabs/hashi#569: [guardian] add UpdateCommittee RPC for committee handoff

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

Review details

design/docs/guardian.mdx

The documentation page for the Guardian is currently a stub with minimal content — it says "Additional details about the guardian integration are added before Testnet." It does not describe any RPCs, APIs, or operational details of the guardian service.

What needs updating:

The page needs to document the UpdateCommittee RPC as part of the guardian service's API/interface. Specifically:

1. New section needed: Guardian Service RPCs (or API)

   • The page currently has no mention of any RPCs or service endpoints. A section should be added describing the guardian's RPC interface.

2. UpdateCommittee RPC documentation should include:

   • Purpose: Handles committee handoff at epoch changes.
   • Input: Accepts a SignedCommitteeTransition message.
   • Behavior/Verification: The guardian verifies the outgoing committee's threshold signature on the transition before accepting it.
   • Effect: Swaps the guardian's in-memory committee to the new committee.
   • Logging: The transition is logged to S3 for auditability/recovery.

3. Context within the page:

   • The existing content explains why the guardian exists (2-of-2 multisig, defense in depth). The new section should explain that because the guardian co-signs with the MPC committee, it must track which committee is currently active — hence the need for UpdateCommittee at epoch boundaries.

Suggested structure addition (after the existing paragraphs, replacing or supplementing the "Additional details" placeholder):

## Guardian Service API

### UpdateCommittee

The `UpdateCommittee` RPC handles committee handoff at epoch boundaries.

- **Request:** A `SignedCommitteeTransition` containing the new committee definition and a threshold signature from the outgoing committee.
- **Verification:** The guardian verifies the outgoing committee's threshold signature to ensure the transition is authorized.
- **Effect:** On successful verification, the guardian swaps its in-memory committee to the new committee.
- **Audit log:** The signed transition is persisted to S3 for auditability and disaster recovery.

This ensures the guardian always knows which committee it should expect to co-sign withdrawals with, and that committee transitions are cryptographically authorized by the prior committee.

design/docs/reconfiguration.mdx

The documentation page covers the on-chain reconfiguration flow (start_reconfig, DKG/key rotation, end_reconfig, abort_reconfig) but does not mention the new UpdateCommittee RPC on the guardian service.

The PR introduces a new guardian-service RPC (UpdateCommittee) that is part of the committee handoff process at epoch changes. It accepts a SignedCommitteeTransition, verifies the outgoing committee's threshold signature, swaps the in-memory committee held by the guardian, and logs the transition to S3. This is a distinct operational step in the reconfiguration flow that the current page does not cover.

Suggested updates

1. Add a mention of the guardian committee update step in the "End Reconfig" section (or as a new subsection between "End Reconfig" and "Abort Reconfig")

Currently, the "End Reconfig" section describes only the on-chain end_reconfig call and the subsequent presigning initialization. It should also describe the guardian-side committee handoff:

What to add (new subsection or paragraph):

After the on-chain epoch is advanced, the guardian service must also update its view of the active committee. A committee member calls the guardian's UpdateCommittee RPC, passing a SignedCommitteeTransition that contains the new committee information along with a threshold signature from the outgoing committee. The guardian verifies the outgoing committee's threshold signature to authenticate the transition, swaps its in-memory committee to the new one, and logs the transition record to S3 for auditability.

This step ensures that the guardian — which may gate-keep or co-sign certain operations — recognizes the new committee and will accept requests from its members going forward.

Suggested placement: A new heading such as ### Guardian Committee Update between "End Reconfig" and "Abort Reconfig", or as an additional paragraph/sub-heading within "End Reconfig" after the paragraph about presignatures. The Mermaid diagram for the overall flow could also be extended to include this step (e.g., C[End Reconfig] --> D[Guardian Committee Update]).

2. Mention the UpdateCommittee RPC by name so that readers searching for it can find the relevant context. Include that it:

• Accepts a SignedCommitteeTransition
• Verifies the outgoing committee's threshold signature
• Swaps the guardian's in-memory committee
• Logs the transition to S3

design/docs/committee.mdx

The documentation page covers the concept of the Hashi committee, registration information, and the rationale for why the committee is a subset of Sui validators. It mentions the hand-off process at a high level in the last paragraph but does not document the UpdateCommittee RPC on the guardian service, the SignedCommitteeTransition type, the verification of the outgoing committee's threshold signature, the in-memory committee swap, or the S3 logging behavior.

However, this page is a design/concept page about what the committee is and why it exists. The new UpdateCommittee RPC is a guardian service API endpoint — it would more naturally belong on a page documenting the guardian service's API or RPC interface rather than this conceptual page.

That said, the last paragraph of this page directly discusses the "hand-off from an old committee to a new committee" and states it as an open design concern. The new UpdateCommittee RPC is the concrete mechanism that implements this hand-off. The page should be updated to reflect that this mechanism now exists.

Suggested updates:

1. Last paragraph (starting "The one downside of not having tight coupling..."): This paragraph describes the hand-off as a requirement but doesn't mention how it's actually implemented. It should be updated to briefly describe the concrete mechanism:

   • Currently says: "The hand-off requires that 2f+1 stake-weighted members of the old committee are alive and willing to participate in the hand-off protocol."
   • Should additionally mention that the hand-off is triggered via the UpdateCommittee RPC on the guardian service, which accepts a SignedCommitteeTransition containing a threshold signature from the outgoing committee. Upon verification of the outgoing committee's threshold signature, the guardian swaps its in-memory committee and logs the transition to S3.

2. Consider adding a subsection (e.g., ## Committee Hand-off or ## Epoch Transitions) that briefly documents:

   • The SignedCommitteeTransition structure and what it contains
   • The UpdateCommittee RPC as the mechanism by which guardians are notified of committee changes
   • The verification step (outgoing committee's threshold signature must meet quorum)
   • The resulting state change (in-memory committee swap + S3 logging)

This would make the page a complete reference for committee lifecycle, not just committee composition.

design/docs/service.mdx

The documentation page needs updating to reflect the new UpdateCommittee RPC added to the guardian service.

What needs updating

Section: Top-level description of the gRPC interface

The page mentions that each Hashi node "serves a gRPC HashiService" but does not enumerate or describe any of the specific RPCs available on that service. The new UpdateCommittee RPC is a significant addition to the gRPC interface and is not documented anywhere on this page.

Suggested update

A new section should be added (e.g., after the introductory paragraph about the gRPC HashiService, and before or after the "Sui contracts" section) that describes the RPCs exposed by the service. At minimum, it should document the UpdateCommittee RPC:

Suggested new section:

## gRPC Interface

The `HashiService` exposes the following RPCs:

### UpdateCommittee

Used for committee handoff at epoch changes. This RPC accepts a
`SignedCommitteeTransition`, verifies the outgoing committee's threshold
signature, swaps the in-memory committee, and logs the transition to S3.

This section could be expanded over time as other RPCs are documented, but the UpdateCommittee RPC should be included now since it is a new API addition.

Additionally: "Stateless" section consideration

The UpdateCommittee RPC involves swapping an in-memory committee and logging to S3, which are forms of state held outside of Sui. The "Stateless" section currently states that "any state critical for the functioning of the service must be stored on Sui as part of the live object set." The in-memory committee state and S3 logging may warrant a clarification or caveat in this section — for example, noting that ephemeral in-memory state (such as the current committee) and operational logs (such as S3 audit logs) are exceptions to the on-chain state principle, or explaining how the in-memory committee is derived from or validated against on-chain state.

---

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.

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

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

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

• Line 21 — passive_voice
  • Current: the transition is authorized
  • Fix: the outgoing committee authorized the transition
• Line 22 — passive_voice
  • Current: the guardian swaps its in-memory committee to the new committee.
  • Fix: (no violation - line 22 is fine; flagging line 23 instead)
• Line 23 — passive_voice
  • Current: The signed transition is persisted to S3
  • Fix: The guardian persists the signed transition to S3
• Line 25 — passive_voice
  • Current: transitions are cryptographically authorized by the prior committee
  • Fix: the prior committee cryptographically authorizes committee transitions

---

Automated audit using the Sui Documentation Style Guide.