feat: add Paykit server accounts

[ben-kaufman]

Description

This PR builds on #1066 to add Paykit Server watch-only accounts:

• Presents a dedicated watch-only consent step before the normal Pubky authorization screen.
• Requires x-bitkit-claim=watch-only-account-v1 and the exact /pub/paykit/v0/bitkit/server/:rw capability, rejecting missing, unknown, duplicate, or mismatched companion parameters.
• Uses Paykit approveAuthWithCompanionClaim, failing closed if companion delivery or normal authorization fails.
• Allocates monotonic BIP84 accounts, reuses the same incomplete account on retry, and exports the exact versioned 84-byte claim payload.
• Automatically names new accounts from the requesting service; users can rename them later from Settings.
• Hides Settings → Advanced → Server Accounts until the experimental Paykit UI is enabled.
• Persists and backs up account metadata, serializes lifecycle and reconciliation changes, and supports disabling or restoring LDK tracking without deleting wallet state.
• Configures additional-wallet scanning and the rolling 1,000-address lookahead.
• Deterministically derives the receiver Noise key from the wallet's BIP39 seed using domain-separated HKDF-SHA256 with version, network, and receiver-path context; securely caches and verifies it so the wallet seed remains the only backup required.
• Reuses the derived Noise key across authentication and restarts, and publishes only its receiver marker when live session access becomes available.
• Updates to Paykit 0.1.0-rc37, LDK Node 0.7.0-rc.57, and Bitkit Core 0.4.2; Bitkit Core now supplies trusted extended-public-key serialization, so BitcoinJ is no longer required.

The relay claim contains only the versioned account index, address type, and serialized xpub. Local names and tracking state are not disclosed. Ordinary Pubky Auth remains unchanged.

References:

• Base PR: feat: support paykit receiver paths #1066
• Companion iOS PR: feat: add Paykit server accounts bitkit-ios#630
• Server boundary ADR: https://github.com/pubky/paykit-server/blob/master/docs/ADRs/0001-minimal-paykit-server-boundaries.md#creator-setup-and-bitkit-watch-only-account-claim

QA Notes

This slice implements ADR 0001's watch-only-account-v1 claim, which is the currently agreed protocol. ADR 0002's proposed watch-only-account-service-v1 delegation flow has not been agreed and is not part of the current implementation.

Reviewers can exercise the complete Bitkit-side setup and account lifecycle with this disposable test request:

pubkyauth://signin?caps=/pub/paykit/v0/bitkit/server/:rw&relay=https://httprelay.pubky.app/inbox/&secret=e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3s&x-bitkit-claim=watch-only-account-v1

Enable Paykit UI, then scan or paste the URL. It exercises watch-only consent, normal Pubky authorization, account allocation and xpub export, companion-claim delivery followed by AuthToken delivery, local activation, and Server Accounts management. The xpub can be copied from the account details and used for external address derivation, funding, restart discovery, spending, and tracking disable/re-enable testing.

The request secret is public, so this URL must only be used with a disposable regtest wallet. A Paykit Server listener or receiver harness is still required to verify requester-side relay polling, decryption, and signature verification. A staging deployment is intended once Paykit Server runtime/listener composition is available.

Manual Tests

• Enable Paykit UI → Settings → Advanced: Server Accounts is visible; disable Paykit UI: it is hidden.
• Scanner/paste → use the disposable setup request above → approve watch-only sharing → complete normal Pubky authorization: the account becomes active.
• Copy the xpub from Server Accounts → externally derive a nonzero receive address → send funds → restart Bitkit: the additional-wallet full scan discovers the funds.
• Spend the externally received funds from Bitkit.
• Settings → Advanced → Server Accounts → disable and re-enable tracking: the same account and balance return without allocating another account.
• Missing, duplicate, unknown, or mismatched companion parameters/capability are rejected; ordinary Pubky Auth remains unchanged.

Automated Checks

