Files
giza-kmp/docs/confederation-submodule-update.md
T
Kgothatso NgakoandClaude Opus 5.5 37079ee41b test: Giza reaches bitcoin-kmp's confederation API (confederation update, Phase 4)
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>
2026-11-21 20:08:16 +02:00

19 KiB
Raw Blame History

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 .def header lists. Everything else is added: JNI, Kotlin/Native and the Secp256k1 interface. -DSECP256K1_ENABLE_MODULE_CONFEDERATION=ON joins CMAKE_DEFAULT_OPTS in native/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 in src/modules/prefractal/tests_impl.h. No other header in include/ 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.dkgLocal and signLocal run 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.

  1. Shared .git/modules. Linked worktrees share .git/modules/ with the main checkout (jvm-target.md). The main checkout currently has every level on a claude/dependency-update branch, except zkp, which is detached at origin/claude/frost-share-refresh. All five are clean. Record git submodule status --recursive in the main checkout before you start. Restore it at the end, or say in the PR that it moved.

  2. 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 threshold at bitcoin-kmp is still 0c34097. If it has moved, pin the new tip only after reading what it adds.

  3. Check out the chain and the SDK paths:

    git submodule update --init --recursive
    

    Then add local.properties at all five Gradle roots, using the loop in the root README.md.

  4. Branch per level. Name the branches claude/confederation at lightning-kmp (from threshold) and at lightning-kmp-app (from master). 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.

  1. In …/bitcoin-kmp, check out 0c34097 and run git submodule update --recursive. Confirm that secp256k1-kmp is at fce4d81 and zkp at c68e2384.

  2. 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
    
  3. Rebuild the natives. The main checkout's native/build/linux/libsecp256k1.a is dated 2026-11-20, before confederation. native/build.gradle.kts declares the submodule sources and CMake flags as inputs, so Gradle should rebuild. Don't rely on that: delete native/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 UnsatisfiedLinkError on the first confederation call. It does not show up at compile time.

  4. In secp256k1-kmp, run :tests:jvmTest. Pay most attention to ConfederationTest, ConfederationVectorsTest, ConfederationTransitionTest and ConfederationRecoveryTest, and to the existing FROST, ChillDKG, enrollment and refresh suites, which must pass unchanged.

  5. In bitcoin-kmp, run ./gradlew jvmTest, focusing on ConfederationTestsCommon, ConfederationTaprootTestsCommon and everything under crypto/frost/ and crypto/dkg/.

  6. 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 the crypto and channel packages. 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.kts is unchanged.
  • secp256k1-kmp still says 0.24.0 at fce4d81, so the secp256k1-kmp-jni-android:0.24.0 line still resolves to :jni:android from source.
  • Nothing new arrives between d87af50 and 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, and FrostSigning*JvmTest.
  • ChillDkgRitualManager and ShareRefreshManager through their tests. Both import ChilldkgFault from secp256k1-kmp, whose enum did not change.

Done when both commands pass with no app change.

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 rpd roster from bitcoin-kmp's confederation/vectors.json, inlined as hex with a comment naming bitcoin-kmp 0c34097, and checks its hash against the vectors' rpd_hash;
  • runs Confederation.dkgLocal and signLocal once, and verifies the signature with Crypto.verifySignatureSchnorr;
  • signs under ConfederationTweak.taproot and 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 own ConfederationTaprootTestsCommon already 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 .so inside the app. Note the APK size before and after, because the native library gains a whole module.
  • A desktop run (jvm target) 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:

  1. Re-fetch. Confirm that bitcoin-kmp threshold is still 0c34097 and that nobody has advanced lightning-kmp threshold or lightning-kmp-app master in the meantime. If they have, rebase the bump onto the new tip and repeat that phase's checks.
  2. Push lightning-kmp claude/confederation. Fast-forward threshold to it and push.
  3. Push lightning-kmp-app claude/confederation. Fast-forward master to it and push.
  4. Push Giza's branch and open the PR against giza. In the PR, list the device checks not made, and note that zkp now tracks frost.

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. dkgLocal and signLocal cannot 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