Skip to content

feat: add Paykit server accounts#630

Open
ben-kaufman wants to merge 16 commits into
codex/paykit-rc33-receiversfrom
codex/paykit-watch-only-accounts
Open

feat: add Paykit server accounts#630
ben-kaufman wants to merge 16 commits into
codex/paykit-rc33-receiversfrom
codex/paykit-watch-only-accounts

Conversation

@ben-kaufman

@ben-kaufman ben-kaufman commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Description

This PR builds on #620 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 companion authorization and fails 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.
  • 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.56, and Bitkit Core 0.4.2; Bitkit Core now supplies trusted extended-public-key serialization, so Base58Swift and its BigInt dependency are 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:

QA Notes

Manual Tests

  • Scanner → exact Paykit Server setup request → approve watch-only sharing → complete normal Pubky authorization: the account becomes active.
  • Claimed xpub → 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

  • WatchOnlyAccountServiceTests.swift
  • PubkyAuthApprovalSheetTests.swift
  • PubkyAuthRequestTests.swift
  • PaykitReceiverNoiseKeyStoreTests.swift
  • Paykit rc37 simulator build succeeded against LDK Node rc.56.
  • The iOS and Android receiver-key tests share an independently verified derivation vector and cover persistence, reuse, invalid caches, and wrong-seed fail-closed behavior.
  • 75 selected Paykit, Pubky Auth, endpoint, and receiver-key tests passed.
  • SwiftFormat and git diff --check passed.

@greptile-apps

greptile-apps Bot commented Jul 15, 2026

Copy link
Copy Markdown

Greptile Summary

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

  • Strict parsing for the watch-only companion claim and capability.
  • Companion authorization with tracked setup and retry states.
  • Monotonic account allocation, backup, restore, and reconciliation.
  • LDK scanning and tracking controls for additional wallet accounts.
  • Deterministic receiver Noise-key derivation and persistence.
  • Settings screens for managing account names and tracking.

Confidence Score: 5/5

This looks safe to merge.

  • The updated delivery-error handling keeps the account tracked after the documented post-delivery authorization failure.
  • No blocking issue remains in the reviewed changes.

Important Files Changed

Filename Overview
Bitkit/Services/PubkyService.swift Adds companion authorization and preserves account tracking for the documented post-delivery authorization failure.
Bitkit/Services/WatchOnlyAccountService.swift Adds account allocation, persistence, authorization lifecycle, backup restoration, and tracking reconciliation.
Bitkit/Services/LightningService.swift Integrates watch-only accounts with LDK startup, scanning, address lookahead, and tracking controls.

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

Comment thread Bitkit/Services/PubkyService.swift
@ben-kaufman
ben-kaufman marked this pull request as draft July 15, 2026 21:23
@ben-kaufman
ben-kaufman marked this pull request as ready for review July 16, 2026 15:19
@ben-kaufman
ben-kaufman marked this pull request as draft July 20, 2026 11:18
@ben-kaufman
ben-kaufman marked this pull request as ready for review July 20, 2026 11:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant