# urriki1502/wam-silent-payments architecture

> Architecture diagram of the GitHub repository urriki1502/wam-silent-payments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urriki1502/wam-silent-payments
- Repository: https://github.com/urriki1502/wam-silent-payments

## Overview

WAM Silent Payments is a regtest-qualified wallet implementation for BIP-352 payment derivation, durable scanning, wallet accounting, recovery, and PSBTv2 offline signing. The principal flow is an application invoking the wallet API, which coordinates scanning and wallet operations against a validating node, persists state, and supports payment construction and signing. Separate recovery and ecosystem-adapter branches preserve documented product capabilities. Edges are limited to README statements and relationships visible in the supplied excerpts or SOURCE INDEX; some adapter wiring is documented but not shown in source excerpts.

Main entry points: [`src/wam_sp/api.py`](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/api.py) (Wallet API), [`src/wam_sp/scanner.py`](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/scanner.py) (Durable scanner), [`src/wam_sp/wallet.py`](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/wallet.py) (Wallet accounting), [`src/wam_sp/backup.py`](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/backup.py) (Recovery bundles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wallet["Wallet workflow"]
  node_api["Wallet API<br/>[api.py]"]
  node_wallet_ops["Wallet accounting<br/>[wallet.py]"]
  node_scanner["Durable scanner<br/>[scanner.py]"]
  node_rpc["Node RPC<br/>[rpc.py]"]
end

subgraph group_protocol["Payment protocol"]
  node_core["BIP-352 derivation<br/>[core.py]"]
  node_codec["Address codec<br/>[codec.py]"]
  node_transaction["Transaction utilities<br/>[transaction.py]"]
end

subgraph group_state["State and recovery"]
  node_store[("SQLite state<br/>[store.py]")]
  node_watcher["Scan journal<br/>[watcher.py]"]
  node_backup["Recovery bundles<br/>[backup.py]"]
  node_keystore["Key custody<br/>[keystore.py]"]
  node_descriptors["Wallet descriptors<br/>[descriptors.py]"]
end

subgraph group_integrations["Signing and integrations"]
  node_psbt["PSBTv2 signing<br/>[psbt.py]"]
  node_sp_psbt["Silent-payment PSBT<br/>[sp_psbt.py]"]
  node_psbt_document["PSBT document adapter<br/>[psbt_document.py]"]
  node_pay_adapter["Pay adapter<br/>[pay.py]"]
  node_sdk_adapter["WAM SDK adapter<br/>[sdk.py]"]
  node_watchtower_adapter["Watchtower adapter<br/>[watchtower.py]"]
  node_wam_sdk["WAM SDK<br/>[client.py]"]
end

node_application(("Application"))
node_node["Validating node"]

node_application -->|"calls"| node_api
node_api -->|"starts scans"| node_scanner
node_api -->|"exposes wallet"| node_wallet_ops
node_api -->|"backs up"| node_backup
node_api -->|"manages descriptors"| node_descriptors
node_api -->|"uses keys"| node_keystore
node_scanner -->|"reads blocks"| node_node
node_scanner -.->|"calls"| node_rpc
node_scanner -->|"derives matches"| node_core
node_scanner -->|"persists scan state"| node_store
node_scanner -.->|"uses journal"| node_watcher
node_core -->|"encodes addresses"| node_codec
node_wallet_ops -->|"derives payments"| node_core
node_wallet_ops -->|"uses scan results"| node_scanner
node_wallet_ops -->|"constructs spends"| node_psbt
node_wallet_ops -->|"uses keys"| node_keystore
node_backup -->|"exports state"| node_store
node_backup -->|"seals recovery"| node_keystore
node_backup -->|"restores scan state"| node_scanner
node_psbt -->|"verifies sender"| node_sp_psbt
node_psbt_document -->|"adapts maps"| node_sp_psbt
node_psbt_document -->|"uses transactions"| node_transaction
node_api -.->|"supports integration"| node_pay_adapter
node_api -.->|"supports integration"| node_sdk_adapter
node_api -.->|"supports integration"| node_watchtower_adapter
node_sdk_adapter -.->|"adapts SDK"| node_wam_sdk

click node_api "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/api.py"
click node_wallet_ops "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/wallet.py"
click node_scanner "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/scanner.py"
click node_rpc "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/rpc.py"
click node_core "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/core.py"
click node_codec "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/codec.py"
click node_transaction "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/transaction.py"
click node_store "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/store.py"
click node_watcher "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/watcher.py"
click node_backup "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/backup.py"
click node_keystore "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/keystore.py"
click node_descriptors "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/descriptors.py"
click node_psbt "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/psbt.py"
click node_sp_psbt "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/sp_psbt.py"
click node_psbt_document "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/psbt_document.py"
click node_pay_adapter "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/pay.py"
click node_sdk_adapter "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/sdk.py"
click node_watchtower_adapter "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/watchtower.py"
click node_wam_sdk "https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/integration-deps/wam-sdk/src/wam_sdk/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_wallet_ops,node_scanner,node_rpc toneBlue
class node_core,node_codec,node_transaction toneAmber
class node_store,node_watcher,node_backup,node_keystore,node_descriptors toneMint
class node_psbt,node_sp_psbt,node_psbt_document,node_pay_adapter,node_sdk_adapter,node_watchtower_adapter,node_wam_sdk toneRose
class node_application,node_node toneIndigo
```

## Components

### Wallet workflow

- [Wallet API](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/api.py): `src/wam_sp/api.py`
- [Wallet accounting](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/wallet.py): `src/wam_sp/wallet.py`
- [Durable scanner](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/scanner.py): `src/wam_sp/scanner.py`
- [Node RPC](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/rpc.py): `src/wam_sp/rpc.py`

### Payment protocol

- [BIP-352 derivation](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/core.py): `src/wam_sp/core.py`
- [Address codec](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/codec.py): `src/wam_sp/codec.py`
- [Transaction utilities](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/transaction.py): `src/wam_sp/transaction.py`

### State and recovery

- [SQLite state](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/store.py): `src/wam_sp/store.py`
- [Scan journal](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/watcher.py): `src/wam_sp/watcher.py`
- [Recovery bundles](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/backup.py): `src/wam_sp/backup.py`
- [Key custody](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/keystore.py): `src/wam_sp/keystore.py`
- [Wallet descriptors](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/descriptors.py): `src/wam_sp/descriptors.py`

### Signing and integrations

- [PSBTv2 signing](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/psbt.py): `src/wam_sp/psbt.py`
- [Silent-payment PSBT](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/sp_psbt.py): `src/wam_sp/adapters/sp_psbt.py`
- [PSBT document adapter](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/psbt_document.py): `src/wam_sp/adapters/psbt_document.py`
- [Pay adapter](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/pay.py): `src/wam_sp/adapters/pay.py`
- [WAM SDK adapter](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/sdk.py): `src/wam_sp/adapters/sdk.py`
- [Watchtower adapter](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/src/wam_sp/adapters/watchtower.py): `src/wam_sp/adapters/watchtower.py`
- [WAM SDK](https://github.com/urriki1502/wam-silent-payments/blob/feat/wsp1-v1.0/integration-deps/wam-sdk/src/wam_sdk/client.py): `integration-deps/wam-sdk/src/wam_sdk/client.py`

### Other components

- **Application**
- **Validating node**

## Connections

- Application → Wallet API: calls
- Wallet API → Durable scanner: starts scans (evidence: `src/wam_sp/api.py`)
- Wallet API → Wallet accounting: exposes wallet (evidence: `src/wam_sp/api.py`)
- Wallet API → Recovery bundles: backs up (evidence: `src/wam_sp/api.py`)
- Wallet API → Wallet descriptors: manages descriptors (evidence: `src/wam_sp/api.py`)
- Wallet API → Key custody: uses keys (evidence: `src/wam_sp/api.py`)
- Durable scanner → Validating node: reads blocks (evidence: `src/wam_sp/scanner.py`)
- Durable scanner → Node RPC: calls
- Durable scanner → BIP-352 derivation: derives matches (evidence: `src/wam_sp/scanner.py`)
- Durable scanner → SQLite state: persists scan state (evidence: `src/wam_sp/scanner.py`)
- Durable scanner → Scan journal: uses journal (evidence: `src/wam_sp/scanner.py`)
- BIP-352 derivation → Address codec: encodes addresses (evidence: `src/wam_sp/core.py`)
- Wallet accounting → BIP-352 derivation: derives payments (evidence: `src/wam_sp/wallet.py`)
- Wallet accounting → Durable scanner: uses scan results (evidence: `src/wam_sp/wallet.py`)
- Wallet accounting → PSBTv2 signing: constructs spends (evidence: `src/wam_sp/wallet.py`)
- Wallet accounting → Key custody: uses keys (evidence: `src/wam_sp/wallet.py`)
- Recovery bundles → SQLite state: exports state (evidence: `src/wam_sp/backup.py`)
- Recovery bundles → Key custody: seals recovery (evidence: `src/wam_sp/backup.py`)
- Recovery bundles → Durable scanner: restores scan state (evidence: `src/wam_sp/backup.py`)
- PSBTv2 signing → Silent-payment PSBT: verifies sender (evidence: `src/wam_sp/psbt.py`)
- PSBT document adapter → Silent-payment PSBT: adapts maps (evidence: `src/wam_sp/adapters/psbt_document.py`)
- PSBT document adapter → Transaction utilities: uses transactions (evidence: `src/wam_sp/adapters/psbt_document.py`)
- Wallet API → Pay adapter: supports integration
- Wallet API → WAM SDK adapter: supports integration
- Wallet API → Watchtower adapter: supports integration
- WAM SDK adapter → WAM SDK: adapts SDK