!5327itz/keysign-rotation-3.22.0 → developaaed821912

Keysign leader rotation now opens at 3.22.0

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

1commits
2files
15lines changed
2lines to read
3.21.2→3.22.0rotation gate
1/3tests pin the boundary

Where the diff is

2-minute explainer

What changed

The gate moves

3.21.2 and 3.21.3 stay off; 3.22.0 opens rotation.

3.21.1 off3.21.2 off3.21.3 off3.22.0 on

What flips together

Join, signature wait and blame all share this one gate.

3 rotated leaders45s → 185sno blame

Tests

Pass at head; restoring 3.21.2 fails only the version-gate test.

TestKeysignLeaderRotationVersionGate catches it

Look here first

Confirm the release plan reaches 3.22.0Rotation stays off until the network reaches 3.22.0. No 3.22.0 branch or tag exists here, so the dependency claim is unconfirmed.keysign_leader_rotation.go:28 ↗verify
2020 // no-blame-on-sync-failure behavior. The version flows from the THORChain network
2121 // consensus version (GetThorchainVersion), which is the lowest version among active
2222 // validators, so the whole fleet flips to the new party-formation protocol atomically
2323 // once the last active node runs this release — a rotating node derives a distinct
2424 // per-attempt join id and cannot form a party with a pre-rotation peer, so an atomic,
2525 // consensus-synchronized switch is mandatory. The gate must therefore be the first
2626 // release that ships this code: a lower gate would switch nodes on one by one as they
2727 // upgrade from a release that already meets it. Mirrors frostJoinRotationVersion.
28− keysignLeaderRotationVersion = "3.21.2"
28+ keysignLeaderRotationVersion = "3.22.0"
2929 // keysignJoinAttemptDomain separates GG20 join-attempt digests from the FROST ones so
3030 // the two protocols can never collide on a shared msgID.
3131 keysignJoinAttemptDomain = "thorchain-keysign-join-attempt-v1"
3232 // keysignSignatureWaitSlack pads the rotated signature wait for start skew between
3333 // nodes, matching the slack FROST adds to its result wait (KeySignTimeout+5s).
3434 keysignSignatureWaitSlack = 5 * time.Second
3535 )
3636
3737 // keysignLeaderRotationEnabled reports whether the gated GG20 keysign leader-rotation /
3838 // no-blame protocol is active for this request version.
3939 func keysignLeaderRotationEnabled(version string) (bool, error) {
4040 old, err := conversion.VersionLTCheck(strings.TrimSpace(version), keysignLeaderRotationVersion)
4141 if err != nil {
Leader blame continues below 3.22.0This no-blame branch shares the gate, so any 3.21.x still blames a fixed leader after failed joins.keysign.go:100 ↗careful
unchanged in this MR · context
9191 Blame: blameNodes,
9292 }, nil
9393 }
9494
9595 // Leader-rotation builds (version-gated) already tried every deterministic coordinator
9696 // without forming a party and rotated the leader between attempts. A join timeout is
9797 // not signed evidence against any node, and the leader is no longer fixed, so blaming
9898 // it would serially jail an innocent node. Emit NO blame — mirrors frostJoinPartyBlame.
9999 // The error stays a join-party failure, so the UTXO rebuild-retry path is preserved.
100100 if rotationOn, verErr := keysignLeaderRotationEnabled(req.Version); verErr == nil && rotationOn {
101101 t.broadcastKeysignFailure(msgID, allPeersID)
102102 t.logger.Error().Err(errJoinParty).Msgf("messagesID(%s) fail to form keysign party (leader rotated, no blame) online:%v", msgID, onlinePeers)
103103 return keysign.Response{
104104 Status: common.Fail,
105105 Blame: blame.NewBlame(blame.TssSyncFail, nil),
106106 }, nil
107107 }
108108
109109 var blameLeader blame.Blame
110110 leaderPubKey, err := conversion.GetPubKeyFromPeerID(leader)
111111 if err != nil {
112112 t.logger.Error().Err(errJoinParty).Msgf("fail to convert the peerID to public key %s", leader)
113113 blameLeader = blame.NewBlame(blame.TssSyncFail, []blame.Node{})
Comment assumes gate equals first shipping releaseA 3.21.x patch cut from develop would ship this code dormant: safe, but the comment's rule would no longer hold.keysign_leader_rotation.go:25 ↗careful
1616 )
1717
1818 const (
1919 // keysignLeaderRotationVersion gates the GG20/ECDSA keysign leader rotation +
2020 // no-blame-on-sync-failure behavior. The version flows from the THORChain network
2121 // consensus version (GetThorchainVersion), which is the lowest version among active
2222 // validators, so the whole fleet flips to the new party-formation protocol atomically
2323 // once the last active node runs this release — a rotating node derives a distinct
2424 // per-attempt join id and cannot form a party with a pre-rotation peer, so an atomic,
2525 // consensus-synchronized switch is mandatory. The gate must therefore be the first
2626 // release that ships this code: a lower gate would switch nodes on one by one as they
2727 // upgrade from a release that already meets it. Mirrors frostJoinRotationVersion.
28− keysignLeaderRotationVersion = "3.21.2"
28+ keysignLeaderRotationVersion = "3.22.0"
2929 // keysignJoinAttemptDomain separates GG20 join-attempt digests from the FROST ones so
3030 // the two protocols can never collide on a shared msgID.
3131 keysignJoinAttemptDomain = "thorchain-keysign-join-attempt-v1"
3232 // keysignSignatureWaitSlack pads the rotated signature wait for start skew between
3333 // nodes, matching the slack FROST adds to its result wait (KeySignTimeout+5s).
3434 keysignSignatureWaitSlack = 5 * time.Second
3535 )
3636
3737 // keysignLeaderRotationEnabled reports whether the gated GG20 keysign leader-rotation /
Two tests do not pin the boundaryWait-timeout and signature-wait tests try only 3.21.1 and 3.22.0, and passed with the gate restored to 3.21.2.keysign_leader_rotation_test.go:114 ↗look
105106
106107 func TestKeysignSignatureWaitTimeoutCoversRotatedJoins(t *testing.T) {
107108 s := &TssServer{conf: tsscommon.TssConfig{KeySignTimeout: 45 * time.Second, PartyTimeout: 45 * time.Second}}
108109 cases := []struct {
109110 version string
110111 want time.Duration
111112 }{
112113 {"3.21.1", 45 * time.Second}, // pre-gate: legacy wait unchanged
113− {"3.21.2", 185 * time.Second}, // keysign timeout + slack + 3 rotated join attempts
114+ {"3.22.0", 185 * time.Second}, // gated: keysign timeout + slack + 3 rotated join attempts
114115 {"not-a-version", 45 * time.Second},
115116 }
116117 for _, c := range cases {
117118 if got := s.keysignSignatureWaitTimeout(c.version); got != c.want {
118119 t.Fatalf("version %q: wait=%s, want %s", c.version, got, c.want)
119120 }
120121 }
121122 }
122123
123124 // A party formed on a later rotation attempt signs after the keysign timeout alone has
124125 // elapsed; the rotation-sized wait must still deliver that peer's signature.
125126 func TestWaitForSignaturesReceivesSignatureFromRotatedParty(t *testing.T) {
126127 conversion.SetupBech32Prefix()
Release candidates stay on the legacy path3.22.0-rc1 sorts below 3.22.0 in VersionLTCheck, so an RC network will not exercise rotation.keysign_leader_rotation.go:40 ↗look
unchanged in this MR · context
3131 keysignJoinAttemptDomain = "thorchain-keysign-join-attempt-v1"
3232 // keysignSignatureWaitSlack pads the rotated signature wait for start skew between
3333 // nodes, matching the slack FROST adds to its result wait (KeySignTimeout+5s).
3434 keysignSignatureWaitSlack = 5 * time.Second
3535 )
3636
3737 // keysignLeaderRotationEnabled reports whether the gated GG20 keysign leader-rotation /
3838 // no-blame protocol is active for this request version.
3939 func keysignLeaderRotationEnabled(version string) (bool, error) {
4040 old, err := conversion.VersionLTCheck(strings.TrimSpace(version), keysignLeaderRotationVersion)
4141 if err != nil {
4242 return false, fmt.Errorf("fail to parse keysign leader rotation version: %w", err)
4343 }
4444 return !old, nil
4545 }
4646
4747 // keysignSignatureWaitTimeout bounds how long a node waits for a peer's keysign signature.
4848 // With leader rotation a party can form on any of frostMaxJoinLeaderAttempts join attempts,
4949 // each bounded by the party timeout, before the signing ceremony itself starts. The wait
5050 // adds those attempts and keysignSignatureWaitSlack to the keysign timeout, so a signature
5151 // from a party formed on a later attempt, or by a peer that started a little later, still
5252 // arrives while this node listens and can abort its own remaining attempts. It is a
5353 // best-effort budget, not a hard bound: the keysign timeout is an idle timeout, so a

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Blame
Naming nodes responsible for a failed TSS round, which can lead to penalties.
frostJoinRotationVersion
The equivalent gate for FROST keysign, at 3.20.0, which this GG20 gate mirrors. frost_keysign.go ↗
GG20
The threshold ECDSA signing protocol whose party formation this gate controls.
Keysign
A threshold signing round where vault members jointly sign an outbound transaction. keysign.go ↗
Leader rotation
Trying up to three deterministically ordered coordinators, each with its own join id, instead of one fixed leader. keysign_leader_rotation.go ↗
Network consensus version
The version bifrost reads from THORChain; per the gate's comment, the lowest among active validators. thorchain.go ↗