• WatchOnlyAccountClaimCodecTest.kt
• WatchOnlyAccountStoreTest.kt
• WatchOnlyAccountRepoTest.kt
• WatchOnlyAccountLifecycleCoordinatorTest.kt
• WatchOnlyAccountRestoreTest.kt
• PubkyAuthApprovalViewModelTest.kt
• PubkyAuthRequestTest.kt
• PubkyRepoTest.kt
• LightningServiceTest.kt
• PaykitSdkServiceTest.kt
• PrivatePaykitRepoTest.kt
• The Android and iOS receiver-key tests share an independently verified derivation vector and cover persistence, reuse, invalid caches, and wrong-seed fail-closed behavior.
• Post-delivery normal-auth failure, retry after delivery, restart retry, activation, and wallet Paykit regressions are covered by the selected suites.
• Paykit rc37 Kotlin compilation and 300 selected watch-only, SDK/private Paykit, restore, backup, Lightning, and wipe tests passed after rebase.
• ./gradlew testDevDebugUnitTest
• ./gradlew detekt (passes with unrelated existing findings)

[greptile-apps]

Greptile Summary

This PR adds Paykit Server watch-only accounts. The main changes are:

• Companion-claim validation and a dedicated consent flow.
• Persistent account allocation, backup, restore, and lifecycle handling.
• LDK tracking, reconciliation, and address lookahead.
• Deterministic receiver Noise-key derivation and storage.
• Server account controls in Advanced Settings.
• Paykit, LDK Node, and Bitkit Core dependency updates.

Confidence Score: 5/5

No additional blocking issue was found in this follow-up.

• The remaining activation-recovery concern is the same failure already reported.
• No separate failure requiring an independent fix was confirmed.

Important Files Changed

Filename	Overview
app/src/main/java/to/bitkit/ui/screens/profile/PubkyAuthApprovalViewModel.kt	Adds the watch-only consent and companion-claim authorization flow.
app/src/main/java/to/bitkit/repositories/WatchOnlyAccountRepo.kt	Adds account preparation, tracking, activation, cancellation, and restore operations.
app/src/main/java/to/bitkit/data/WatchOnlyAccountStore.kt	Adds persistent account, allocation, backup, and reconciliation state.
app/src/main/java/to/bitkit/services/LightningService.kt	Adds LDK configuration and reconciliation for watch-only accounts.

_{Reviews (3): Last reviewed commit: "fix: derive Paykit Noise key from wallet..." | Re-trigger Greptile}

[piotr-iohk]

Reviewed this against the companion iOS PR and paykit-server (ADR 0001 / 0002 + README).

UI gating

Settings → Advanced → Server Accounts is always visible today. Please hide it behind Enable Paykit UI (same pattern as Payment Preferences / other Paykit surfaces), so this unfinished server flow doesn’t show up for default users.

How to test / blocker

Full happy-path QA needs a real Paykit Server setup pubkyauth://… URL (x-bitkit-claim=watch-only-account-v1 + exact /pub/paykit/v0/bitkit/server/:rw), then:

Scanner/paste → watch-only consent → authorize → account appears under Server Accounts → external fund of claimed xpub → restart/scan → spend → disable/re-enable tracking.

That path isn’t available end-to-end right now: paykit-server is not runnable (README: partial implementation; main loads config then exits with runtime composition is not implemented). No listener / no setup QR from a live server.

Questions:

1. How should reviewers exercise the consent + companion-claim flow today (harness / mock URL / internal tooling)?
2. Is there a plan to host paykit-server on staging once the runtime is composed?

Without that, we can only review code/UI structure + unit coverage; not the live setup → claim → track → fund path.

Other notes

• Unit coverage for claim parsing, lifecycle, restore, and Noise-key derivation looks solid.
• Greptile’s post-delivery / markActive edge cases are still worth confirming (retry after remote success vs activation-only recovery).
• ADR 0001’s watch-only-account-v1 claim is superseded by ADR 0002 (watch-only-account-service-v1 + delegation). This PR implements v1, which matches current server runtime notes, but worth confirming that’s intentional for this Bitkit slice.
• Also worth a quick regression on wallet Paykit (contacts / LN) because of the Noise-key + Paykit/LDK/Core bumps.

CI / merge

Merge conflicts with the base branch (codex/paykit-rc33-receivers) — please rebase/resolve.

Happy to re-test once there’s a setup URL path (or staging) and the above are addressed.

[ben-kaufman]

Thanks — the app-side items are now addressed on the latest commit.

UI gating

Settings → Advanced → Server Accounts is now only visible when Enable Paykit UI is enabled.

Testing the flow

Reviewers can exercise the Bitkit-side flow using this disposable request:

