feat(wallet): a guarded wallet knows the group that directly guards it (Phase 1)

GuardedWallet gains three derived properties: directGuardianChatRoomId,
the nearest guardian, which for a member's wallet is the group that
signed its certificate; isGuardedHere; and branchChatRoomId, the
holding group's own child the wallet sits under. All are read off the
guardians and the line of descent a verified certificate already gives.

LineageExample is the note's R/P/M/N tree with Alice's two wallets in
it, for this phase's tests and the later ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-10-24 11:49:11 +02:00
1 parent eaaa352d57
commit 449d80f8bf
3 files changed
+160

No files matched your search

@@ -103,6 +103,24 @@ object GuardianManager {
*/
val delay: Long get() = account.guardians[position].delay
/**
* The group that directly guards it: the nearest guardian, which for a
* member's wallet is the group that signed its certificate --
* `MemberWalletRequestEvent.verified` refuses a request whose nearest
* guardian is not the group it asks. `docs/member-wallet-guarding-group.md`, D1.
*/
val directGuardianChatRoomId: String get() = account.guardians.first().chatRoomId
/** True when the ancestor holding it is the group that directly guards it. */
val isGuardedHere: Boolean get() = position == 0
/**
* The ancestor's own child the wallet sits under -- the branch of its tree
* -- or null when the ancestor guards it directly. The ancestor signed
* that child's birth certificate, so it can always name it.
*/
val branchChatRoomId: String? get() = lineage.takeIf { position > 0 }?.first()
/** The ancestor as the spender of a spend from this wallet, signing as [thresholdPublicKey] -- null to only build one. */
fun spender(thresholdPublicKey: HexKey? = null): GroupSpend.Spender.Guardian =
GroupSpend.Spender.Guardian(position = position, lineage = lineage, thresholdPublicKey = thresholdPublicKey, name = displayName)
@@ -0,0 +1,59 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.managers.LineageExample.heldBy
import com.machankura.bennu.compose.managers.LineageExample.m
import com.machankura.bennu.compose.managers.LineageExample.n
import com.machankura.bennu.compose.managers.LineageExample.p
import com.machankura.bennu.compose.managers.LineageExample.r
import com.machankura.bennu.compose.managers.LineageExample.rent
import com.machankura.bennu.compose.managers.LineageExample.rentGuardians
import com.machankura.bennu.compose.managers.LineageExample.savings
import com.machankura.bennu.compose.managers.LineageExample.savingsGuardians
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertNull
import kotlin.test.assertTrue
/**
* Which group directly guards a member's wallet, and which branch of an
* ancestor's tree it sits under -- read off the guardians and the line of
* descent a verified certificate already gives. `docs/member-wallet-guarding-group.md`, Phase 1.
*/
class GuardedWalletLineageTest {
@Test
fun `the root sees Savings guarded by M, two generations down through P`() {
val wallet = heldBy(r, savings, savingsGuardians)
assertEquals(m, wallet.directGuardianChatRoomId)
assertEquals(p, wallet.branchChatRoomId)
assertEquals(2, wallet.position)
assertFalse(wallet.isGuardedHere)
}
@Test
fun `the root sees Rent guarded by its own child N, which is also the branch`() {
val wallet = heldBy(r, rent, rentGuardians)
assertEquals(n, wallet.directGuardianChatRoomId)
assertEquals(n, wallet.branchChatRoomId)
assertEquals(1, wallet.position)
}
@Test
fun `the middle group sees the same guardian, with M as its branch`() {
val wallet = heldBy(p, savings, savingsGuardians)
assertEquals(m, wallet.directGuardianChatRoomId)
assertEquals(m, wallet.branchChatRoomId)
}
@Test
fun `the group that signed the certificate guards it here, and has no branch`() {
val wallet = heldBy(m, savings, savingsGuardians)
assertEquals(m, wallet.directGuardianChatRoomId)
assertTrue(wallet.isGuardedHere)
assertNull(wallet.branchChatRoomId)
}
}
@@ -0,0 +1,83 @@
package com.machankura.bennu.compose.managers
import com.machankura.bennu.compose.nostr.wallet.MemberWalletCertificateEvent
import com.vitorpamplona.quartz.nip01Core.core.Event
import fr.acinq.bitcoin.ByteVector32
import fr.acinq.bitcoin.Chain
import fr.acinq.bitcoin.PrivateKey
import fr.acinq.secp256k1.Hex
/**
* The tree `docs/member-wallet-guarding-group.md` uses throughout, with Alice's
* two wallets in it:
*
* ```
* R root
* ├── P R's guarded subgroup
* │ └── M P's guarded subgroup — guards Alice's "Savings"
* └── N R's guarded subgroup — guards Alice's "Rent"
* ```
*
* The guardians are real grants, so `position` and `lineage` are what a
* verified certificate would give; the events are stand-ins, since nothing here
* checks a signature.
*/
object LineageExample {
private fun key(seed: Int): String =
PrivateKey(ByteVector32(Hex.decode(seed.toString(16).padStart(64, '0')))).publicKey().toString()
val rKey = key(0x600d)
val pKey = key(0xbeef)
val mKey = key(0xcafe)
val nKey = key(0xf00d)
val r = SharedKeyDerivation.marmotGroupId(rKey)
val p = SharedKeyDerivation.marmotGroupId(pKey)
val m = SharedKeyDerivation.marmotGroupId(mKey)
val n = SharedKeyDerivation.marmotGroupId(nKey)
val alice = key(0xa11ce)
val savings = "5".repeat(64)
val rent = "7".repeat(64)
private val pGrant = GuardianDerivation.grant(rKey, r, emptyList(), p)
private val mGrant = GuardianDerivation.grant(pKey, p, pGrant, m)
private val nGrant = GuardianDerivation.grant(rKey, r, emptyList(), n)
/** Savings' guardians, `[M, P, R]`. */
val savingsGuardians = GuardianDerivation.grant(mKey, m, mGrant, savings)
/** Rent's guardians, `[N, R]`. */
val rentGuardians = GuardianDerivation.grant(nKey, n, nGrant, rent)
/**
* Alice's wallet [walletId] under [guardians], as [ancestor] holds it.
* [label] and [ownerName] are what `GuardianManager.named` would fill.
*/
fun heldBy(
ancestor: String,
walletId: String,
guardians: List<GuardianDerivation.Guardian>,
label: String? = null,
ownerPublicKey: String = alice,
ownerName: String? = "alice",
walletKey: Int = 0xdecaf,
): GuardianManager.GuardedWallet {
val account = GroupWalletDerivation.account(key(walletKey), Chain.Regtest, guardians = guardians)
val certificate = Event(walletId.take(63) + "c", guardians.first().chatRoomId, 1_700_000_000, MemberWalletCertificateEvent.KIND, emptyArray(), walletId, "")
return GuardianManager.GuardedWallet(
ancestorChatRoomId = ancestor,
descendantChatRoomId = walletId,
statement = certificate,
account = account,
certificate = certificate,
lineage = requireNotNull(GuardianDerivation.lineage(guardians, walletId, ancestor)) { "$ancestor does not guard $walletId" },
subject = GuardianManager.GuardedSubject.Member(
id = walletId,
ownerPublicKey = ownerPublicKey,
label = label,
ownerName = ownerName,
),
)
}
}