feat: the Shares section holds Rotate shares and says why (Phase 2)

SharesSummary.canRotate becomes Rotation: Unavailable, Available, or
Held with a reason -- a rotation in progress, the group's signature on
the new shares still owed, or this device behind. The button stays,
disabled, with the reason beneath it.

While the key state is owed and nobody here is asking for it, the
section offers to ask the group to sign it
(ShareRefreshManager.proposeOwedKeyState), so a coordinator who is gone
does not hold every later rotation; while somebody is asking, it links
to the proposal. The offer to rotate without a removed member is made
only when a rotation could start now, and says so otherwise.

The section's actions run one at a time, through isActionPending.
ShareRefreshRitualJvmTest 24/24, m3Audit, compileDebugKotlinAndroid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-20 00:44:59 +02:00
1 parent 159ae402db
commit d358a0db38
8 files changed
+215 -13

No files matched your search

@@ -127,6 +127,13 @@
<string name="pending_rotation_confirm">Store your new share</string>
<string name="pending_repair_help">Help bring a member back</string>
<string name="shares_action_sent">Sent to the group</string>
<string name="rotation_held_running">A rotation is in progress</string>
<string name="rotation_held_awaiting_signatures">Waiting for the group to sign the new shares before another rotation</string>
<string name="rotation_held_behind">This device is catching up with the group's latest rotation</string>
<string name="rotation_held_after_removal">Removal sent. They still hold a share; rotate without them once the group has signed the current shares.</string>
<string name="ask_the_group_to_sign_the_new_shares">Ask the group to sign the new shares</string>
<string name="key_state_requested">Asked the group to sign the new shares</string>
<string name="see_the_proposal">See the proposal</string>
<string name="share_rotation_requested">Share rotation proposed; every remaining member is asked to take part</string>
<string name="library">Library</string>
<string name="lightning_invoice">Lightning invoice</string>
@@ -42,6 +42,7 @@ import mobi.giza.compose.database.model.types.MarmotReindexReport
import mobi.giza.compose.identity.Identity
import mobi.giza.compose.identity.toKeyPair
import mobi.giza.compose.managers.ShareRefreshManager
import mobi.giza.compose.managers.RotationHold
import mobi.giza.compose.ui.view.state.SharesSummary
import mobi.giza.compose.database.model.types.ShareStanding
import mobi.giza.compose.database.model.types.ShareRepairStage
@@ -676,7 +677,6 @@ class DatabaseChatRepository(
}
} + repairs.filter { ShareRepairManager.isAwaitingApproval(database, it) }
.map { SharesSummary.PendingApproval(it.id, SharesSummary.PendingApproval.Kind.REPAIR_HELP) }
val running = refreshes.any { it.stage != ShareRefreshStage.COMPLETE && it.stage != ShareRefreshStage.FAILED }
val mine = shares.roster.firstOrNull { it.memberPublicKey == me }
val repairing = repairs.any { it.targetPublicKey == me && it.stage != ShareRepairStage.FAILED && it.stage != ShareRepairStage.COMPLETE }
SharesSummary(
@@ -685,7 +685,19 @@ class DatabaseChatRepository(
SharesSummary.Member(entry.memberPublicKey, names[entry.memberPublicKey] ?: entry.memberPublicKey.take(8), entry.standing, entry.memberPublicKey == me)
},
pending = if (ExperimentalFeatures.shareRefresh) pending else emptyList(),
canRotate = ExperimentalFeatures.shareRefresh && shares.secretShare != null && !running,
rotation = if (!ExperimentalFeatures.shareRefresh || shares.secretShare == null) {
SharesSummary.Rotation.Unavailable
} else {
when (val hold = ShareRefreshManager.rotationHold(database, localChatRoom, key)) {
null -> SharesSummary.Rotation.Available
is RotationHold.Running -> SharesSummary.Rotation.Held(SharesSummary.Rotation.Reason.ROTATION_RUNNING)
is RotationHold.AwaitingKeyState -> SharesSummary.Rotation.Held(
SharesSummary.Rotation.Reason.AWAITING_SIGNATURES,
canAskForSignature = hold.signingSessionId == null,
)
is RotationHold.Behind -> SharesSummary.Rotation.Held(SharesSummary.Rotation.Reason.BEHIND)
}
},
canAskToBeRepaired = ExperimentalFeatures.shareRefresh && mine?.standing == ShareStanding.STALE && !repairing,
)
}.getOrNull()
@@ -716,6 +728,12 @@ class DatabaseChatRepository(
}.exceptionOrNull())
}
override suspend fun proposeKeyState(localChatRoom: LocalChatRoom): String? {
val (me, _) = privateKeyOrNull() ?: return "This identity cannot sign"
val key = shareKeyOf(localChatRoom) ?: return "This group has no shared key"
return failureOf(runCatching { ShareRefreshManager.proposeOwedKeyState(database, localChatRoom, me, key) }.exceptionOrNull())
}
override suspend fun abandonRotation(localChatRoom: LocalChatRoom, sessionId: String): String? =
failureOf(runCatching { ShareRefreshManager.abandon(database, localChatRoom, sessionId) }.exceptionOrNull())
@@ -235,6 +235,26 @@ object ShareRefreshManager {
return null
}
/**
* Asks the group to sign the key state it owes for the generation the last
* rotation produced, when nobody here is asking -- the coordinator's proposal
* failed, or its device is gone. Anyone may (docs/frost-share-refresh.md,
* Phase 8); without it a lost coordinator holds every later rotation for good
* (docs/rotation-waits-for-key-state.md, R4).
*/
suspend fun proposeOwedKeyState(database: GizaDatabase, localChatRoom: LocalChatRoom, userPublicKey: HexKey, key: DkgSession): FrostSigningSession {
val hold = rotationHold(database, localChatRoom, key)
check(hold is RotationHold.AwaitingKeyState && hold.signingSessionId == null) {
"The group is not waiting on anyone to ask for its key state"
}
// The refresh that produced the generation, named on the state as the
// coordinator would have named it.
val refreshId = database.shareRefreshDao().getSessionsForKey(key.id)
.firstOrNull { it.stage == ShareRefreshStage.COMPLETE && it.baseGeneration + 1 == hold.generation }
?.id
return GroupKeyStateManager.proposeGeneration(database, localChatRoom, userPublicKey, key, refreshId)
}
/**
* A key-state signing session of [key] still open on this device -- a
* rotation's, a rebind's, or the ceremony's first -- unless this device has
@@ -290,6 +290,13 @@ interface ChatRepository {
/** Answers what [approval] asks. Null on success, or why not. */
suspend fun approveShares(localChatRoom: LocalChatRoom, approval: SharesSummary.PendingApproval): String?
/**
* Asks the group to sign the key state at the generation the last rotation
* produced, when nobody here is asking (docs/rotation-waits-for-key-state.md, R4).
* Null when the request went out, or why it did not.
*/
suspend fun proposeKeyState(localChatRoom: LocalChatRoom): String?
/** Ends the rotation [sessionId] for everyone. Null on success, or why not. */
suspend fun abandonRotation(localChatRoom: LocalChatRoom, sessionId: String): String?
@@ -496,6 +503,8 @@ interface ChatRepository {
override suspend fun approveShares(localChatRoom: LocalChatRoom, approval: SharesSummary.PendingApproval): String? = null
override suspend fun proposeKeyState(localChatRoom: LocalChatRoom): String? = null
override suspend fun abandonRotation(localChatRoom: LocalChatRoom, sessionId: String): String? = null
override suspend fun askToBeRepaired(localChatRoom: LocalChatRoom): String? = null
@@ -122,6 +122,13 @@ import androidx.compose.foundation.layout.Row
import mobi.giza.compose.resources.share_rotation_requested
import mobi.giza.compose.resources.not_now
import mobi.giza.compose.resources.rotate_shares
import mobi.giza.compose.resources.rotation_held_running
import mobi.giza.compose.resources.rotation_held_awaiting_signatures
import mobi.giza.compose.resources.rotation_held_behind
import mobi.giza.compose.resources.rotation_held_after_removal
import mobi.giza.compose.resources.ask_the_group_to_sign_the_new_shares
import mobi.giza.compose.resources.key_state_requested
import mobi.giza.compose.resources.see_the_proposal
import mobi.giza.compose.resources.rotate_shares_without_body
import mobi.giza.compose.resources.rotate_shares_without_title
import androidx.compose.material3.AlertDialog
@@ -185,6 +192,8 @@ fun ChatRoomDetailScreen(
val removalRequested = stringResource(Res.string.member_removal_requested)
val rotationRequested = stringResource(Res.string.share_rotation_requested)
val sharesActionSent = stringResource(Res.string.shares_action_sent)
val keyStateRequested = stringResource(Res.string.key_state_requested)
val rotationHeldAfterRemoval = stringResource(Res.string.rotation_held_after_removal)
// Offered after removing a member who still holds a share of the room's key:
// the removal took them out of the room, not out of the key
@@ -413,6 +422,7 @@ fun ChatRoomDetailScreen(
Row(horizontalArrangement = Arrangement.spacedBy(MaterialTheme.spacing.relatedGap)) {
if (approval.kind != SharesSummary.PendingApproval.Kind.REPAIR_HELP) {
TextButton(
enabled = !chatRoomDetailViewModel.isActionPending.value,
onClick = {
chatRoomDetailViewModel.abandonRotation(chatRoomDetailUIState.localChatRoom, approval.sessionId) { failure ->
notify(failure ?: sharesActionSent)
@@ -423,6 +433,7 @@ fun ChatRoomDetailScreen(
}
}
FilledTonalButton(
enabled = !chatRoomDetailViewModel.isActionPending.value,
onClick = {
chatRoomDetailViewModel.approveShares(chatRoomDetailUIState.localChatRoom, approval) { failure ->
notify(failure ?: sharesActionSent)
@@ -435,7 +446,9 @@ fun ChatRoomDetailScreen(
}
)
}
if (shares.canRotate || shares.canAskToBeRepaired) {
val rotation = shares.rotation
val actionPending = chatRoomDetailViewModel.isActionPending.value
if (rotation != SharesSummary.Rotation.Unavailable || shares.canAskToBeRepaired) {
item {
Column(verticalArrangement = Arrangement.spacedBy(MaterialTheme.spacing.relatedGap)) {
Text(
@@ -443,8 +456,12 @@ fun ChatRoomDetailScreen(
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant
)
if (shares.canRotate) {
if (rotation != SharesSummary.Rotation.Unavailable) {
// Disabled rather than hidden while the last rotation is
// unfinished, with the reason beneath it
// (docs/rotation-waits-for-key-state.md, Phase 2).
FilledTonalButton(
enabled = rotation == SharesSummary.Rotation.Available && !actionPending,
onClick = {
chatRoomDetailViewModel.rotateShares(chatRoomDetailUIState.localChatRoom) { failure ->
notify(failure ?: rotationRequested)
@@ -454,8 +471,50 @@ fun ChatRoomDetailScreen(
Text(stringResource(Res.string.rotate_shares))
}
}
if (rotation is SharesSummary.Rotation.Held) {
Text(
text = stringResource(
when (rotation.reason) {
SharesSummary.Rotation.Reason.ROTATION_RUNNING -> Res.string.rotation_held_running
SharesSummary.Rotation.Reason.AWAITING_SIGNATURES -> Res.string.rotation_held_awaiting_signatures
SharesSummary.Rotation.Reason.BEHIND -> Res.string.rotation_held_behind
}
),
style = MaterialTheme.typography.bodyMedium,
color = MaterialTheme.colorScheme.onSurfaceVariant
)
if (rotation.canAskForSignature) {
// Nobody is asking for the key state the group owes:
// the coordinator's proposal failed, or its device is
// gone. Anyone may ask again (frost-share-refresh.md, Phase 8).
TextButton(
enabled = !actionPending,
onClick = {
chatRoomDetailViewModel.proposeKeyState(chatRoomDetailUIState.localChatRoom) { failure ->
notify(failure ?: keyStateRequested)
}
}
) {
Text(stringResource(Res.string.ask_the_group_to_sign_the_new_shares))
}
} else if (rotation.reason == SharesSummary.Rotation.Reason.AWAITING_SIGNATURES) {
TextButton(
onClick = {
onNavigateToRoute.invoke(
ProposalListRoute(
activeUserPublicKey = activeUserPublicKey,
chatRoomId = chatRoomId
)
)
}
) {
Text(stringResource(Res.string.see_the_proposal))
}
}
}
if (shares.canAskToBeRepaired) {
TextButton(
enabled = !actionPending,
onClick = {
chatRoomDetailViewModel.askToBeRepaired(chatRoomDetailUIState.localChatRoom) { failure ->
notify(failure ?: sharesActionSent)
@@ -706,8 +765,8 @@ fun ChatRoomDetailScreen(
chatRoomDetailViewModel.removeMember(
localChatRoom = chatRoomDetailUIState.localChatRoom,
memberPublicKey = memberPublicKey,
) { failure ->
notify(failure ?: removalRequested)
) { failure, rotationHeld ->
notify(failure ?: if (rotationHeld) rotationHeldAfterRemoval else removalRequested)
}
}
) {
@@ -118,20 +118,24 @@ class ChatRoomDetailViewModel(
* applied when a relay accepts it, so the member's row stays until then; the
* line saying they were removed is there at once.
*/
fun removeMember(localChatRoom: LocalChatRoom, memberPublicKey: HexKey, onDone: (String?) -> Unit = {}) {
fun removeMember(localChatRoom: LocalChatRoom, memberPublicKey: HexKey, onDone: (failure: String?, rotationHeld: Boolean) -> Unit = { _, _ -> }) {
viewModelScope.launch(Dispatchers.IO) {
// Asked before the removal, while they are still in the room's roster.
val heldShare = chatRepository.holdsShare(localChatRoom, memberPublicKey)
val failure = runCatching { chatRepository.removeMember(localChatRoom, memberPublicKey) }
.exceptionOrNull()
// Offered only when a rotation could start now; while the last one is
// unfinished the offer would only be refused
// (docs/rotation-waits-for-key-state.md, Phase 2).
val rotation = if (failure == null && heldShare) chatRepository.sharesSummary(localChatRoom)?.rotation else null
initiateChatRoomDetail()
viewModelScope.launch(Dispatchers.Main) {
onDone(failure?.message)
onDone(failure?.message, rotation is SharesSummary.Rotation.Held)
// The removal takes them out of the room, not out of the key: they
// can still help sign until the shares are rotated without them.
// A second act, offered rather than folded in -- it needs every
// remaining holder (docs/frost-share-refresh.md, Phase 9).
if (failure == null && heldShare) rotationOffer = RotationOffer(localChatRoom, memberPublicKey)
if (rotation == SharesSummary.Rotation.Available) rotationOffer = RotationOffer(localChatRoom, memberPublicKey)
}
}
}
@@ -142,9 +146,17 @@ class ChatRoomDetailViewModel(
* goes on with in the background, so done means sent, not finished.
*/
private fun sharesAction(onDone: (String?) -> Unit, action: suspend () -> String?) {
// One at a time: the section's buttons read this, so a second tap while the
// first is on its way does nothing rather than reporting twice.
if (isActionPending.value) return
isActionPending.value = true
viewModelScope.launch(Dispatchers.IO) {
val failure = action()
initiateChatRoomDetail()
val failure = try {
action()
} finally {
initiateChatRoomDetail()
viewModelScope.launch(Dispatchers.Main) { isActionPending.value = false }
}
viewModelScope.launch(Dispatchers.Main) { onDone(failure) }
}
}
@@ -155,6 +167,9 @@ class ChatRoomDetailViewModel(
fun approveShares(localChatRoom: LocalChatRoom, approval: SharesSummary.PendingApproval, onDone: (String?) -> Unit) =
sharesAction(onDone) { chatRepository.approveShares(localChatRoom, approval) }
fun proposeKeyState(localChatRoom: LocalChatRoom, onDone: (String?) -> Unit) =
sharesAction(onDone) { chatRepository.proposeKeyState(localChatRoom) }
fun abandonRotation(localChatRoom: LocalChatRoom, sessionId: String, onDone: (String?) -> Unit) =
sharesAction(onDone) { chatRepository.abandonRotation(localChatRoom, sessionId) }
@@ -12,13 +12,34 @@ data class SharesSummary(
val generation: Int,
val members: List<Member>,
val pending: List<PendingApproval>,
/** This device holds a live share and no rotation is running: it may propose one. */
val canRotate: Boolean,
/** Whether this device may propose a rotation, and if not, what it waits on. */
val rotation: Rotation,
/** This device's own id is stale and nothing is bringing it back yet. */
val canAskToBeRepaired: Boolean,
) {
data class Member(val publicKey: HexKey, val name: String, val standing: ShareStanding, val isSelf: Boolean)
/**
* The rotate action, as the section shows it (docs/rotation-waits-for-key-state.md).
* [ShareRefreshManager.rotationHold][mobi.giza.compose.managers.ShareRefreshManager.rotationHold]
* decides it, the same function proposing asks, so the button and the protocol agree.
*/
sealed interface Rotation {
/** No live share here, or a build without the feature: no button. */
data object Unavailable : Rotation
data object Available : Rotation
/**
* The button, disabled, and why. [canAskForSignature]: the group owes the
* key state at this generation and nobody here is asking for it, so this
* device can.
*/
data class Held(val reason: Reason, val canAskForSignature: Boolean = false) : Rotation
enum class Reason { ROTATION_RUNNING, AWAITING_SIGNATURES, BEHIND }
}
/** Something this device's owner is being asked, and the session it is for. */
data class PendingApproval(val sessionId: String, val kind: Kind) {
enum class Kind { REFRESH_DEAL, REFRESH_CONFIRM, REPAIR_HELP }
@@ -19,6 +19,8 @@ import kotlin.test.assertNotEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Job
import kotlinx.coroutines.runBlocking
import mobi.giza.compose.database.GizaDatabase
import mobi.giza.compose.database.builder.getRoomDatabase
@@ -32,6 +34,7 @@ import mobi.giza.compose.database.model.NostrEvent
import mobi.giza.compose.database.model.Profile
import mobi.giza.compose.database.model.ShareRefreshConfirmation
import mobi.giza.compose.database.model.intermdiate.LocalChatRoom
import mobi.giza.compose.database.repository.DatabaseChatRepository
import mobi.giza.compose.database.model.types.DkgRitualStage
import mobi.giza.compose.database.model.types.FrostSigningStage
import mobi.giza.compose.database.model.types.ShareGenerationState
@@ -41,6 +44,7 @@ import mobi.giza.compose.extensions.toHex
import mobi.giza.compose.nostr.dkg.DkgRitualEvents
import mobi.giza.compose.nostr.frost.FrostSigningEvents
import mobi.giza.compose.nostr.frost.ShareRefreshEvents
import mobi.giza.compose.ui.view.state.SharesSummary
/**
* A share refresh between devices (docs/frost-share-refresh.md, Phase 7).
@@ -584,6 +588,55 @@ class ShareRefreshRitualJvmTest {
assertFailsWith<IllegalStateException> { propose(late) }
}
/** The rotate action as the room's Shares section reads it. */
private suspend fun rotation(device: Device): SharesSummary.Rotation? =
DatabaseChatRepository(device.db, CoroutineScope(Job())).sharesSummary(device.room)?.rotation
@Test
fun `the Shares section holds the button while a rotation is unfinished, and says why`() = runBlocking<Unit> {
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = true
val group = Group(3, 2)
val all = devicesFor(group)
val (alice, bob) = all
assertEquals(SharesSummary.Rotation.Available, rotation(bob))
val refresh = propose(alice)
pump(all)
assertEquals(SharesSummary.Rotation.Held(SharesSummary.Rotation.Reason.ROTATION_RUNNING), rotation(bob))
approveAll(all, refresh.id)
val awaiting = SharesSummary.Rotation.Held(SharesSummary.Rotation.Reason.AWAITING_SIGNATURES, canAskForSignature = false)
assertEquals(awaiting, rotation(bob), "the coordinator is already asking")
// The coordinator's proposal fails: nobody is asking, so Bob may.
all.forEach { device ->
device.db.frostSigningSessionDao().getSessionsForChatRoom(group.roomId).forEach {
device.db.frostSigningSessionDao().upsert(it.copy(stage = FrostSigningStage.FAILED))
}
}
assertEquals(awaiting.copy(canAskForSignature = true), rotation(bob))
val asked = ShareRefreshManager.proposeOwedKeyState(bob.db, bob.room, bob.publicKey, bob.key())
pump(all)
assertEquals(awaiting, rotation(bob))
assertFailsWith<IllegalStateException>("one ask at a time") {
ShareRefreshManager.proposeOwedKeyState(alice.db, alice.room, alice.publicKey, alice.key())
}
approveSigning(all)
assertEquals(FrostSigningStage.COMPLETE, bob.db.frostSigningSessionDao().getSessionById(asked.id)?.stage)
all.forEach { assertEquals(SharesSummary.Rotation.Available, rotation(it), "device ${it.index}") }
val stated = Event.fromJson(bob.db.frostSigningSessionDao().getItems(asked.id).single().unsignedEventJson)
assertTrue(stated.tags.any { it.contains(refresh.id) }, "the refresh is named as the coordinator would have named it")
}
@Test
fun `a member left out of a rotation is offered no rotate button`() = runBlocking<Unit> {
mobi.giza.compose.ExperimentalFeatures.shareRefreshOverride = true
val (_, all) = rotatedWithout(2)
assertEquals(SharesSummary.Rotation.Unavailable, rotation(all[2]))
assertEquals(SharesSummary.Rotation.Available, rotation(all[0]))
}
// ---- Phase 10: re-enrollment -----------------------------------------------------------------------------------
/** Every helper approves every repair waiting on them. */