pubkyauth://signin?caps=/pub/paykit/v0/bitkit/server/:rw&relay=https://httprelay.pubky.app/inbox/&secret=e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3t7e3s&x-bitkit-claim=watch-only-account-v1

Enable Paykit UI, then paste or scan it. This exercises:

1. Watch-only account consent.
2. Normal Pubky authorization.
3. Account allocation and xpub export.
4. Companion-claim delivery followed by AuthToken delivery.
5. Local account activation and Server Accounts management.

A requester does not need to remain connected: Paykit uploads both relay messages and Bitkit activates the account after both deliveries succeed.

From Server Accounts, the reviewer can copy the xpub, derive a nonzero external address, fund it, restart Bitkit, spend the discovered funds, and test disabling/re-enabling tracking. Because the URL contains a public test secret, it should only be used with a disposable regtest wallet.

What this does not verify is requester-side polling, decryption, and signature verification of the claim. That still requires a Paykit Server listener or receiver harness.

Server staging

The intended next server-side QA step is to deploy Paykit Server on staging once its runtime/listener composition is implemented. There is no staging endpoint yet, and that work is outside these mobile PRs.

Retry and activation behavior

The post-delivery cases are covered:

• If Paykit reports its documented post-delivery AuthorizationFailure, the account remains authorizing and tracked.
• Retrying the same request reuses the same account index, xpub, and persisted account.
• Pre-delivery failures unload a newly pending account.
• markActive runs in a non-cancellable lifecycle section.
• If local activation persistence fails after remote delivery, retrying after restart repeats the combined authorization with the same account and then completes activation. No new account is allocated.

This behavior is covered by the repository and approval ViewModel tests.

Protocol version

ADR 0001's watch-only-account-v1 is the currently agreed protocol and is intentionally implemented here. ADR 0002's proposed watch-only-account-service-v1 delegation flow has not been agreed and is not part of the current implementation.

Regression and CI

The branch was rebased onto the latest stacked base and is currently mergeable. The full Android unit suite, Detekt, builds, and all current E2E checks pass, including the staging pubky_paykit regression. The focused verification includes 300 watch-only, Paykit SDK/private Paykit, restore, backup, Lightning, and wipe tests.

[piotr-iohk]

Thanks! Retested Bitkit-side flow with the disposable setup URL on both platforms. Happy path looks good; a few nits remain.

Verified OK

• Disposable pubkyauth://…watch-only-account-v1 → consent → authorize → Server Accounts active
• Paykit UI off: Server Accounts row hidden; pubkyauth paste/scan does not open approval
• Wallet Paykit regression (contacts / LN) after Noise-key + LDK bumps
• Copy xpub → external nonzero address → fund → receive → spend on iOS and Android
• Track account disable/re-enable: same xpub / no new allocation. With tracking off (including after restart), those funds correctly leave savings balance; re-enable should bring them back after sync

1. Settings row consistency (icon + title casing)

Settings → Advanced → Server Accounts is Paykit-UI gated (good). Cross-platform mismatch remains:

	Android	iOS
Title	Server accounts	Server Accounts
Icon	ic_lock_key (red safe/lock)	keyring (keys)

Worth aligning if designs exist; otherwise pick one icon + casing for both.

2. Android: missing drawer burger on Server Accounts

iOS shows the header menu (burger) via NavigationBar default. Android WatchOnlyAccountsScreen uses AppTopBar without actions = { DrawerNavIcon() }, while sibling screens (e.g. Address Viewer, Settings) include it. Please add the drawer action for parity.

Also description copy differs slightly (Android mentions “revoking the service session”; iOS doesn’t).

3. No Pubky identity toast

With no Bitkit Pubky identity / profile, scanning or pasting the setup URL shows:

• Android: title-only toast — “Use Ring to manage authorizations” (profile__auth_approval_ring_only)
• iOS: “Pubky Identity Required” / “Create a Pubky identity in your profile…” (pubky_auth__no_identity + _desc)

Android collapses “no identity” and “Ring-only” into one string. Prefer matching iOS’s clearer no-identity copy (and keep a separate Ring-only path if needed).

4. Send entry points for pubkyauth://

Confirmed working on Android from:

• Global scan / paste
• Send → Paste invoice
• Send → Enter manually

iOS supports scan + Send paste, but Send → Enter manually rejects .pubkyAuth as invalid (performValidation default).

