ConfederationReachableJvmTest runs a local confederation DKG and two signatures -- one plain, one under a taproot tweak checked against the P2TR output key -- through the desktop JNI library Giza loads. A compile proves only that the classes are on the classpath; a libsecp256k1 built from an older secp256k1-zkp fails here with an UnsatisfiedLinkError. Not a ceremony: dkgLocal and signLocal run every role in one process, and nothing in the app calls them. The plan records Phases 1-4, the Android launch over an existing build, and why secp256k1-kmp's instrumented tests do not build (FrostRefreshTest's spaced method names, from before this update). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
19 KiB
Submodule update: bringing bitcoin-kmp's confederation API up to Giza
On 2026-11-21, bitcoin-kmp threshold gained fr.acinq.bitcoin.crypto.confederation. Confederation
is nested threshold keys: a roster of outer groups, each with its own inner threshold of admins,
holds one BIP 340 key. The work below bitcoin-kmp is already done and pushed. secp256k1-kmp has the
bindings, and secp256k1-zkp has the module. Nothing above bitcoin-kmp has moved. This plan carries
that work up through lightning-kmp and lightning-kmp-app to Giza, so the API can be imported from
composeApp.
It follows submodule-refresh.md, which set the procedure: a worktree with its own submodule checkout, a branch per level, pushes bottom up, and tracked branches fast-forwarded only once Giza is green. Read that first. This note covers only what is different this time.
Measured on 2026-11-21 after git fetch --all at every level, against Giza d0437d6c.
Progress
| phase | result |
|---|---|
| 0 | done 2026-11-21. FROST, ChillDKG, enrollment, refresh, MuSig and schnorrsig sources identical between zkp 31ea015c and c68e2384. Natives rebuilt from scratch for Linux and four Android ABIs, each exporting 30 secp256k1_confederation_* symbols. secp256k1-kmp :tests:jvmTest 125/125 (13 confederation); bitcoin-kmp jvmTest 293/293 (19 confederation, 51 FROST/ChillDKG). connectedAndroidTest cannot build: see below |
| 1 | done. lightning-kmp ab8d4760 on claude/confederation. :lightning-kmp-core:jvmTest crypto + channel 568/568, iceberg + prefractal 47/47 |
| 2 | done. lightning-kmp-app e6be5e5 on claude/confederation. :library:compileKotlinJvm, :library:compileAndroidMain |
| 3 | done. Giza 4555f5d1. compileDebugKotlinAndroid; jvmTest 1411/1411; check with the brand, M3, Magpie lock, Marmot and wallet audits all at 0. No app change |
| 4 | done but for the device checks below. ConfederationReachableJvmTest 3/3 through the desktop JNI library Giza loads. Android: a debug build installed over the existing one on Medium_Phone (API 36, x86_64; its Room schema was 42, the same as this branch's) launches and loads libsecp256k1-jni.so with no crash or link error. That profile had no group, so no group was signed in. The Alice/Bob/Charlie emulators were left alone. Desktop run and iOS build not done. libsecp256k1-jni.so is now 1.6–2.0 MB per ABI; no pre-bump APK was at hand to compare |
secp256k1-kmp's instrumented tests don't build, and this update didn't cause it.
:tests:dexBuilderDebugAndroidTest fails because D8 rejects the method name
`the zkp vectors come out the same through the bindings` in FrostRefreshTest: names with
spaces need DEX 040, i.e. a minSdk of 30. -Pandroid.injected.build.api=36 doesn't get around
it. The test came in with 0f5a710 (2026-11-19, FROST share refresh) and is already in bcaa985,
which Giza pinned before this update. None of the confederation tests use spaced names. The
fix is to rename the methods in FrostRefreshTest. That is a secp256k1-kmp commit, and the
chain above it would have to be bumped again, so it is left for its own change.
This worktree does not use git submodule update --init. That would share, and repoint,
the main checkout's .git/modules. Instead each level is an independent git clone of the
main checkout's copy, with origin set back to the real remote and fetched. Giza records the
gitlink from the nested repository's HEAD all the same.
Where it stands
| level | repository | tracks | pinned by its parent | tip of tracked branch | gap |
|---|---|---|---|---|---|
| 0 | giza-kmp |
giza |
— | d0437d6c |
— |
| 1 | kngako/lightning-kmp-app |
master |
d87af50 |
d87af50 |
0 |
| 2 | kngako/lightning-kmp |
threshold |
f8835338 |
f8835338 |
0 |
| 3 | kngako/bitcoin-kmp |
threshold |
0fd254b (by f8835338) |
0c34097 |
3 |
| 4 | kngako/secp256k1-kmp |
threshold |
fce4d81 (by 0c34097) / bcaa985 (by 0fd254b) |
fce4d81 |
0 from bitcoin-kmp's tip |
| 5 | frost/secp256k1-zkp |
frost (was main) |
c68e2384 (by fce4d81) |
c68e2384 |
0 |
The gap is one pointer: lightning-kmp pins bitcoin-kmp at 0fd254b, three commits behind
threshold. Every level above it inherits that gap. Every level below is already current.
0fd254b is an ancestor of 0c34097, so the update is a fast-forward and nothing has to be merged.
The three bitcoin-kmp commits:
| commit | what |
|---|---|
50c0e1c |
secp256k1-kmp bcaa985 → fce4d81. No source change. The commit says the existing suites pass unchanged on jvm and linuxX64. |
42d184d |
Confederation, ConfederationRoster, ConfederationKeyState, ConfederationTransition, ConfederationShare, ConfederationRecoveryPackage, ConfederationOperation, plus tests and vectors copied from secp256k1-kmp fce4d81 |
0c34097 |
ConfederationTweak.taproot and Confederation.signTaprootInputLocal: BIP 341 key-path signing, tested end to end through the script interpreter |
Below them, secp256k1-kmp bcaa985..fce4d81 adds seven commits: the zkp bump, the descriptors,
transitions, shares and recovery, DKG and signing, hardening, and docs. zkp 31ea015c..c68e2384
adds 88 commits, the confederation module merged with frost_refresh.
What arrives, and what it can and cannot do
It is additive. At every level the diff touches only confederation:
- bitcoin-kmp: six files, all under
crypto/confederation/, plus the submodule pointer. - secp256k1-kmp: one line removed in
Secp256k1.kt, plus the.defheader lists. Everything else is added: JNI, Kotlin/Native and theSecp256k1interface.-DSECP256K1_ENABLE_MODULE_CONFEDERATION=ONjoinsCMAKE_DEFAULT_OPTSinnative/build.gradle.kts. - zkp: outside
src/modules/confederation/,include/secp256k1_confederation.h, tools, docs and examples, the only changes are build wiring,src/secp256k1.c(+4, the include),src/tests.c,src/ctime_tests.c, and a ChillDKG test insrc/modules/prefractal/tests_impl.h. No other header ininclude/changed, and neither did the FROST, ChillDKG, enrollment or refresh sources Giza signs with.
Giza can use it in tests, but not across devices. The bitcoin-kmp KDoc is explicit on this:
Confederation.dkgLocalandsignLocalrun every role in one process, holding every host secret key and every share. They are a simulation and test harness. "The round-by-round steps, and enrollment, refresh, masking and resharing, are not public at the pinned native revision."- The module is experimental research code, "not audited or stable", and "must not be used in production or to protect value". The recovery-package encryption is "a non-standard candidate construction that has not been reviewed".
- Transport, sender authentication, durable attempt records, timeouts and atomic persistence are left to the application.
So after this update Giza can import the confederation types, build rosters and key states from their canonical encodings, and run a whole confederation in a test. It cannot yet run a confederation ceremony across members' devices. That has to wait until the distributed rounds are public, and it needs its own design document, as reduced enrollment did (submodule-refresh.md, Phase 6).
zkp now tracks frost, not main. secp256k1-kmp fce4d81 changed its .gitmodules branch
to frost. submodule-refresh.md recorded that move as a decision not
taken, because zkp's frost branch held the BIP 445 rewrite of the FROST signing module. It has
now been taken upstream, as part of this work. At the pinned commits the FROST sources are
byte-identical (Phase 0 re-checks this), so Giza's signing does not change. But from now on, any
git submodule update --remote at that level follows frost. The next zkp bump is where a
signing-module change could come in, and its plan has to check for it.
Before starting
This worktree (claude/submodule-update-bitcoin-kmp-5aa639) has the submodule registered but not
checked out. lightning-kmp-app/ is empty.
-
Shared
.git/modules. Linked worktrees share.git/modules/with the main checkout (jvm-target.md). The main checkout currently has every level on aclaude/dependency-updatebranch, except zkp, which is detached atorigin/claude/frost-share-refresh. All five are clean. Recordgit submodule status --recursivein the main checkout before you start. Restore it at the end, or say in the PR that it moved. -
Concurrent work. bitcoin-kmp's three commits landed at 19:36–19:42 today. Another session may still be working at the bitcoin-kmp or secp256k1-kmp level. Re-fetch before each push, and confirm that
thresholdat bitcoin-kmp is still0c34097. If it has moved, pin the new tip only after reading what it adds. -
Check out the chain and the SDK paths:
git submodule update --init --recursiveThen add
local.propertiesat all five Gradle roots, using the loop in the rootREADME.md. -
Branch per level. Name the branches
claude/confederationat lightning-kmp (fromthreshold) and at lightning-kmp-app (frommaster). Giza's branch is this worktree's. bitcoin-kmp, secp256k1-kmp and zkp need no branch, because nothing is committed there.
Phase 0: confirm the bottom of the chain
No commit. Prove that what lightning-kmp is about to pin builds and passes, before stacking on it.
-
In
…/bitcoin-kmp, check out0c34097and rungit submodule update --recursive. Confirm that secp256k1-kmp is atfce4d81and zkp atc68e2384. -
Confirm that the FROST signing module did not change under the tracking-branch move. Each of these should print nothing:
git -C …/native/secp256k1 diff --stat 31ea015c c68e2384 -- src/modules/frost src/modules/chilldkg src/modules/frost_enrollment src/modules/frost_refresh src/modules/musig include/secp256k1_frost.h include/secp256k1_chilldkg.h include/secp256k1_frost_enrollment.h include/secp256k1_frost_refresh.h -
Rebuild the natives. The main checkout's
native/build/linux/libsecp256k1.ais dated 2026-11-20, before confederation.native/build.gradle.ktsdeclares the submodule sources and CMake flags as inputs, so Gradle should rebuild. Don't rely on that: deletenative/build/, rebuild Linux and Android, then confirm the symbols are there:nm native/build/linux/libsecp256k1.a | grep -c secp256k1_confederation_A stale library shows up later as an
UnsatisfiedLinkErroron the first confederation call. It does not show up at compile time. -
In secp256k1-kmp, run
:tests:jvmTest. Pay most attention toConfederationTest,ConfederationVectorsTest,ConfederationTransitionTestandConfederationRecoveryTest, and to the existing FROST, ChillDKG, enrollment and refresh suites, which must pass unchanged. -
In bitcoin-kmp, run
./gradlew jvmTest, focusing onConfederationTestsCommon,ConfederationTaprootTestsCommonand everything undercrypto/frost/andcrypto/dkg/. -
If an emulator is available, run secp256k1-kmp
:tests:connectedAndroidTest. The JNI glue grew by 828 lines of C (fr_acinq_secp256k1_Secp256k1CFunctions.c), and a marshalling mistake would hide there.
Done when both JVM suites pass against natives built from c68e2384, and the FROST diff above
is empty.
If the FROST diff is not empty, stop. The update then changes how Giza signs, and that needs its own plan.
Phase 1: lightning-kmp, bump bitcoin-kmp
One commit on lightning-kmp claude/confederation, from threshold (f8835338), moving
experimental/bitcoin-kmp from 0fd254b to 0c34097:
Bump bitcoin-kmp: confederation
0fd254b -> 0c34097: the Confederation API and taproot key-path signing
over secp256k1-kmp fce4d81 / secp256k1-zkp c68e2384. Additive; zkp now
tracks its `frost` branch.
lightning-kmp calls no confederation code. The check is that it still compiles and that its FROST and crypto tests pass against the new natives:
:lightning-kmp-core:compileKotlinJvm:lightning-kmp-core:jvmTest, at least thecryptoandchannelpackages. The full suite is long.ElectrumClientTest"get headers" times out against a live server and did so before this work (submodule-refresh.md), so don't count it as a regression.
Done when those pass.
Phase 2: lightning-kmp-app, bump lightning-kmp
One commit on lightning-kmp-app claude/confederation, from master (d87af50), moving
experimental/lightning-kmp from f8835338 to the Phase 1 commit:
Bump lightning-kmp: confederation down the chain
Checks:
:library:compileKotlinJvm:library:compileAndroidMain
Done when both compile.
Phase 3: Giza, bump lightning-kmp-app
One commit on this branch, moving lightning-kmp-app from d87af50 to the Phase 2 commit. It
follows the subject style of c8a529a1:
build: lightning-kmp-app with bitcoin-kmp's confederation down the chain
No change to composeApp/build.gradle.kts is expected:
- The composite substitution in
settings.gradle.ktsis unchanged. - secp256k1-kmp still says
0.24.0atfce4d81, so thesecp256k1-kmp-jni-android:0.24.0line still resolves to:jni:androidfrom source. - Nothing new arrives between
d87af50and the Phase 2 commit except the bump. Unlike the last refresh, no unrelated wallet commits come along.
Checks, cheapest failure first:
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
./gradlew check
check runs the M3, brand and wallet audits. The bump touches none of the files they scan, and
wallet-audit.sh reads Giza's own code rather than the submodule. They should pass untouched. Of
the JVM tests, these exercise the rebuilt natives:
ForkCompatibilityTest. Its npub, profile id and host key must not move.FrostSigningRoundTest,SharedKeyDerivationTest, and the ceremony suites:CeremonyAcrossDevicesJvmTest,RobustRoomKeyCeremonyTest,SubgroupCeremonyInParentRoomTest, andFrostSigning*JvmTest.ChillDkgRitualManagerandShareRefreshManagerthrough their tests. Both importChilldkgFaultfrom secp256k1-kmp, whose enum did not change.
Done when both commands pass with no app change.
Phase 4: prove Giza can reach it (recommended)
A bump that compiles proves the classes are on the classpath. It does not prove the native library
Giza loads has the confederation symbols in it. Add one JVM test in composeApp/src/jvmTest,
ConfederationReachableJvmTest, that:
- parses the
rpdroster from bitcoin-kmp'sconfederation/vectors.json, inlined as hex with a comment naming bitcoin-kmp0c34097, and checks its hash against the vectors'rpd_hash; - runs
Confederation.dkgLocalandsignLocalonce, and verifies the signature withCrypto.verifySignatureSchnorr; - signs under
ConfederationTweak.taprootand checks the signature against the P2TR output key, and not against the internal key. It does not build or spend a transaction: Giza keeps no wallet, and bitcoin-kmp's ownConfederationTaprootTestsCommonalready covers the spend.
It is a test, not a feature. Nothing in commonMain imports crypto.confederation, and the
test's KDoc repeats upstream's single-process warning, so nobody reads it as a ceremony.
Then the checks this tree cannot fully run:
- An Android debug build installed over the current one. Open an existing profile and sign in
a group. This is the only check that exercises the rebuilt Android JNI
.soinside the app. Note the APK size before and after, because the native library gains a whole module. - A desktop run (
jvmtarget) doing the same. - An iOS build on a Mac, where cinterop regenerates from the new header list. This can't be done on Linux. Until it is done, say so in the PR.
Done when the test passes on JVM, and the device checks pass or are listed in the PR as not done.
Phase 5: land, bottom up
Only once Phases 3 and 4 are green:
- Re-fetch. Confirm that bitcoin-kmp
thresholdis still0c34097and that nobody has advanced lightning-kmpthresholdor lightning-kmp-appmasterin the meantime. If they have, rebase the bump onto the new tip and repeat that phase's checks. - Push lightning-kmp
claude/confederation. Fast-forwardthresholdto it and push. - Push lightning-kmp-app
claude/confederation. Fast-forwardmasterto it and push. - Push Giza's branch and open the PR against
giza. In the PR, list the device checks not made, and note that zkp now tracksfrost.
Fast-forward rather than merge. A fast-forward makes no new commit, so the pointers committed in Phases 1–3 stay valid. A merge commit would mean redoing every bump above it. A parent may only pin a commit that exists on the child's remote, so each child is pushed before its parent.
Still open from the last refresh: lightning-kmp-app has no tags, so JitPack consumers can't
resolve it by version. If a tagging scheme gets chosen, tag the fast-forwarded master here.
Phase 6: Giza uses confederation (not part of this update)
Nothing in Giza is a confederation today. The obvious use is a subgroup structure in which a parent room's key is held by its subgroups (subgroups.md). Building it is a feature and needs its own document in the manner of shared-key-ceremony.md, and it is blocked on upstream:
- The distributed DKG and signing rounds must be public in zkp, and wrapped in bitcoin-kmp, before
Giza can run either over Marmot.
dkgLocalandsignLocalcannot be the basis of a ceremony. - The roster's entity attestation, the transition certificate's "authorization, not consensus", and the per-epoch exposure of a compromised host key are all left to the application. Each needs a decision in that document.
- It should not ship to users while upstream calls the module experimental. Like share refresh, it would be built behind a flag that is off in release.
Afterwards
giza-wallet-removal.md Phase 7b plans to make bitcoin-kmp Giza's own submodule and drop lightning-kmp-app. It has not been built. If it lands, this chain shortens to three levels and Phases 1–3 collapse into one bump. The two don't conflict: do this update now, and 7b starts from a bitcoin-kmp that already has confederation.
Summary
| phase | where | commit | done when |
|---|---|---|---|
| 0 | secp256k1-kmp, bitcoin-kmp | none | natives rebuilt from c68e2384; both JVM suites pass; FROST sources unchanged |
| 1 | lightning-kmp | bump bitcoin-kmp 0fd254b → 0c34097 |
compiles; crypto and channel tests pass |
| 2 | lightning-kmp-app | bump lightning-kmp f8835338 → Phase 1 |
:library compiles for JVM and Android |
| 3 | Giza | bump lightning-kmp-app d87af50 → Phase 2 |
compileDebugKotlinAndroid, jvmTest, check, with no app change |
| 4 | Giza | ConfederationReachableJvmTest |
test passes; Android and desktop on device; iOS noted |
| 5 | all | fast-forward threshold / master, push bottom up |
Giza PR open |
| 6 | Giza | — | separate design document, after upstream publishes the distributed rounds |