BIP Compliance Matrix

This document maps the Paykit BIP specification to the implementation, identifying compliance status and any deviations.

Overview

BIP: Paykit - Payment Method Discovery and Negotiation Protocol
Status: Draft
Implementation Version: 0.2.0

Conformance Levels

The BIP defines three conformance levels:

Level	Name	Status	Notes
1	Directory Protocol	✅ Required	Fully implemented
2	Interactive Protocol	✅ Optional	Fully implemented
3	Subscription Protocol	✅ Optional	Fully implemented

Core Method Compliance

Core Methods (MUST support for Level 1):

Method	Status	Location	Notes
onchain	✅	paykit-lib/src/methods/onchain.rs	BIP21-compatible
lightning	✅	paykit-lib/src/methods/lightning.rs	BOLT11 + LNURL support

Compliance Status by BIP Section

BIP Section	Implementation	Status	Notes
Preamble (BIP3)	N/A	✅	Compliant headers
Abstract	✅	Complete	Bitcoin-focused
Conformance Levels	✅	Complete	All levels implemented
Core Concepts	✅	Complete	z-base-32 identity encoding
Directory Protocol	✅	Complete	paykit-lib/src/transport/
Interactive Protocol	✅	Complete	paykit-interactive/
Noise_IK Pattern	✅	Complete	Required pattern, in paykit-interactive
Noise_XX Pattern	🔸	Available	Via pubky-noise crate; not directly exposed in paykit-interactive
Subscription Protocol	✅	Complete	paykit-subscriptions/
Payment Proofs	✅	Complete	paykit-interactive/src/proof/
Backward Compatibility	✅	Complete	BIP21, BOLT11, LNURL
Security Considerations	✅	Complete	All mitigations implemented
Test Vectors	🔸	Provided	bip-paykit/test-vectors.json (no automated verification yet)

Detailed Mapping

Directory Protocol (Level 1)

BIP Section: "Directory Protocol"
Implementation: paykit-lib/src/transport/

Feature	Status	Location
Path prefix /pub/paykit.app/v0/	✅	PAYKIT_PATH_PREFIX constant
Publish endpoints	✅	HomeserverSessionStorage::upsert_payment_endpoint
Discover endpoints	✅	HomeserverPublicStorageRead::fetch_payment_endpoint
List all methods	✅	HomeserverPublicStorageRead::fetch_supported_payments
Contact discovery	✅	HomeserverPublicStorageRead::fetch_known_contacts
Pubky integration	✅	paykit-lib/src/transport/pubky/
Endpoint rotation	✅	paykit-lib/src/rotation/

Compliance: ✅ Fully compliant

Interactive Protocol (Level 2)

BIP Section: "Interactive Protocol"
Implementation: paykit-interactive/

Feature	Status	Location
Noise_IK handshake (REQUIRED)	✅	PubkyNoiseChannel::connect
Noise_XX handshake (RECOMMENDED)	🔸	Available via pubky-noise crate
Cipher suite (25519_ChaChaPoly_BLAKE2s)	✅	pubky-noise
Length-prefixed framing	✅	PubkyNoiseChannel::send/receive
Max message size (1 MB)	✅	MAX_MESSAGE_SIZE constant
Max handshake size (64 KB)	✅	MAX_HANDSHAKE_SIZE constant
Message types	✅	PaykitNoiseMessage enum
Receipt exchange	✅	PaykitReceipt struct
Private endpoint sharing	✅	OfferPrivateEndpoint message

Compliance: ✅ Fully compliant (Noise_XX available but not directly wrapped)

Subscription Protocol (Level 3)

BIP Section: "Subscription Protocol"
Implementation: paykit-subscriptions/

Feature	Status	Location
Subscription agreement	✅	Subscription struct
Payment frequency	✅	PaymentFrequency enum
Cryptographic signatures	✅	signing.rs
Domain separation (PAYKIT_SUBSCRIPTION_V2)	✅	SUBSCRIPTION_DOMAIN constant
Deterministic serialization (postcard)	✅	hash_subscription_canonical
Replay protection (nonce + expiry)	✅	Signature struct
Payment requests	✅	PaymentRequest struct
Auto-pay rules	✅	paykit-subscriptions/src/autopay.rs
Spending limits	✅	paykit-subscriptions/src/autopay.rs, storage.rs