Question: should pubkyauth be accepted from Send at all? If yes → align iOS Enter manually. If no → remove from Send paste/manual on both and keep global scan only.

Recording for §3–4:

Screen.Recording.2026-07-22.at.16.11.08.mov

5. OBS — Electrum timeouts under watch-only tracking

• iOS: once saw Incomplete setup after authorize; retry succeeded. Logs: Electrum/LDK timeouts during watch-only ops (exportWatchOnlyAccountXpub ~33s, WalletOperationTimeout), then recovery on retry.
• Android: similar Electrum sync timeouts for additional NativeSegwit accounts during fund/spend; did not block receive/spend.

Recovery/lifecycle looks fine; looks like Electrum load under concurrent additional-wallet sync.

Remaining optional

• Ordinary Pubky auth (no claim) still works

[piotr-iohk]

Retested after the alignment fixes. Settings nits look good (icon/casing, drawer burger). Limiting pubkyauth away from Send paste / Enter manually is fine.

Blocking: home Scan still rejects pubkyauth.

Tab bar Scan opens Send, not a main scanner:

onScanClick = { appViewModel.showSheet(Sheet.Send(SendRoute.QrScanner)) }

Gate is:

private val isMainScanner get() = currentSheet.value !is Sheet.Send

So home Scan → Sheet.Send → isMainScanner == false → QR error toast, never approval.

Send paste / Send scan / Enter manually rejecting pubkyauth is correct. Only home Scan was over-gated.

Please:

1. Treat home Scan as main (or pass an explicit allow-pubkyauth flag)
2. Add a unit test that opens Sheet.Send(SendRoute.QrScanner), scans pubkyauth://…, and expects the approval sheet (current “main scanner” test doesn’t open Send first, so it misses this)

[ben-kaufman]

Thanks for the thorough cross-platform retest.

Items 1–4 were addressed in Android commit b0f0c0a4 and matching iOS commit 728a39a9:

• Both platforms now use Server Accounts and the lock-key icon.
• Android now includes the drawer action.
• The account description and empty-state copy are aligned.
• Android now distinguishes “no Pubky identity” from a Ring-owned identity.
• We decided that pubkyauth:// is an authorization input, not a payment input. It remains supported through global scan/paste and deep links, while Send scan/paste/manual reject it consistently on both platforms.

Focused coverage was added for the identity states and Send/global-scanner routing. Ordinary Pubky Auth remains unchanged.

Thanks also for confirming the complete xpub funding/spending and tracking lifecycle. We’ve noted the Electrum timeout observation. Since both platforms recovered correctly through retry and it did not prevent receive/spend, we’re treating it as a backend-load observation rather than a blocker for this PR.

The two subsequent inline review items were addressed in ddc9b2e0b: URL decoding now supports the API 28 minimum, and watch-only errors are instantiated per throw rather than reused as singleton Throwables. Local Kotlin compilation, the full unit suite, Detekt, and Android Lint pass.

[piotr-iohk]

We decided that pubkyauth:// is an authorization input, not a payment input. It remains supported through global scan/paste and deep links, while Send scan/paste/manual reject it consistently on both platforms.

As I mentioned in #1084 (comment), home scan currently blocks pubkyauth on android. Also on current HEAD.

Screen.Recording.2026-07-24.at.10.40.35.mov

[ben-kaufman]

Fixed in 57626b7cf. You were right: the home tab scan button was still opening Sheet.Send(SendRoute.QrScanner), so pubkyauth:// was being classified as Send input and rejected.

The home scan button now opens the global scanner via showScannerSheet(). Send scan/paste/manual behavior is unchanged and continues to reject pubkyauth://.

I also updated the regression test to exercise the real global scanner-sheet path (showScannerSheet() → onScannerSheetResult) before asserting that the Pubky approval sheet opens.

Verified with:

• focused global-scanner Pubky Auth test
• ./gradlew compileDevDebugKotlin
• ./gradlew testDevDebugUnitTest
• ./gradlew detekt --rerun-tasks (only existing unrelated baseline findings)
• ./gradlew lintDevDebug

[piotr-iohk]

tACK

[jvsena42]

tAck

Screen_recording_20260724_081015.webm

[jvsena42]

Commits must have verified signatures.

@ben-kaufman please, force-push or squash the commits with verified signature