Files
giza-kmp/docs/frost-share-refresh.md
T
Kgothatso NgakoandClaude Opus 5.5 cc21d68356 feat: the Shares section says whose share a rotation takes away; the record (admin-change-rotation, Phases 7 and 8)
The running card names the members whose share it takes away because
the group removed them as admin, and their rows read Share being
rotated away instead of Holds a share. Removing an admin says nobody
is asked again.

The plan is marked built, with where the build chose differently, and
the notes it changes point to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 11:11:32 +02:00

52 KiB
Raw Blame History

FROST share refresh and re-enrollment

The goal: give every member of a group a new share of the same threshold key, so the group signs as it always has (same key, same room, same certificates) while the shares it held before stop being useful. Those old shares may be a lost phone's, a removed member's, or a database a backup service still holds.

This is a phased plan, built: every phase is in, one or two commits each, with the gaps named in the table below. It was written against d4dd87f2 on 2026-11-19, right after submodule-refresh.md carried reduced (v2) FROST enrollment up to Giza. Read shared-key-ceremony.md and shared-key-derivation.md first. Everything below assumes the ceremony they describe and the rule that a room's id is the key it signs with.

Where it stands

phase commit checked
1 zkp 8477b7c1, a7c54598, e30c8a16, 31ea015c tests -t=frost_refresh (vectors, roundtrip n 2..5, withheld, sequential, recovery, faults, binding, params, lengths); full tests suite; ctime_tests under valgrind (RelWithDebInfo) clean; autotools build. Not reviewed (D4)
2 secp256k1-kmp 7fd0d34, 8beb781, 0f5a710 :tests:jvmTest and :tests:linuxX64Test 112/112, the zkp vector byte for byte through both backends
3 bitcoin-kmp d2e15b8, 3cd82d1 jvmTest 274/274, including withheld → repaired with FrostReducedEnrollment → signs
4 lightning-kmp 2043f254, lightning-kmp-app 3794eb8, Giza Phase 4 lightning-kmp crypto tests 104/104; Giza compileDebugKotlinAndroid, jvmTest 1183/1183, audits
7 f8974aec ShareRefreshRitualJvmTest (7: three devices with real host keys refresh through the real zkp module and then sign at generation 1 as the same room; nothing published before approval; a withheld member follows to the new table with no share and declines to sign; a minority refused; one confirmation per generation; a second proposal hands back the first; a redelivered transcript changes nothing); jvmTest 1190/1190; compileDebugKotlinAndroid; audits
8 51615992 three more in ShareRefreshRitualJvmTest: once the group signs the generation-1 key state every device deletes the ceremony's share and its randomness and still signs; a gen-0 session left open fails with "This share was rotated before the session finished"; a key state at an older generation loses whatever its timestamp. jvmTest 1193/1193; compileDebugKotlinAndroid; audits
9 c4fe4c9c two more in ShareRefreshRitualJvmTest: rotating without a removed member of a 2-of-3 leaves the other two signing at generation 1 and the removed member's old share signing nothing with a new one; a 2-of-2 is refused with "fewer than the 2 it takes to sign". jvmTest 1195/1195; compileDebugKotlinAndroid; audits. The dialog has not been seen on a device
10 1c3e0e93 three more in ShareRefreshRitualJvmTest: 10a, a stale member repaired by two helpers into generation 1 and signing with one of them; a repair checked against the wrong public share fails at round 2 and stores nothing, and nobody marks the member live without a proof; 10b, a new identity's request waits with nothing sent until the group signs the binding, then is repaired and holds the id's share. jvmTest 1198/1198; compileDebugKotlinAndroid; audits
11 99229090 compileDebugKotlinAndroid; the M3 audit at its budgets. Not seen on a device or a desktop window
12 4949f0fe ShareRefreshRitualJvmTest: three refreshes in a row, then the recovery walk from the generation-0 share lands on every device's live share, each generation checked against its table. jvmTest 1200/1200
13 99229090 ShareRefreshRitualJvmTest: with the flag off, the recipients decline a rotation out loud and it fails; proposing one throws. Android, desktop and iOS device checks not done
after 13 159ae402, d358a0db, 98567629, 95131248 rotation-waits-for-key-state.md: a rotation waits for the group to sign the last one's key state, the Shares section says why, follows the group while open, and the proposer is not asked about their own rotation. ShareRefreshRitualJvmTest 25/25, ChatRoomDetailSharesJvmTest 3/3; ./gradlew check (jvmTest 1240/1240, testDebugUnitTest 496/496, lint, audits). Not seen on a device or a desktop window
after that rotate-shares-single-approval.md taking part is a rotation's only approval: CONFIRM is gone, the proposer's dialog is its approval, the new generation's key state signs itself, and a running rotation can be abandoned from the Shares section. See that note
5 4040ae74 SecureDeleteJvmTest (5, two of them controls that fail without the fix); jvmTest 1176/1176; compileDebugKotlinAndroid, processDebugResources
6 fce51e20 ShareGenerationsJvmTest (7: a real 2-of-3 signature with hand-refreshed shares verifying as the unchanged room, a decline from a device without the generation, a withheld member who is not a signer); every existing signing test unedited; jvmTest 1183/1183; compileDebugKotlinAndroid; the M3, brand and wallet audits

Pushed on 2026-11-19, bottom up, as claude/frost-share-refresh at every level (zkp to code.sigidli.com/frost/secp256k1-zkp, secp256k1-kmp, bitcoin-kmp, lightning-kmp and lightning-kmp-app to github.com/kngako), and every parent's pin checked against its child's remote branch. The tracked branches (main, threshold, master) are untouched: moving them is a fast-forward to these branches once the work is reviewed, as submodule-refresh.md did.

