docs: codify paykit issuer contract

[ovitrif]

Closes #713

Description

Codifies the issuer contract Bitkit applies to one-time Paykit Payment Requests:

• documents exact lowercase asset, network-specific on-chain identifier, chain-independent Lightning identifier, and JSON endpoint payload requirements
• centralizes those production gates without changing their behavior
• adds a versioned cross-platform fixture covering P2TR, P2WPKH, P2SH, and P2PKH on Bitcoin, testnet, signet, and regtest, plus both Lightning identifiers on every network
• locks the fixture to production parsing with focused tests and explicit network injection
• adds the repeatable incoming-request journey and the accessibility identifiers it needs

Paykit protocol and SDK policy remain owned by Paykit.

Linked Issues/Tasks

• Closes docs: codify Paykit issuer interoperability #713
• Android mirror: docs: codify paykit issuer interoperability bitkit-android#1208

Preview

N/A — no user-visible changes.

QA Notes

Product journey / regtest evidence

• The source wallet-leg run completed the canonical regtest path on 2026-08-22: Bitkit presented the incoming request, opened the on-chain payment, broadcast it, and confirmed transaction cc85df0e24b54be353a57700429d144b35264c1af97f3de41c503dc52f1e4792 at height 77318.
• journeys/payment-requests/issuer-interoperability.xml records the repeatable path with a linked fixture issuer, exact request data, and stable accessibility identifiers.
• The canonical fixture locks 16 on-chain network/script pairs, both Lightning identifiers on every network, lowercase btc, and a JSON object endpoint payload containing a non-empty string value.

Automated checks

• Paykit issuer, public endpoint, and payment-request suites: 68 passed, 0 failed, 0 skipped.
• Standard iOS Simulator build passed with XcodeBuildMCP.
• SwiftFormat lint passed for all changed Swift files.
• Canonical JSON fixture and journey XML parse successfully.
• git diff --check passed.

[greptile-apps]

Greptile Summary

The PR codifies Bitkit’s existing one-time Paykit issuer contract without changing production parsing behavior.

• Centralizes Bitcoin asset, endpoint-identifier, and endpoint-payload validation.
• Adds a versioned interoperability fixture and production-path tests across all supported networks.
• Documents issuer requirements and adds a repeatable incoming-request journey with stable accessibility identifiers.

Confidence Score: 5/5

The PR appears safe to merge because the production changes preserve existing validation behavior while adding focused contract coverage and documentation.

Production callers continue to use the same environment network and parsing rules, the new files are automatically included through synchronized Xcode groups, and no concrete changed-code failure remains.

Important Files Changed

Filename	Overview
Bitkit/Services/PaykitIssuerInterop.swift	Centralizes the existing asset, network-aware endpoint filtering, deduplication, and JSON payload parsing behavior.
Bitkit/Services/PaykitPaymentRequestService.swift	Uses the centralized issuer contract while retaining Env.network as the production default.
Bitkit/Services/PublicPaykitService.swift	Delegates endpoint payload parsing to the shared interop helper without changing the resulting endpoint shape.
Bitkit/Views/PaymentRequests/PaymentRequestsView.swift	Adds stable accessibility identifiers directly to actionable Pay and Reject buttons.
Bitkit/Views/Wallets/Send/SendConfirmationView.swift	Distinguishes ordinary and payment-request confirmation screens in the accessibility tree while preserving child elements.
BitkitTests/PaykitIssuerInteropTests.swift	Exercises the production request and endpoint parsers against the versioned cross-platform fixture.
BitkitTests/Fixtures/paykit-issuer-interoperability.json	Defines accepted and rejected issuer-contract cases for Bitcoin, testnet, signet, and regtest.
Docs/paykit-issuer-interoperability.md	Documents the exact request terms, endpoint identifiers, payload shape, and delivery prerequisites enforced by Bitkit.
journeys/payment-requests/issuer-interoperability.xml	Records the repeatable regtest journey from incoming request presentation to payment confirmation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Issuer Payment Request] --> B[Validate btc asset and one-time terms]
    B --> C[Filter endpoint identifiers for wallet network]
    C --> D[Present incoming request]
    D --> E[Resolve JSON endpoint payload]
    E --> F[Open send confirmation]
    F --> G[Pay or reject request]

Loading

_{Reviews (1): Last reviewed commit: "docs: codify Paykit issuer contract (#71..." | Re-trigger Greptile}