Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
Submodule refresh: carrying reduced FROST enrollment up the chain
Giza builds against five nested repositories, each pinning the one below it. Today's work in secp256k1-kmp — reduced (version 2) FROST enrollment — has reached the bottom two levels and stops there. This plan moves every pointer to the tip of the branch it tracks, bottom up, so each level builds against the one beneath it as it now is.
Measured on 2026-11-19 after git fetch at every level.
Where it stands
Phases 1–5 are built and committed, each level on a local claude/reduced-frost-enrollment
branch, and nothing is pushed:
| level | commit | what | checked |
|---|---|---|---|
| secp256k1-kmp | — (at ce05021) |
Phase 1 | :tests:jvmTest 107/107, natives built from a04dc1ed |
| bitcoin-kmp | 36e2ed5 |
bump secp256k1-kmp | jvmTest 258/258 |
| bitcoin-kmp | 1982eba |
FrostReducedEnrollment + 9 tests |
jvmTest all pass |
| lightning-kmp | df778bc4 |
bump bitcoin-kmp | :lightning-kmp-core:jvmTest 1001/1002 — see below |
| lightning-kmp-app | e4779ff |
bump lightning-kmp | :library:compileKotlinJvm, :library:compileAndroidMain |
| Giza | 051b339a |
bump lightning-kmp-app | compileDebugKotlinAndroid, jvmTest 1171/1171, check |
The one lightning-kmp failure is ElectrumClientTest "get headers", a 15 s timeout fetching
2016 headers from a live Electrum server. It fails the same way with bitcoin-kmp, secp256k1-kmp
and zkp put back to 9e3c4f8 / 8adf691 / 7a35fde1, so it predates this work.
Still to do, in this order:
- Push the branches bottom up — bitcoin-kmp, lightning-kmp, lightning-kmp-app — since Giza's
commit pins
e4779ff, which exists only locally until then. - Fast-forward bitcoin-kmp and lightning-kmp
threshold, and lightning-kmp-appmaster, to those branches; tag lightning-kmp-app. - The checks Linux and this session could not make: an Android install over the current build
and a desktop run, both signing in a group; secp256k1-kmp's
connectedAndroidTest; an iOS build on a Mac.
The chain
| level | repository | tracks | pinned by its parent | tip of tracked branch | behind |
|---|---|---|---|---|---|
| 0 | giza-kmp |
giza |
— | — | — |
| 1 | kngako/lightning-kmp-app |
master |
67a0376 |
949bfcb (2026-11-02) |
3 |
| 2 | kngako/lightning-kmp |
threshold |
688d36ad (by 67a0376) / 065dcf89 (by master) |
065dcf89 (2026-11-02) |
0 from master, 3 from what Giza pins |
| 3 | kngako/bitcoin-kmp |
threshold |
9e3c4f8 |
9e3c4f8 (2026-09-15) |
0 |
| 4 | kngako/secp256k1-kmp |
threshold |
8adf691 |
ce05021 (2026-11-19) |
4 |
| 5 | frost/secp256k1-zkp |
main |
a04dc1ed (by ce05021) |
a04dc1ed (2026-11-18) |
0 |
Paths, from the Giza root:
lightning-kmp-app
└─ experimental/lightning-kmp
└─ experimental/bitcoin-kmp
└─ experimental/secp256k1-kmp
└─ native/secp256k1 (secp256k1-zkp)
So the gap is in two places:
- bitcoin-kmp → secp256k1-kmp. bitcoin-kmp pins
8adf691; the four commits after it are today's enrollment work (1b70238bump zkp,3de04cdbindings,2f60bc3tests,ce05021docs). Every level above bitcoin-kmp inherits the gap. - Giza → lightning-kmp-app. Giza pins
67a0376;masteris three commits ahead with the lightning-kmp bumps for offers (5478993,7aaacad) and the swap-in signer (949bfcb).
secp256k1-kmp → zkp is already current: 1b70238 moved it from 7a35fde1 to a04dc1ed, the
tip of zkp main, which carries the six frost_enrollment: commits of 2026-11-18.
What today's change is
Additive. Secp256k1 gains five functions and changes none:
frostEnrollmentReducedParamsHash— the v2 parameters hash, bound to asessionId32.frostEnrollmentReducedSharesGen— round 1.1, a triangular share row: u(u−1)/2 helper messages instead of u(u−1).frostEnrollmentReducedShareAgg— round 1.2, returnsFrostEnrollmentShareAggResult, naming the helper at fault by identifier.frostEnrollmentReducedSecshareGen— round 2, with the expected public share mandatory.frostEnrollmentPubshareDeriveFromCommitments— derives the expected public share from authenticated aggregate VSS commitments rather than helper public shares.
The v1 (frostEnrollment…) functions are untouched apart from KDoc; the v1 test diff is
comments only. v1 and v2 messages must never be mixed within a run, and the hashes are
incompatible by design, so nothing that speaks v1 today can be silently broken by v2.
The module is marked experimental upstream, and the generalized protocol with more helpers than the threshold "requires independent review". That is a reason to bring it in and test it, not a reason to ship a user-facing feature on it — see Phase 6.
Who calls enrollment today:
- bitcoin-kmp:
fr.acinq.bitcoin.crypto.frost.FrostEnrollmentwraps v1 only (7de8761, 2026-09-04), withFrostEnrollmentTestsCommon. - lightning-kmp, lightning-kmp-app, Giza: nothing.
So a pointer bump alone changes no behaviour anywhere above secp256k1-kmp. It only makes the v2 functions reachable.
Before starting
Use a worktree with its own submodule checkout, not the main checkout. The main checkout at
giza-kmp/ has uncommitted content in zkp (native/secp256k1/README.md modified), which shows
as m/M at every level above it. Don't commit over it or reset it — it isn't part of this work.
docs/jvm-target.md explains that linked worktrees share .git/modules/ with the main checkout;
moving a submodule's HEAD in one is visible as drift in the other. Check git submodule status --recursive in both before and after.
A concurrent fetch was seen on zkp while this was measured (cannot lock ref 'refs/remotes/origin/frost'), so another session may be working in these repositories. Check
before pushing any threshold or master.
In this worktree:
git submodule update --init --recursive
Then local.properties at all five Gradle roots (the loop is in README.md).
Branch per level. At each level, do the bump on a claude/reduced-frost-enrollment branch
cut from the tracked branch, and fast-forward the tracked branch only once Phase 5 is green. A
failure at the top should not leave threshold advanced at three levels below it. This matches
how claude/group-swap-in-signer went in.
Push order is bottom up, and nothing is pushed until the level above has been built against it. A parent may only pin a commit that exists on the child's remote; push the child's branch before the parent's commit is pushed, never the other way.
Phase 1 — verify secp256k1-kmp at ce05021
No commit. Prove the bottom of the chain works before stacking on it.
- In
…/secp256k1-kmp, check outce05021andgit submodule updateso zkp is ata04dc1ed. Confirm withgit submodule status. - Rebuild the natives. The JNI and iOS libraries are built from zkp by
native/build.sh,native/build-android.shandnative/build-ios.sh, and the main checkout'snative/build/{linux,android-*}were built from an older zkp. A stalelibsecp256k1shows up as a missingsecp256k1_frost_enrollment_reduced_*symbol at link or load time, so deletenative/build/and rebuild Linux and Android. - Run the tests that came with the change, on JVM:
FrostReducedEnrollmentTest— the end-to-end v2 run.FrostEnrollmentVectorsTest— frozen vectors from zkp's Python generator.FrostEnrollmentTest— v1, must still pass unchanged.- The rest of
:tests:jvmTest, for ChillDKG and FROST signing, which Giza uses.
- If an Android emulator is available,
:tests:connectedAndroidTestfor the same classes, since the JNI glue (fr_acinq_secp256k1_Secp256k1CFunctions.c, +226 lines) is where a marshalling mistake would hide.
Done when all of the above pass with natives built from a04dc1ed.
Decision recorded here, not made: zkp has a frost branch, 25 commits ahead of main,
holding the BIP 445 rewrite of the frost module (merged with main today, c3ad9e7e).
secp256k1-kmp tracks main (.gitmodules: branch = main) and is current with it. Moving to
frost would replace the FROST signing module Giza signs with — a different change with its own
plan, not part of a refresh.
Phase 2 — bitcoin-kmp: bump secp256k1-kmp
One commit on bitcoin-kmp claude/reduced-frost-enrollment, from threshold (9e3c4f8):
Bump secp256k1-kmp: reduced FROST enrollment
moving experimental/secp256k1-kmp from 8adf691 to ce05021.
Then in bitcoin-kmp:
./gradlew jvmTest, with the attention oncrypto/frost/—FrostEnrollmentTestsCommon(v1 through the wrapper), the ChillDKG tests, and the FROST signing tests. The wrapper calls only functions whose signatures did not change, so this should compile without edits; if it does not, that is a finding about Phase 1, not something to patch here../gradlew compileKotlinIosArm64on a Mac if one is to hand. The cinterop declaration is regenerated from the newsecp256k1_frost_enrollment.h, which grew by 180 lines.
Done when bitcoin-kmp's JVM tests pass against ce05021.
Phase 3 — bitcoin-kmp: wrap reduced enrollment (recommended, separable)
The wrapper is what Giza would call, in Giza's types (PublicKey, ByteVector32, Either), so
"making use of" v2 one level up means extending FrostEnrollment. It can land after Phases 4–5
without blocking them; doing it now means the bump that reaches Giza carries a usable API rather
than only a reachable one.
Second commit on the same branch: a new object, FrostReducedEnrollment, in
crypto/frost/FrostReducedEnrollment.kt, beside FrostEnrollment rather than inside it:
paramsHash(…, sessionId: ByteVector32).generateShares(…)returningReducedEnrollmentShares(kept, outgoing: Map<UInt, ByteVector32>, paramsHash).aggregateShares(kept, received: Map<UInt, ReducedEnrollmentMessage>, …)returningReducedShareAggregation(Aggregated(message)/HelperAtFault(helperId)).derivePublicShareFromCommitments(thresholdPublicKey, commitments: List<PublicKey?>, newId, nParticipants)—nullfor the point at infinity, encoded as 33 zero bytes on the way down.generateSecretShare(received: Map<UInt, ReducedEnrollmentMessage>, …, expectedPublicShare: PublicKey)— non-nullable, because upstream made it mandatory.
An earlier draft of this plan reused v1's EnrollmentShares and ShareAggregation. It did
not survive contact with the routing: v1's lists are aligned with the helper ids and every
non-own entry is sent, while v2 sends only to larger identifiers and smaller ones get nothing.
A position-aligned list would have made the mistake upstream warns about — routing by array
position — the natural way to call it. So v2 takes and returns messages keyed by identifier,
and checks that exactly the expected senders are present: a missing or extra message is the
caller's error (Either.Left), never a helper at fault, since blaming a helper for a message
the caller failed to route is indistinguishable, to the group, from that helper misbehaving.
v1 and v2 are separate objects with separate message types, not a version parameter, so a
mix within a run is a type error.
Copy upstream's warnings into the KDoc: experimental, not for production, and the more-helpers-than-threshold case unreviewed.
Tests in FrostReducedEnrollmentTestsCommon, mirroring FrostReducedEnrollmentTest:
- enrollment for every n in 3..5, t in 2..n, u in t..n, with helpers listed out of order, and a repair at an existing identifier, end to end through the wrapper;
- shares routed only to larger identifiers, u(u−1)/2 in all;
HelperAtFaultcarrying the right identifier when one helper's message is replayed from anothersessionId;- a missing or extra sender being an error rather than a fault;
- round 2 failing on a wrong
expectedPublicShare, a wrongsessionId, or a tampered hash; derivePublicShareFromCommitmentsagreeing withderivePublicSharefor the same group, andnullencoding the point at infinity.
Done when those pass and the v1 tests are unchanged.
Phase 4 — lightning-kmp, then lightning-kmp-app
lightning-kmp. One commit on claude/reduced-frost-enrollment from threshold
(065dcf89):
Bump bitcoin-kmp: reduced FROST enrollment
lightning-kmp uses no enrollment and no FROST enrollment wrapper, so the check is that it still
compiles and its JVM tests pass against the new bitcoin-kmp. The full suite is long; at minimum
compileKotlinJvm and the crypto and channel test packages.
lightning-kmp-app. One commit on claude/reduced-frost-enrollment from master
(949bfcb), bumping experimental/lightning-kmp from 065dcf89 to the Phase 4 commit:
Bump lightning-kmp: reduced FROST enrollment down the chain
Check :library:compileKotlinJvm and :library:compileDebugKotlinAndroid.
Tag it once the tracked branch is fast-forwarded (end of Phase 5): JitPack resolves by tag, and
docs/nsec-sign-in.md (Phase 8) set that precedent.
Phase 5 — Giza: bump lightning-kmp-app
One commit on this branch, claude/submodule-dependency-updates-64bd3d, moving
lightning-kmp-app from 67a0376 to the Phase 4 commit.
This brings in more than enrollment: the three commits between 67a0376 and master (offers
decline/answer, swap-in user key held by a signer). They are wallet code in lightning-kmp. Giza
calls none of it, and wallet-audit.sh looks at Giza's own code rather than the submodule, but
the commit message should say they arrive, so a later bisect is not surprised.
Checks, in the order they fail cheapest:
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
./gradlew check
check runs the M3, brand and wallet audits. Of the JVM tests, the ones that touch this change
are:
ForkCompatibilityTest— pins the npub and profile id derived from a phrase; it must not move.- The ChillDKG and FROST signing tests under
managers/and the subgroup ceremony tests (SubgroupCeremonyInParentRoomTest), since they drive the natives rebuilt in Phase 1.
Then:
- An Android debug build installed over the current one, opening an existing profile and
signing in a group. This is the only check that exercises the Android JNI
.sobuilt in Phase 1 inside the app.composeApp/build.gradle.ktsresolvessecp256k1-kmp-jni-android:0.24.0from source through the composite build; the version string did not change (ce05021still says0.24.0), so that line needs no edit. - A desktop build (
jvmtarget) doing the same. - An iOS build on a Mac. Not possible on Linux. Until it is done, say so in the PR.
Done when all of the above pass. Then, bottom up: fast-forward threshold in secp256k1-kmp
(already there), bitcoin-kmp, lightning-kmp, and master in lightning-kmp-app to their
claude/reduced-frost-enrollment branches, push each, tag lightning-kmp-app, and open the Giza PR.
Fast-forward rather than merge: a fast-forward makes no new commit, so every pointer already
committed in Phases 2–5 stays valid. A merge commit would mean redoing each bump above it.
Phase 6 — Giza uses reduced enrollment (not part of this refresh)
Nothing in Giza enrolls or repairs today. Doing so is a feature: adding a member to a group key
without rerunning ChillDKG, or recovering a lost share. It needs its own document in the manner of
docs/shared-key-ceremony.md, because upstream leaves exactly the hard parts to the application:
transport, deduplication, authorization, consensus on the extended public-share table, and atomic
persistence before signing. Two things this refresh does decide for it:
- Use v2 (
Reduced) only. There is no installed base of v1 enrollment messages to stay compatible with. - Get the expected public share from authenticated group state — the
GroupKeyStateEventtable, or VSS commitments if ChillDKG's are kept — never from the helpers.
And it should not ship to users while upstream calls the module experimental.
Afterwards
docs/giza-wallet-removal.md, Phase 7, plans to bring bitcoin-kmp in as Giza's own submodule
and drop lightning-kmp-app. If that lands, this chain shortens to three levels and Phases 4–5
collapse into one bump. The two do not conflict: do this refresh now, and that move starts from
a bitcoin-kmp that already has v2.
Summary
| phase | where | commit | done when |
|---|---|---|---|
| 1 | secp256k1-kmp | none | natives rebuilt from a04dc1ed; v1, v2 and vector tests pass |
| 2 | bitcoin-kmp | bump secp256k1-kmp 8adf691 → ce05021 |
JVM tests pass |
| 3 | bitcoin-kmp | FrostEnrollment v2 wrapper + tests |
wrapper tests pass, v1 unchanged |
| 4 | lightning-kmp, lightning-kmp-app | two bumps | both compile, lightning-kmp tests pass |
| 5 | Giza | bump lightning-kmp-app 67a0376 → new |
check, jvmTest, Android + desktop on device; iOS noted |
| 6 | Giza | — | separate design document |