Where the build chose differently from the plan:

what the plan said what it turned out to be
Phase 5: a test overwrites a share and finds no copy three. An overwrite in this schema happens to write the new cell over the old share, so it passed with secure_delete off too and proved nothing; a deleted row is the control that fails without it. And secure_delete alone leaves the share in -wal until a truncating checkpoint, so GizaDatabase.scrubFreedPages is part of the fix, with its own control
Phase 1: the module's C API adds secp256k1_frost_refresh_params_parse, so the bindings carry the parameters as their serialization and parse them in every call, holding nothing between calls. Faults reuse secp256k1_chilldkg_fault, with the fault index a position in the recipient list; bitcoin-kmp's FrostRefreshFault translates it to an identifier. The round-1 zero-randomness check was variable time, which ctime_tests found; it is secp256k1_is_zero_array now
Phase 1: an investigation procedure none. A dealt value that does not match the commitments is UNKNOWN_FAULTY_PARTICIPANT_OR_COORDINATOR and the session must be abandoned; frost_refresh.md names it as future work
Phase 6: a manual MIGRATION_37_38 backfills generation 0 into the new tables no backfill, and no manual migration. Generation 0 stays where the ceremony wrote it, read by ShareGenerations with ids derived from the host keys exactly as signerIds derived them; rows exist from generation 1 on. A copy of generation 0 would have been a second source of truth for the one fact signing most needs to agree with the ceremony about, and ShareGenerationsJvmTest asserts the derivation instead of a copy. The migration is a Room AutoMigration
Phase 6: a session at a generation this device lacks declines so does one whose frost_generation is present and unreadable, filed at generation -1 so nothing reads it as a share this device holds. A decline's reason is FrostSigningManager.GENERATION_REFUSAL
Phase 6: (not in the plan) DkgSessionDao.getKeyHoldingSessions now counts a share of any generation, and completedKey asks ShareGenerations.canSign, so a refreshed key whose ceremony share is wiped is still found -- and a member withheld from the newest refresh is offered nothing to sign. ShippedProfileUpgradeJvmTest pins the built version at 38
Phase 7: the refusals one more: every participant not retired has to be a recipient or withheld, so a proposal cannot leave someone in neither list. A participant stale at the base generation is withheld again, as stale, automatically: a refresh brings nobody back, a repair does. A recipient that refuses a proposal on arrival broadcasts a failure, since the certificate needs it; anyone else refuses silently. D5's capability check waits for Phase 13
Phase 7: a kill between storing the pending generation and sending the confirmation handled the way the plan said -- confirmAndStore is idempotent for the refresh that holds the claim, so the next pass stores it again and sends -- but not tested on its own
Phase 7: the transcript system lines through RitualNotice, settled. The request line opens nothing until the refresh screen exists (Phase 11)
Phase 8: any recipient proposes the new key state the coordinator does, automatically, the moment its refresh completes; anyone can again. That races the certificate to the other devices, and lost in the first test run: a device still holding the generation as pending declined. A proposal at a generation this device has confirmed and is waiting on the certificate for now waits instead, and the refresh resumes it on activation (FrostSigningManager.resumeAt). "Anyone can again" had no button until rotation-waits-for-key-state.md: the Shares section offers it when the key state is owed and nobody is asking
Phase 8: ShareRefreshCutoverJvmTest the cutover tests live in ShareRefreshRitualJvmTest, which has the multi-device harness. The bytes-on-disk check is SecureDeleteJvmTest's, against a file; these devices are in memory. A device that disagrees with the group's table keeps its share and logs it, untested
Phase 8: gen-0's randomness nulled emptied: round1Random and round2AuxRandom are not nullable, and a complete ceremony never reads them again
Phase 9: an action on the members screen a dialog the room detail screen raises after a removal succeeds, when the member held a live share (asked before the removal, while they are still in the roster). "Not now" leaves it; nothing offers it again yet -- Phase 11's Shares section is where a rotation can be started at any time. MemberRemovalRefreshJvmTest is two tests in the ritual harness
Phase 10: pairwise channels -- a gift wrap to one npub, or the MIP-03 carve-out NIP-44 between the two ChillDKG host keys, as room-wide inner events. Only the two endpoints hold the conversation key, so the room can carry the message without reading it, and the keys are the ones the refresh already encrypts to -- including a new identity's, which it names in its request
Phase 10: other devices learn a repair succeeded the target proves it: a Schnorr signature by the repaired share over the session id, checked against the group-signed public share before any device marks the id live (kind 30349, DONE). Kinds 30346-30349
Phase 10b: a frost_member tag id:npub:hostkey, kept on GroupKeyState.memberBindings (schema 40) and applied to the roster of that generation when the group's signature is filed -- only to an id that is not live. A key state at a generation already on file is stamped at least a second after it: the first 10b test run lost a binding to a tie with the state it amended, in the same second
Phase 10b: the newcomer's device seeded in the test with the key's public record, as the member chronicle would hand it over; that hand-over is not built for share generations yet
Phase 11: a Shares section on the key's screen, a refresh screen, a repair screen one Shares section on the room detail screen, carrying all of it: the generation, each member's standing, every approval this device owes with approve and abandon, and the two actions. No pushed screen, and so no route; the transcript's request lines still open nothing. The stale "banner" is the member's own standing, "Waiting to be brought back", above an "Ask to be brought back" button
Phase 12: the recovery walk ShareGenerations.recover and recoverFrom. The walk stops at a generation this host key was withheld from, since a repaired share leaves no recovery data -- a repaired member restoring from the phrase is repaired again. Nothing calls it yet: wiring it into a restore flow is the restore flow's
Phase 13: the flag ExperimentalFeatures.shareRefresh, from isDevelopmentBuild(): BuildConfig.DEBUG on Android, an unpackaged run or -Dgiza.experimental=true on desktop, Platform.isDebugBinary on iOS (unbuilt). D5's capability is not built: nothing advertises support, so a refresh including a member on an older build waits on them until a recipient abandons it
Phase 5: dataExtractionRules or allowBackup="false" both. From Android 12 allowBackup="false" stops cloud backup but not a device-to-device transfer