Compliance: ✅ Fully compliant

Implementation Note: BIP specifies migration to RFC 8785 JCS planned for v1.0.

Identity Encoding

BIP Section: "PublicKey"
Implementation: paykit-lib/src/lib.rs

Feature	Status	Location
z-base-32 encoding	✅	Via pubky crate
Pubky URI format	✅	paykit-lib/src/uri.rs
Ed25519 identity	✅	Via pubky crate

Compliance: ✅ Fully compliant

Cryptographic Primitives

BIP Section: bip-paykit/crypto.md
Implementation: Via pubky-noise crate

Feature	Status	Location
Ed25519 (identity)	✅	ed25519-dalek
X25519 (key exchange)	✅	x25519-dalek
ChaCha20-Poly1305 (Noise AEAD)	✅	chacha20poly1305
XChaCha20-Poly1305 (Sealed Blob v2)	✅	chacha20poly1305
BLAKE2s (Noise hash)	✅	blake2
SHA-256 (signatures)	✅	sha2
HKDF-SHA256	✅	hkdf

Compliance: ✅ Fully compliant

Payment Proofs

BIP Section: "Payment Proofs"
Implementation: paykit-interactive/src/proof/

Feature	Status	Location
Proof types	✅	PaymentProof enum
Bitcoin txid proof	✅	BitcoinTxidProof
Lightning preimage proof	✅	LightningPreimageProof

Compliance: ✅ Fully compliant

URI Parsing

BIP Section: "PublicKey" (URI format)
Implementation: paykit-lib/src/uri.rs

Feature	Status	Location
Pubky URI (pubky://)	✅	PaykitUri::Pubky
Lightning URI	✅	PaykitUri::Invoice
Bitcoin URI (BIP21)	✅	PaykitUri::Invoice
Payment request URI	✅	PaykitUri::PaymentRequest

Compliance: ✅ Fully compliant

Test Coverage

Unit Tests

• paykit-lib: 84 tests
• paykit-subscriptions: 82 tests
• paykit-interactive: 26 tests
• paykit-mobile: 28 tests

BIP Test Vectors

Test vectors are provided in bip-paykit/test-vectors.json. These vectors are intended for cross-implementation verification but are not yet consumed by an automated test harness in this repository.

Deviations and Notes

1. Serialization Format

BIP Note: Migration to RFC 8785 JCS planned for v1.0
Current: Postcard (deterministic binary)
Rationale: Postcard provides deterministic serialization. JCS migration will improve cross-language interoperability.

2. Noise_XX Pattern

BIP Requirement: Noise_XX RECOMMENDED for first contact
Status: 🔸 Available via pubky-noise crate
Note: paykit-interactive currently wraps Noise_IK only. Noise_XX is available in the underlying pubky-noise crate but not directly exposed via PubkyNoiseChannel.

3. File-based Storage Encryption

BIP Requirement: Encrypted file storage for private endpoints
Status: 🚧 Placeholder implemented
Rationale: Platform-specific storage (iOS Keychain, Android EncryptedSharedPreferences) is recommended.

4. Test Vector Verification

Status: 🚧 Not yet automated
Note: Test vectors in bip-paykit/test-vectors.json are provided for manual and cross-implementation verification. Automated verification tests are planned.

Implementation Completeness

Area	Completeness
Level 1: Directory	100% ✅
Level 2: Interactive	100% ✅
Level 3: Subscriptions	100% ✅
Crypto Primitives	100% ✅
Test Vectors	Provided 🔸
Mobile FFI	95% 🚧

Conclusion

The Paykit implementation is fully compliant with all three conformance levels defined in the BIP specification:

• Level 1 (Directory): ✅ Complete
• Level 2 (Interactive): ✅ Complete
• Level 3 (Subscriptions): ✅ Complete

Noise_XX is available via the underlying pubky-noise crate but not directly wrapped in paykit-interactive. Test vectors are provided but not yet verified by automated tests.