feat(subgroup): a birth certificate can carry its child's wallet policy (Phase 1)

SubgroupWalletPolicy and WalletPolicyTag, ["wallet", "guarded"|"unguarded"],
and SubgroupBirthCertificateEvent.parseWalletPolicy. A certificate with no
tag reads Undecided; one whose tag does not read, or contradicts the
guardian keys beside it, reads null rather than undecided. certifies is
unchanged. Nothing writes the tag yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-10-23 21:50:57 +02:00
1 parent fed7e67c3d
commit f19001cd61
4 files changed
+210 -2

No files matched your search

@@ -12,6 +12,7 @@ import com.machankura.bennu.compose.nostr.frost.tags.FrostDerivationPathTag
import com.machankura.bennu.compose.nostr.subgroup.tags.GuardianTag
import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupKeyTag
import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupParentTag
import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag
/**
* A group saying, with a quorum, that another group is its child.
@@ -65,6 +66,15 @@ import com.machankura.bennu.compose.nostr.subgroup.tags.SubgroupParentTag
* the key that check needs and nobody else needs it: the parent's quorum can
* already spend through its own leaf whatever the others would let it.
*
* ### The wallet policy
*
* A certificate may carry a [WalletPolicyTag]: the parent deciding whether the
* child's wallet is guarded or unguarded, rather than leaving it to the child --
* `docs/subgroup-wallet-policy.md`. A guarded certificate carries the guardian
* keys and an unguarded one carries none, and [parseWalletPolicy] refuses one
* whose policy and keys disagree. Like the keys, the policy is not among the
* checks in [certifies]: it is read where it is used.
*
* ### What [certifies] deliberately does not check
*
* The name and the `p` tags are the **founding** roster. A certificate is signed
@@ -111,7 +121,8 @@ object SubgroupBirthCertificateEvent {
adminPublicKeys: List<HexKey>,
name: String,
path: List<Long> = SharedKeyDerivation.MARMOT_ADMIN_GROUP_PATH,
guardians: List<GuardianDerivation.Guardian> = emptyList()
guardians: List<GuardianDerivation.Guardian> = emptyList(),
walletPolicy: SubgroupWalletPolicy? = null
): Array<Array<String>> = arrayOf(
DTag.assemble(subgroupChatRoomId),
SubgroupParentTag.assemble(parentChatRoomId),
@@ -119,7 +130,35 @@ object SubgroupBirthCertificateEvent {
FrostDerivationPathTag.assemble(path),
arrayOf(NAME_TAG_NAME, name)
) + adminPublicKeys.distinct().map { PTag.assemble(it, null) } +
guardians.map(GuardianTag::assemble)
guardians.map(GuardianTag::assemble) +
listOfNotNull(walletPolicy?.let(WalletPolicyTag::assemble))
/**
* What the certificate says about the child's wallet: [WalletPolicyReading.Undecided]
* when it carries no policy, as every certificate from before policies does,
* and null when the reading cannot be used --
*
* - a `wallet` tag that does not read, or two of them;
* - guardian keys that do not read;
* - a policy that contradicts the keys beside it: `guarded` with none, or
* `unguarded` with some.
*
* A certificate that says one thing in its policy and another in its keys is
* not a thing to guess the meaning of, and a policy present and unreadable
* must never read as absent -- that would hand the child the choice the
* parent took away.
*/
fun parseWalletPolicy(tags: Array<Array<String>>): WalletPolicyReading? {
val guardians = parseGuardians(tags) ?: return null
return when (val tag = WalletPolicyTag.parseOne(tags)) {
WalletPolicyTag.Result.Absent -> WalletPolicyReading.Undecided
WalletPolicyTag.Result.Unreadable -> null
is WalletPolicyTag.Result.Present -> when (tag.policy) {
SubgroupWalletPolicy.GUARDED -> WalletPolicyReading.Decided(tag.policy).takeIf { guardians.isNotEmpty() }
SubgroupWalletPolicy.UNGUARDED -> WalletPolicyReading.Decided(tag.policy).takeIf { guardians.isEmpty() }
}
}
}
/**
* The guardian keys the parent grants the child, nearest first -- empty for a
@@ -0,0 +1,50 @@
package com.machankura.bennu.compose.nostr.subgroup
/**
* What a parent decided, at a subgroup's birth, about the subgroup's wallet --
* `docs/subgroup-wallet-policy.md`.
*
* Chosen by the coordinator on the subgroup picker, carried on the ceremony
* proposal so every admin sees it before joining, and signed by the parent's
* quorum into the birth certificate. Every honest device then offers, signs,
* derives and watches only the wallet it allows.
*
* Not a rule the chain enforces: the child's key is the child's, and a quorum of
* modified clients can sign whatever it likes with it. It is the parent's signed
* decision, which every client running this app keeps.
*/
enum class SubgroupWalletPolicy(val tagValue: String) {
/**
* The child can only open a guarded wallet, and its certificate carries the
* guardian keys that wallet's leaves are built from. A guarded group's own
* subgroups are guarded too.
*/
GUARDED("guarded"),
/**
* The child can only open a plain wallet. Its certificate carries no guardian
* keys, so nothing above it can reach its wallet or anything beneath it.
*/
UNGUARDED("unguarded");
companion object {
fun fromTagValue(value: String): SubgroupWalletPolicy? = entries.firstOrNull { it.tagValue == value }
}
}
/** What a birth certificate says about the child's wallet. */
sealed interface WalletPolicyReading {
/** The parent decided, and signed it. */
data class Decided(val policy: SubgroupWalletPolicy) : WalletPolicyReading
/**
* No policy tag: a certificate from before policies, which leaves the choice
* to the child -- a guarded wallet if its certificate carries keys, a plain
* one beside it either way.
*/
data object Undecided : WalletPolicyReading
}
/** Whether this reading is the parent having decided [policy]. */
fun WalletPolicyReading?.isDecided(policy: SubgroupWalletPolicy): Boolean =
(this as? WalletPolicyReading.Decided)?.policy == policy
@@ -0,0 +1,49 @@
package com.machankura.bennu.compose.nostr.subgroup.tags
import com.machankura.bennu.compose.nostr.subgroup.SubgroupWalletPolicy
/**
* A subgroup's wallet policy, as its parent decided it:
*
* ```
* ["wallet", "guarded" | "unguarded"]
* ```
*
* On a key ceremony's proposal it is what the coordinator chose, shown to every
* admin before they join; on a birth certificate it is the parent's quorum
* signing that choice. See `SubgroupWalletPolicy` and
* `docs/subgroup-wallet-policy.md`.
*
* Shape only, as `GuardianTag` is. Whether a policy agrees with the guardian
* keys beside it is the certificate's question, not the tag's.
*/
object WalletPolicyTag {
const val TAG_NAME = "wallet"
fun assemble(policy: SubgroupWalletPolicy): Array<String> = arrayOf(TAG_NAME, policy.tagValue)
/** The policy [tag] names, or null when it is not a wallet tag or names no policy this build knows. */
fun parse(tag: Array<String>): SubgroupWalletPolicy? {
if (tag.size < 2 || tag[0] != TAG_NAME) return null
return SubgroupWalletPolicy.fromTagValue(tag[1])
}
/**
* The policy [tags] carry: null for none, the policy for exactly one readable
* tag -- and [Unreadable] when a tag *named* `wallet` fails to read or there
* are two, so that a policy present and unreadable is never mistaken for one
* absent.
*/
fun parseOne(tags: Array<Array<String>>): Result {
val named = tags.filter { it.isNotEmpty() && it[0] == TAG_NAME }
if (named.isEmpty()) return Result.Absent
if (named.size > 1) return Result.Unreadable
return parse(named.single())?.let { Result.Present(it) } ?: Result.Unreadable
}
sealed interface Result {
data object Absent : Result
data object Unreadable : Result
data class Present(val policy: SubgroupWalletPolicy) : Result
}
}
@@ -20,6 +20,7 @@ import com.machankura.bennu.compose.extensions.toHex
import com.machankura.bennu.compose.managers.GuardianDerivation
import com.machankura.bennu.compose.managers.SharedKeyDerivation
import com.machankura.bennu.compose.nostr.subgroup.tags.GuardianTag
import com.machankura.bennu.compose.nostr.subgroup.tags.WalletPolicyTag
/**
* What a birth certificate is allowed to convince a member of.
@@ -375,6 +376,75 @@ class SubgroupBirthCertificateEventTest {
assertNull(SubgroupBirthCertificateEvent.parseGuardians(broken.toTypedArray()))
}
@Test
fun `a guarded certificate carries its keys and reads as guarded`() {
val tags = policyTags(SubgroupWalletPolicy.GUARDED, guardians = grant())
assertEquals(WalletPolicyReading.Decided(SubgroupWalletPolicy.GUARDED), SubgroupBirthCertificateEvent.parseWalletPolicy(tags))
assertEquals(grant(), SubgroupBirthCertificateEvent.parseGuardians(tags))
}
@Test
fun `an unguarded certificate carries no keys and reads as unguarded`() {
val tags = policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList())
assertEquals(WalletPolicyReading.Decided(SubgroupWalletPolicy.UNGUARDED), SubgroupBirthCertificateEvent.parseWalletPolicy(tags))
assertEquals(emptyList(), SubgroupBirthCertificateEvent.parseGuardians(tags))
}
@Test
fun `a certificate from before policies reads as undecided, with keys or without`() {
assertEquals(WalletPolicyReading.Undecided, SubgroupBirthCertificateEvent.parseWalletPolicy(certificate().tags))
assertEquals(WalletPolicyReading.Undecided, SubgroupBirthCertificateEvent.parseWalletPolicy(policyTags(null, guardians = grant())))
}
@Test
fun `a policy that contradicts its keys, or does not read, reads as nothing`() {
// Each of these must not fall back to undecided: that would hand the
// child the choice its parent took away.
val contradictions = mapOf(
"guarded with no keys" to policyTags(SubgroupWalletPolicy.GUARDED, guardians = emptyList()),
"unguarded with keys" to policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = grant()),
"two policies" to policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList()) + WalletPolicyTag.assemble(SubgroupWalletPolicy.UNGUARDED),
"an unknown policy" to policyTags(null, guardians = emptyList()) + arrayOf(WalletPolicyTag.TAG_NAME, "maybe"),
"an empty policy" to policyTags(null, guardians = emptyList()) + arrayOf(WalletPolicyTag.TAG_NAME),
)
contradictions.forEach { (what, tags) ->
assertNull(SubgroupBirthCertificateEvent.parseWalletPolicy(tags), "a certificate with $what was read")
}
}
@Test
fun `a policy does not touch what a certificate certifies`() {
// Lineage stays six questions. A certificate whose policy reads as nothing
// is still the parent's word that the child is its child.
listOf(
policyTags(SubgroupWalletPolicy.GUARDED, guardians = grant()),
policyTags(SubgroupWalletPolicy.UNGUARDED, guardians = emptyList()),
policyTags(SubgroupWalletPolicy.GUARDED, guardians = emptyList()),
).forEach { tags ->
assertTrue(SubgroupBirthCertificateEvent.certifies(certificate(tags = tags), subgroupChatRoomId, parentChatRoomId))
}
}
private fun grant(): List<GuardianDerivation.Guardian> =
GuardianDerivation.grant(parentMaterial.thresholdPublicKey.value.toHex(), parentChatRoomId, emptyList(), subgroupChatRoomId)
private fun policyTags(
policy: SubgroupWalletPolicy?,
guardians: List<GuardianDerivation.Guardian>,
): Array<Array<String>> = SubgroupBirthCertificateEvent.assembleTags(
subgroupChatRoomId = subgroupChatRoomId,
parentChatRoomId = parentChatRoomId,
thresholdPublicKey = childKey,
adminPublicKeys = admins,
name = name,
path = path,
guardians = guardians,
walletPolicy = policy,
)
private fun certificate(
content: String = subgroupChatRoomId,
tags: Array<Array<String>> = SubgroupBirthCertificateEvent.assembleTags(