The headline: enrollment cannot rotate a share

The word in the request is re-enrollment, and the enrollment module that just arrived looks like the tool for it. It is not, and the reason is what the rest of the plan rests on.

A t-of-n FROST key is a polynomial f of degree t−1 with f(0) = x, the group secret. Member j holds s_j = f(x_j). Any t points on f reconstruct x.

Enrollment, v1 and v2, and in both its modes, evaluates the same f somewhere else.

  • newId == n gives a new member f(x_n).
  • newId < n ("repair") gives back exactly f(x_k).

FrostEnrollment's own KDoc says it: "every existing share [is] unchanged by an enrollment". So re-enrolling every member, even at fresh identifiers, hands out new points on the old polynomial. Every old share stays a valid point on it. A removed member's share plus t−1 new ones still signs, and a leaked backup is exactly as dangerous as before.

Rotation needs a different f. That is a proactive share refresh (Herzberg et al., 1995):

  1. Every dealer i picks a random polynomial δ_i with δ_i(0) = 0.
  2. Each member adds the sum to their share: s_j' = s_j + Σ_i δ_i(x_j).
  3. The new shares lie on f' = f + Σ δ_i. Because every δ_i(0) = 0, f'(0) = x, so the key does not move.
  4. A mix of old and new shares interpolates to garbage. Only t old shares together still reconstruct x, which is why "rotating away" also needs the old ones deleted (see What it protects against).

Neither secp256k1-zkp, secp256k1-kmp nor bitcoin-kmp has this today: the grep is for refresh and reshare across Secp256k1.kt and the frost/chill wrappers. Building it is the first half of this plan.

Enrollment still has a job here, and it is the half that earns the word re-enrollment:

  • Refresh rotates the shares of the members who take part.
  • Repair (v2 FrostReducedEnrollment, newId < n) brings in a member who could not take part: offline, or on a new device. It gives them their point on the new polynomial, which their old device never had.

A member who was withheld from a refresh and is never repaired is, cryptographically, removed. So rotation, removal and recovery from a lost device are one protocol plus one repair.

Vocabulary

term meaning
key a ChillDKG output: threshold public key X, identified by its dkgSessionId, which is also the frost_key tag. Never changes
participant id a member's index in the ChillDKG order (the sorted host keys; FrostSigningManager.signerIds). Fixed for the life of the key; n fixed until an enrollment grows it
generation g which polynomial the shares are on. 0 is ChillDKG's output; each completed refresh adds one
standing per id, per generation: live (holds a share of g), stale (withheld, awaiting repair) or retired (withheld for good; never repaired)
recipients R the ids a refresh delivers to. Every recipient is also a dealer
withheld W the live ids a refresh delivers nothing to. They come out stale or retired, as the proposal says

What a refresh protects against, and what it cannot

This section matters most for the UI copy, because the action sounds stronger than it is.

It protects against an attacker who collects fewer than t shares of any one generation:

  • a stolen or lost phone's database;
  • aux.db in a cloud backup;
  • a removed member's share, once the others have deleted theirs.

After a refresh the attacker needs t shares of the new generation, and what they hold is of the old one.

It cannot protect against:

  • Honest deletion failing. Two members who keep their generation-g shares after a refresh still hold two points on f. If t old shares ever meet, the key is gone, refresh or not. The plan wipes old shares (Phase 8), but a wipe on one device proves nothing to the others.
  • A compromised nsec. The ChillDKG host key is sha256("mantra/chilldkg/host-key/v1" || nostrPriv). ChillDKG's participantRecover(hostSecretKey, recovery) rebuilds the generation-0 share from it and the public transcript. So every member's generation-0 share can always be rebuilt from their nsec, whatever is wiped. A refresh moves the group past a leaked share, never past a leaked identity. A member whose nsec is compromised has to be withheld and repaired under a new identity (Phase 10b), not refreshed.
  • An adversary already holding t shares of the current generation. They have the key. A refresh is not a recovery from that; only a new ceremony is, and it gives a new key and a new room.
  • The threshold. A refresh keeps t and n. Changing t is a reshare, which is out of scope (what this does not do).

Two things in the tree today undercut even the protections listed above, and they are preconditions for the rest (Phase 5):

  • DkgSession.secretShare is plaintext hex in aux.db, under an "encrypted local storage" assumption (DkgSession.kt) that the database does not meet: BundledSQLiteDriver, no SQLCipher, no keystore. round1Random and round2AuxRandom sit beside it and rebuild the share on their own.
  • AndroidManifest.xml has android:allowBackup="true" with no dataExtractionRules, so aux.db goes to the platform backup. A share that has been backed up cannot be rotated away from by anything this app does afterwards, short of every other member deleting theirs.

Decisions this plan asks for

Each has a recommendation. Decide them before Phase 1; several change the wire.

Decided 2026-11-19: all eight as recommended. Execution began the same day. Part B (Phases 5–6) runs first because it needs nothing from Part A; Part A's pushes wait on an explicit go-ahead, since a parent may only pin what the child's remote has.

# question recommendation if decided otherwise
D1 Where does the refresh primitive live? In secp256k1-zkp, as a frost_refresh module beside frost_enrollment, with bindings up the chain the way enrollment came. It shares the frost module's identifier-to-evaluation-point convention, gets Python vectors, and goes through the same review In bitcoin-kmp, as Kotlin over PrivateKey/PublicKey arithmetic (each op calls libsecp256k1). Phases 1–2 collapse into Phase 3 and the chain bump shrinks. The cost: protocol code with no reference implementation and no vectors, in a place no cryptographer reviews
D2 Who has to take part? Every recipient. A refresh cannot finish until all of R confirms, the same rule ChillDKG has. Anyone not taking part is withheld and repaired afterwards Letting a refresh finish without some recipients means a member who later finds their delta inconsistent has no one to complain to. Repair already covers the absent member
D3 How are two concurrent refreshes kept from forking the group? Two rules together. (a) A device confirms at most one refresh per (key, base generation), write-once, like the nonce rules on FrostSigningSession. (b) ` R
D4 Ship gate Behind a build flag, off in release, until upstream drops "experimental" from frost_enrollment and frost_refresh has had independent review. submodule-refresh.md Phase 6 already says this for enrollment Shipping earlier means accepting unreviewed key-handling code on the group's only key
D5 Groups with Bennu members Refuse a refresh whose recipients include a member whose client has not advertised support. A Bennu peer cannot take part, so the refresh would withhold them, which removes them from signing Port the protocol to Bennu first (Giza → Bennu is a cherry-pick, the reverse of giza-rebrand.md Phase 9)
D6 When is the old share wiped? Once the group has signed the generation-g+1 key state (30326). That signature is the proof that t members can sign with the new shares. Before it, a broken refresh would otherwise leave nothing to sign with Wiping at the certificate is earlier, but trusts that the new shares work without a signature showing it
D7 Where does a refresh run? In the Marmot room whose id the key derives, p-tagging the recipients, as a subgroup's ceremony does in its parent. A key with no room yet cannot be refreshed. Its holders can just run the ceremony again The NIP-17 room the ceremony ran in. That room has no record of removals, which is what a refresh is most often for
D8 Does removing a share holder from the room offer a refresh? Yes, as a separate, named step after the MLS removal, never folded into it. Removal is one member's decision; a refresh needs every recipient Silent: the removed member keeps a working share indefinitely, which is today's behaviour (MarmotOutboundDao.removeMember touches MLS only)

The protocol

This is the shape the primitive should have, written so Phase 1 has a spec to start from and Phases 7–8 have something to persist. It is EncPedPop and CertEq from ChillDKG with the constant term removed. Reusing ChillDKG's structure means reusing its review, its blame and its recovery story.

Inputs everyone already holds

  • The threshold key X, participant count n and threshold t.
  • The host public keys in ChillDKG order.
  • The generation-g public-share table P_0 … P_{n−1}.
  • The recipient set R, which the proposal names and which sorts to a canonical order.
  • A refreshId: 32 fresh bytes chosen by the proposer, bound into every hash the way v2 enrollment binds sessionId.

Session parameters hash. H(tag ‖ X ‖ n ‖ t ‖ g ‖ hostkeys ‖ R ‖ P-table ‖ refreshId). Every message carries it. As with ChillDKG's ordering, a device that disagrees on any input gets no refresh rather than a weaker one.

Round 1: each recipient deals

Each recipient i in R does the following:

  1. Draws δ_i(x) = a_{i,1}x + … + a_{i,t−1}x^{t−1}. There is no constant term and so no proof of possession: there is no secret contribution to prove.
  2. Publishes the commitments A_{i,m} = a_{i,m}·G for m = 1…t−1: t−1 points.
  3. For every j in R, encrypts δ_i(x_j) to j's host key, with a pad derived from ECDH and bound to the parameters hash, i and j. This is EncPedPop's construction.

Nothing is encrypted to a withheld id. That is what withholding means. A withheld member never learns their point on f'.

Coordinator: aggregate

The coordinator sums the commitments, A_m = Σ_i A_{i,m}, and packages each recipient's ciphertexts. It is untrusted, as in ChillDKG: it relays and sums, and can neither learn a delta nor bias one.

Round 2: each recipient checks, persists, confirms

  1. Decrypt and sum: d_j = Σ_i δ_i(x_j).
  2. Feldman check: d_j·G == Σ_m A_m · x_j^m. On failure, blame by investigation, as ChillDKG does.
  3. Compute the new share s_j' = s_j + d_j.
  4. Compute every id's new public share, including withheld ones: P_k' = P_k + Σ_m A_m · x_k^m. This needs only public data.
  5. Check s_j'·G == P_j' and frostThresholdInfoValidate(X, P', t).
  6. Persist generation g+1 as pending.
  7. Only then sign CertEq over the transcript with the host key. A confirmation means "I have stored it", so a certificate means everyone has.

Certificate

The coordinator collects every recipient's CertEq signature into a certificate. A device that verifies it moves g+1 from pending to active.

Recovery data for generation g+1 is the round-1 transcript (commitments and ciphertexts) plus the certificate: everything public. With the host key it rebuilds d_j; on top of generation g it rebuilds s_j'. So the chain ChillDKG recovery → refresh 1 → … → refresh g restores any generation from the nsec. That is the same property generation 0 has today, and the same limit.

Repair of a withheld id (re-enrollment)

Repair uses v2 FrostReducedEnrollment with newId = k < n and helpers drawn from the live ids of the current generation (t ≤ u).

The expected public share is P_k' from the group-signed generation table (Phase 8): never from the helpers, as submodule-refresh.md Phase 6 requires.

v2's messages are raw scalars, so they need a confidential, authenticated channel per pair. That is a gift wrap to one npub in a NIP-17 room, and the MIP-03 one-to-one carve-out in a Marmot room (marmot-direct-messages.md). Never an MLS application message: every member of the room can read those.

Phases

Four parts.

  • A (1–4) is library work, below Giza. It follows submodule-refresh.md procedurally.
  • B (5–6) makes Giza ready for a share to change, and changes no behaviour.
  • C (7–8) is the refresh itself.
  • D (9–13) is what makes it usable.

One commit per phase, as the other plans do.


Part A: the primitive

Phase 1: frost_refresh in secp256k1-zkp

On a branch of frost/secp256k1-zkp main, beside frost_enrollment.

  • The spec text first, in the module's README, covering everything in the protocol:
    • the parameters hash;
    • round 1 (dealer);
    • coordinator aggregate;
    • round 2 (recipient verify and new share);
    • public-share table update;
    • CertEq;
    • recovery;
    • participant and coordinator investigate.
  • A Python reference in the style of the enrollment generator, emitting frozen vectors.
  • C functions, roughly mirroring chilldkg_*:
    • frost_refresh_params_hash
    • frost_refresh_participant_step1
    • frost_refresh_coordinator_step1
    • frost_refresh_participant_step2, which returns the new secret share, the new public-share table and the CertEq signature
    • frost_refresh_coordinator_finalize
    • frost_refresh_participant_finalize
    • frost_refresh_participant_recover
    • frost_refresh_*_investigate
  • Tests, each one a property worth its own name:
    • refresh then sign: the signature verifies under the unchanged X;
    • t new shares sign, and a mix of old and new does not (with overwhelming probability);
    • t old shares still reconstruct. This is the honest-deletion caveat as a test, so nobody mistakes it for a bug later;
    • P_k' for a withheld k equals what a repair at k produces;
    • every malformed and inconsistent input lands on the right blame;
    • recovery from host key and transcript equals the share computed live;
    • two consecutive refreshes compose.

Done when the vectors, the C tests and the Python reference agree, and the module carries the same "experimental" warning enrollment does. Not done until somebody other than its author has reviewed it (D4). That does not block Phases 2–9, only release.

Phase 2: secp256k1-kmp bindings

On claude/frost-share-refresh from threshold.

  1. Bump zkp to the Phase 1 commit.
  2. Add JNI glue, iOS cinterop declarations, and Secp256k1 functions that return result types carrying ChilldkgFault-style blame.
  3. Rebuild the natives from scratch (native/build/). A stale libsecp256k1 shows up as a missing secp256k1_frost_refresh_* symbol at load time.
  4. Add JVM tests over the vectors.
  5. Run connectedAndroidTest if an emulator is to hand. The JNI marshalling is where a mistake hides.

Done when :tests:jvmTest passes with natives built from the Phase 1 commit.

Phase 3: bitcoin-kmp FrostRefresh

crypto/frost/FrostRefresh.kt, an object in the shape of ChillDKG.kt:

  • opaque RefreshParticipantState1/2 and RefreshCoordinatorState;
  • results that carry a fault rather than throw;
  • a RefreshResult(secretShare, publicShares, recovery).

Rules carried over from FrostReducedEnrollment:

  • Messages keyed by participant id, never by position. A missing or extra sender is Either.Left, a caller error, never a participant at fault.
  • Refresh and enrollment are separate objects with separate message types. Feeding one into the other is a type error.

Tests in FrostRefreshTestsCommon cover each Phase 1 property through the wrapper, plus the one that matters most for Giza:

  • refresh with k withheld, then a FrostReducedEnrollment repair at k, then sign with k in the signer set. This is the whole of re-enrollment, end to end, below the app.

Done when those pass and FrostEnrollmentTestsCommon and FrostReducedEnrollmentTestsCommon are unchanged.

Phase 4: carry it up the chain

Follow submodule-refresh.md exactly:

  • a worktree with its own submodule checkout;
  • a branch per level;
  • bitcoin-kmp → lightning-kmp → lightning-kmp-app → Giza;
  • pushes bottom up;
  • fast-forward the tracked branches only once Giza is green.

If giza-wallet-removal.md Phase 7b has landed by then, the chain is three levels and this is one bump.

Done when Giza's compileDebugKotlinAndroid, jvmTest and check pass on the bump with no app change.


Part B: a share that can change

Parts A and B are independent. B can start the day this plan is accepted.

Phase 5: preconditions, the share at rest

These are a refresh's preconditions, but each is worth doing on its own; the backup one is a standing leak.

  1. Keep aux.db out of platform backups.
    • Add dataExtractionRules (API 31+) and fullBackupContent (below 31) that exclude the database directory, or set allowBackup="false".
    • The identity is already restored from the recovery phrase, and the shares have their own recovery path (Phase 12), so nothing is lost but a copy of secrets.
  2. Secure delete. Open the database with PRAGMA secure_delete = ON so an overwritten share is zeroed on disk, not left in a free page.
    • A one-time VACUUM after the first wipe (Phase 8) clears what earlier writes left behind.
    • Not a substitute for encryption at rest, but without it a wipe is a promise the file does not keep.
  3. Name encryption at rest as the open item it is. It already has TODO(security) notes in RoomMlsGroupStateStore and DatabaseMarmotRepository. This plan does not do it, and the UI copy (Phase 11) must not claim it.

Done when an Android backup taken with adb backup / bmgr holds no aux.db, and a test writes a share, overwrites it, and finds no copy of the old bytes in the database file.

Phase 6: schema 37 → 38, and generations in signing

The schema. Two new tables, plus generation columns on the signing session and the key state.

table / column holds
KeyShareGeneration PK (dkgSessionId, generation) secretShare (nullable: null once wiped, or while stale), publicShares CSV in id order, state (PENDING, ACTIVE, RETIRING, WIPED), refreshSessionId (null for 0), recoveryData, activatedAt, wipedAt
KeyShareMember PK (dkgSessionId, generation, participantId) memberPublicKey, hostPublicKey, publicShare, standing (LIVE, STALE, RETIRED)
FrostSigningSession.generation nullable Int. Null reads as 0, so rows from before the migration mean what they meant
GroupKeyState.generation, .publicSharesHash nullable. Null is generation 0

The migration.

  • The tables come in through an AutoMigration. A manual MIGRATION_37_38 backfills generation 0 from every DkgSession with a secretShare: the share and table come from DkgSession, and the members come from the HOST_KEY rows sorted exactly as signerIds() sorts them.
  • DkgSession.secretShare stays for now and is nulled at the generation-0 wipe.

Reading through one door. FrostSigningManager.advance, completedKey and signerIds read the share, the public shares and the ids through one function: ShareGenerations.active(dkgSessionId).

This reverses a decision, so the doc has to say why. signerIds is derived on purpose ("so signing cannot disagree with the ceremony that made the key"). From generation 1 on, the roster is a certified fact: the refresh certificate and the group-signed 30326. Generation 0 stays derived. ShareGenerationBackfillJvmTest asserts the backfilled rows equal signerIds() and publicShareList() for every fixture in GroupFixtures. The day they disagree is the day the migration is wrong.

Generation on the wire.

  • A frost_generation tag on 30320, alongside frost_key. No tag means 0, so proposals from older builds still mean what they meant.
  • A receiver whose active generation differs declines out loud: a 30330 with a reason, as WalletRefusal does. It never drops the proposal silently, and never signs with a share of another generation.
  • SecretNonce.generate already takes the share, so binding the session to a generation also binds its nonce. Write the test anyway: a session opened under g whose device has moved to g+1 fails rather than producing a partial signature from the wrong share.

Done when jvmTest passes with no behaviour change: every existing signing test, unedited except fixtures, signs at generation 0. A new FrostSigningGenerationJvmTest covers the mismatch decline.


Part C: the refresh

Phase 7: ShareRefreshManager

A stateless object in the image of ChillDkgRitualManager:

  • persist each inbound message;
  • ask whether the ritual can move;
  • recompute every step from stored inputs (round1Random, auxRandom and the received messages), so an app killed mid-round resumes on the next message.

Kinds. The proposal is 30340–30345. 30338–30349 are unused, and RetiredKindsTest already asserts 30338 and 30349 are not retired. Check Bennu's kinds before fixing the numbers.

kind from carries
30340 proposer (coordinator) proposal: frost_key, frost_generation (base g), refresh_id, p per recipient, withheld per withheld id with stale or retired
30341 recipient round 1: commitments and ciphertexts
30342 coordinator aggregate
30343 recipient CertEq signature
30344 coordinator certificate
30345 any recipient failure: abort and blame, or abandon

They travel as Marmot inner events in the key's room (D7). The ciphertexts are encrypted to host keys, so a room-wide message is fine here, which it is not for repair (Phase 10).

Entities.

  • ShareRefreshSession: id, dkgSessionId, baseGeneration, coordinator, recipients, withheld and their standings, stage, round1Random, auxRandom, approvals, the certificate, the failure reason.
  • ShareRefreshMessage, keyed (sessionId, participantPublicKey, kind), which absorbs redelivery the way DkgParticipantMessage does.

Refusals at proposal and on arrival. Each is a value, with a reason the screen can show:

  • the key has no room, or this device is not live at the base generation;
  • |R| < t, or |R| is not more than half the non-retired ids (D3b);
  • a recipient's client has not advertised refresh support (D5);
  • the base generation is not this device's active one;
  • this device has already confirmed a refresh from this base generation (D3a). This rule is enforced with a write-once column on KeyShareGeneration, set in the same transaction that stores the PENDING row. It is as important as the nonce rules, and for the same reason: it is the one way the group splits.
  • an open ChillDKG or refresh for the same key;
  • on the proposer's device only, a rotation whose key state the group has not signed yet, a key-state proposal still open there, or a device behind the group (rotation-waits-for-key-state.md, ShareRefreshManager.rotationHold). Not on arrival: a recipient a few seconds behind on the signature would end a rotation that was fine.

Approval gates. One, with pendingApproval mirroring advance exactly:

step publishes why it is its own decision
DEAL round 1 joins the refresh and agrees to the withheld list. Withholding someone is a decision about them, so every recipient makes it, not only the proposer

The proposer makes it by proposing, from a dialog that names everyone the proposal leaves out (rotation-waits-for-key-state.md, Phase 4).

A recipient is asked only when the withheld list holds a decision: a rotation that leaves out only members already stale, and members the group's signature took out of a governed room's admins, is taken part in unasked, which is what a rotation after an admin change is (admin-change-rotation.md, Phase 5).

As first built there were two gates, and the proposer was asked at both. CONFIRM stood before CertEq, on the reasoning that it "stops a coordinator substituting a table the recipients never dealt". It never did: that is participantStep2's check, which runs before any prompt could appear and fails the refresh out loud, and the one confirmation per generation is the write-once ShareRefreshConfirmation. Both hold whoever is looking. rotation-waits-for-key-state.md first stopped asking the proposer; rotate-shares-single-approval.md then removed the gate for everyone. ShareRefreshApprovalStep.CONFIRM and confirmApprovedAt remain, unread, so rows written before still decode.

Transcript. System lines in the room, as the ceremony writes them, idempotent by reading the row before writing:

  • started (naming who is withheld, and whether as stale or retired);
  • each member's contribution;
  • complete;
  • abandoned.

Done when ShareRefreshRitualTest (commonTest, real primitive, in-memory multi-device in the manner of RobustRoomKeyCeremonyTest) passes for:

  • n 2..5, t 2..n, with 0, 1 and 2 withheld;
  • redelivery of every message;
  • a kill between "persist PENDING" and "send CertEq";
  • a faulty dealer blamed by id;
  • abandon;
  • ShareRefreshForkTest: two proposals from one base generation, with the majority rule and the write-once rule each shown to be necessary by a test that drops it and gets two certificates.

Phase 8: cutover, the signed table, and the wipe

What a device does with a certificate, and when the old share goes.

  1. Certificate verified → g+1 becomes ACTIVE, g becomes RETIRING.

    • New signing proposals use g+1.
    • Sessions already open under g may finish while g is still RETIRING.
  2. The group signs the new key state. Any recipient proposes a 30326 for the room. It is unchanged in content and d, and carries new tags:

    • frost_generation = g+1;
    • frost_pubshares = hash of the new public-share table;
    • frost_refresh = the refresh id;
    • frost_retired per retired id.

    It is signed under g+1, which makes it the first signature the new shares make: the proof D6 waits for. A recipient's device signs it without asking when it is exactly the state the rotation it completed implies (GroupKeyStateManager.vouchesForGeneration, rotate-shares-single-approval.md, Phase 5).

  3. GroupKeyStateManager changes, and the comment in GroupKeyStateEvent.kt (L84–87) gets answered.

    • The comment expects that rotation would break verifies(). It does not: the key is unchanged, so marmotGroupId(X, path) == chatRoomId still holds. What changes is that a state now names a generation.
    • GroupKeyStateDao.replace() keeps the highest generation, then the newest announcedAt, not the newest announcedAt alone. created_at is chosen by the author, and an older generation's state is still validly signed by the group.
    • stateFrom checks frost_pubshares against the local KeyShareGeneration table. A mismatch is a refusal with a reason, because it means this device and the group disagree about who holds what.
  4. On seeing that signed state: wipe g.

    • KeyShareGeneration(g).secretShare becomes null and the state becomes WIPED.
    • Every open session under g fails, with "this share was rotated".
    • At generation 0, also null DkgSession.secretShare, round1Random and round2AuxRandom. The last two rebuild the share on their own, and a wipe that leaves them wipes nothing.
    • Then the one-time VACUUM from Phase 5.
    • Check first that ChillDkgRitualManager.advance returns early for a COMPLETE session and never reaches for the nulled randomness. If it does not, that is the bug this step will find.

Done when ShareRefreshCutoverJvmTest covers:

  • a refresh followed by signing at g+1;
  • a signature attempted at g after the wipe, which fails out loud;
  • the wiped bytes, absent from the database file;
  • a late 30326 at generation g, which loses to g+1 whatever its created_at;
  • a device that missed the certificate, which comes back from the transcript in its own backlog replay.

GroupKeyStateTest and SignedGroupKeyStateTest must pass unedited for generation 0.


Part D: membership, recovery, UI, rollout

Phase 9: removing a share holder

MarmotOutboundDao.removeMember stays as it is (D8). After it succeeds for a member who is live in the room's key, the members screen offers a second action: "Rotate shares without them". That opens a refresh proposal withholding their id as retired.

The removal and the rotation are two acts, for three reasons:

  • the removal is one admin's commit;
  • the rotation needs every remaining holder;
  • a removal that silently started a refresh would leave the group in a ritual no one chose.

Refusals.

  • Withholding would leave fewer than t non-retired ids. The copy says the group would no longer be able to sign at all, and that the way out is a new ceremony.
  • The majority rule (D3b) fails. Remove fewer at a time: in a 2-of-5, one at a time always passes.

A retired id is never reused, and n does not shrink. FROST identifiers are positions below n, and frostSessionInit takes nParticipants, so a gap is fine. Renumbering would invalidate every public share.

Done when MemberRemovalRefreshJvmTest removes a member from a 2-of-3 room, rotates without them, and shows that:

  • the remaining two sign at g+1;
  • the removed member's share does not appear in any signer set;
  • their share combined with one remaining member's g+1 share produces no valid signature.

Phase 10: re-enrollment

The repair path, for the members a refresh left stale. It uses FrostReducedEnrollment only, never v1, as submodule-refresh.md decided.

10a. Same identity, missed the refresh. The member was offline or had no build that supported it.

  1. They (the target) propose a repair with a fresh sessionId.
  2. t or more live helpers each approve. Approval is a gate, because a helper's round 1.1 message spends its share's secrecy on the target's behalf.
  3. Round 1.1 shares go helper to larger-id helper, and round 1.2 messages go helper to target, every one over a pairwise channel (see the protocol).
  4. The target derives P_k' from the group-signed table, runs generateSecretShare with it as expectedPublicShare, and persists g as live.

Kinds 30346 (request), 30347 (round 1.1) and 30348 (round 1.2).

10b. New identity: lost device, compromised nsec.

  • The member's id k is re-bound to a new npub, and so a new host key, by a 30326 the group signs. The state gains a frost_member tag per id that has changed hands, and the KeyShareMember row follows it. Only then can a repair target k.
  • The order is forced. A repair to an npub the group has not bound to k is a repair to whoever asked.
  • Withholding the old identity first, by a refresh, is what makes the old device's share worthless. A repair alone would hand the new device the same point the old one has.

10c. A new member (newId = n) is enrollment proper. It belongs in submodule-refresh.md's Phase 6 document, not here. This plan leaves it one thing: an enrollment is a 30326 that grows n and the table, at the current generation. The schema above already has room for it.

Done when ReEnrollmentJvmTest runs 10a and 10b end to end, and shows that:

  • the repaired member signs;
  • a repair whose helpers present a table that disagrees with the signed one fails at round 2, not at signing;
  • a 10b repair to an unbound npub is refused before any helper sends anything.

Phase 11: UI

Under CLAUDE.md's rules:

  • strings in the catalogue, sentence case;
  • spacing and colour from the theme;
  • NavigateBackButton on the pushed screen;
  • four states through ScreenStateTransition;
  • outcomes through rememberNotifier.

What to build.

  • A "Shares" section on the key's screen. It shows:

    • the generation;
    • each id's member and standing;
    • when the generation became active;
    • an action to rotate.

    Standing gets a text label, not only an icon, so the icon gets Decorative.

  • The refresh screen. A progress ladder that names who it waits on, like the ceremony's, with its one approval (two as first built; see rotate-shares-single-approval.md).

    • The DEAL prompt lists who is withheld, and as what.
    • The CONFIRM prompt is the ceremony's CertEq prompt in different words.
  • The copy has to tell the truth from what it protects against.

    • Say "Shares held before today stop working once everyone's device has deleted them."
    • Never write "the removed member can no longer sign" without that clause.
    • Never write anything implying a compromised account is fixed by a rotation.
  • The repair screen, and a banner on the key's screen for a stale member: "You missed a share rotation. Ask the group to bring you back in."

Done when ./gradlew :composeApp:m3Audit and check pass at their budgets, and the floors have not moved down.

Phase 12: restore

Today nothing calls ChillDKG.participantRecover. DkgSession.recoveryData is written at the end of a ceremony and never read. So the line "restorable from that member's wallet backup" in shared-key-ceremony.md describes a path that is not built. Refresh makes this gap longer, since a restored device now needs generation 0 and every refresh after it. It does not make the gap wider.

This phase:

  • makes the refresh transcripts (round 1 messages and certificate) part of what a room's backlog replay keeps;
  • adds ShareGenerations.recover(dkgSessionId, hostSecretKey), which walks ChillDKG recovery and then each refresh to the active generation;
  • tests that it lands on the live share at every generation.

Wiring that into a restore flow belongs with whoever builds the restore flow. Until then, the honest copy is that a reinstalled device is repaired (10a), not restored.

Done when the recovery walk is tested to generation 3 against the shares computed live.

Phase 13: rollout

  • The flag (D4). BuildConfig-style, off in release. The key screen shows no rotate action, and inbound 30340s are declined out loud with "this build cannot rotate shares".

  • Capability. The support D5 checks for is a value in the client's key package or profile tags, so a proposer can refuse before anyone deals.

  • Compatibility.

    • An old build sees a 30340 as an unknown kind and does nothing. That is acceptable only because D5 has already refused to make it a recipient.
    • An old build that sees a 30320 with frost_generation ≥ 1 ignores the tag and signs with generation 0. The partial signature then fails verification, and the coordinator blames it. That is noisy, not dangerous. D5 keeps it from happening in a group that has refreshed.
  • Checks this tree cannot run.

    • Android install over the current build, then a refresh across three devices.
    • A desktop member in the same group.
    • iOS on a Mac.
    • The adb backup check from Phase 5.

    Say so in the PR until done, as submodule-refresh.md does.

What this does not do

  • Change the threshold, or add members. A reshare with a different t' deals each member's Lagrange-weighted share as a fresh VSS secret. It is a different protocol, with its own review. Adding a member is enrollment (10c).
  • Encrypt aux.db. Phase 5 shrinks the exposure; it does not close it.
  • Recover from t compromised shares. A refresh is for before that happens. After it, only a new ceremony helps, and it gives a new key, a new room and new certificates.
  • Prove deletion. Every member's wipe is on their own device, on trust.
  • Rotate subgroup keys from the parent. A subgroup refreshes its own key in its own room. The birth certificate names the child's key, which a refresh does not change, so it stays valid.

Appendix: considered and rejected

idea why not
Re-enroll every member at fresh ids, then retire the old ids Same polynomial. Every old share is still a point on it (the headline)
Run ChillDKG again A new key: a new room id (marmotGroupId), every GroupSignedEvent author changes, and subgroup birth certificates and the chronicle no longer verify. That is the right tool after t shares leak, and the wrong one for a routine rotation
Refresh in Kotlin inside Giza Protocol code in the app, with no vectors and no reviewer. If not zkp, then bitcoin-kmp (D1), never composeApp
Let the refresh finish without everyone A recipient who cannot confirm could hold an inconsistent delta and nobody would know. Repair covers the absent member cleanly (D2)
Fold the refresh into removeMember A removal is one admin's commit, and a refresh needs every holder. Coupling them makes a removal hang on the slowest phone (D8)
Send repair messages as MLS application messages Every member of the room can read them. The v2 messages are raw additive shares

Summary

phase where what done when
1 secp256k1-zkp frost_refresh: spec, Python vectors, C, tests vectors agree; review requested
2 secp256k1-kmp bindings, natives :tests:jvmTest
3 bitcoin-kmp FrostRefresh wrapper; refresh → repair → sign test wrapper tests; enrollment tests unchanged
4 chain → Giza bumps, per submodule-refresh.md Giza check with no app change
5 Giza aux.db out of backups; secure_delete no aux.db in a backup; overwritten bytes gone
6 Giza schema 38: generations and roster; frost_generation on signing existing tests unedited; mismatch declines
7 Giza ShareRefreshManager, kinds 30340–30345, gates, fork rules ritual and fork tests
8 Giza cutover, signed 30326 with generation, wipe cutover test; old share gone from file
9 Giza rotate after removal removed member's share signs nothing
10 Giza repair: same identity, new identity re-enrollment tests
11 Giza Shares section, refresh and repair screens m3Audit, check
12 Giza recovery walk across generations recovery equals live to g = 3
13 Giza flag, capability, device checks flag off in release; device checks named in PR