# conduition/wos architecture

> Architecture diagram of the GitHub repository conduition/wos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conduition/wos
- Repository: https://github.com/conduition/wos

## Overview

wos is a Go client for Wallet of Satoshi’s custodial Bitcoin and Lightning REST API. The principal flow is to create or reopen a wallet, then use its read interface for account data and its signing interface for state-changing calls such as invoice creation and payment. The package also parses BOLT11 invoices and Lightning Addresses; the bundled bech32 implementation supports invoice decoding. Edges are limited to relationships visible in excerpts or the README; other documented capabilities are represented without guessed internal links.

Main entry points: [`reader.go`](https://github.com/conduition/wos/blob/main/reader.go) (Read-only access), [`wallet.go`](https://github.com/conduition/wos/blob/main/wallet.go) (Wallet lifecycle), [`signer.go`](https://github.com/conduition/wos/blob/main/signer.go) (Signer interface), [`bolt11.go`](https://github.com/conduition/wos/blob/main/bolt11.go) (BOLT11 amount parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wallet["Wallet access"]
  node_wallet["Wallet lifecycle<br/>[wallet.go]"]
  node_credentials["Credentials<br/>[wallet.go]"]
end

subgraph group_api["WoS API operations"]
  node_reader["Read-only access<br/>[reader.go]"]
  node_walletops["Wallet operations<br/>[wallet.go]"]
  node_account["Addresses and balances<br/>[reader.go]"]
  node_history["Payment history<br/>[reader.go]"]
  node_fees["Fee estimates<br/>[reader.go]"]
  node_invoices["Invoice creation<br/>[wallet.go]"]
  node_payments["Payment actions<br/>[wallet.go]"]
end

subgraph group_payment["Payment formats"]
  node_invoiceparse["BOLT11 amount parsing<br/>[bolt11.go]"]
  node_bech32["Bech32 codec<br/>[bech32.go]"]
  node_lnaddress["Lightning Address<br/>[lnaddress.go]"]
end

subgraph group_security["Signing"]
  node_signer["Signer interface<br/>[signer.go]"]
  node_simple["HMAC signer<br/>[signer.go]"]
end

node_caller(("Go client"))
node_wosapi(("WoS REST API"))
node_remote(("Remote signer"))
node_externalpay(("Lightning / Bitcoin networks"))

node_caller -->|"creates or opens"| node_wallet
node_wallet -->|"uses for reads"| node_reader
node_wallet -->|"uses for writes"| node_signer
node_credentials -->|"opens"| node_wallet
node_credentials -->|"provides token"| node_reader
node_credentials -->|"creates"| node_simple
node_wallet -->|"loads addresses"| node_account
node_reader -->|"fetches"| node_account
node_reader -->|"fetches"| node_history
node_reader -->|"fetches"| node_fees
node_walletops -->|"sends signed requests"| node_wosapi
node_reader -->|"sends GET requests"| node_wosapi
node_walletops -->|"creates"| node_invoices
node_walletops -->|"sends"| node_payments
node_walletops -->|"requests signature"| node_signer
node_simple -->|"implements"| node_signer
node_remote -->|"can implement"| node_signer
node_payments -->|"parses invoice amount"| node_invoiceparse
node_invoiceparse -->|"decodes invoice"| node_bech32
node_payments -->|"uses address URL"| node_lnaddress
node_payments -.->|"initiates payments"| node_externalpay
node_invoices -.->|"creates invoice"| node_wosapi

click node_wallet "https://github.com/conduition/wos/blob/main/wallet.go"
click node_reader "https://github.com/conduition/wos/blob/main/reader.go"
click node_walletops "https://github.com/conduition/wos/blob/main/wallet.go"
click node_credentials "https://github.com/conduition/wos/blob/main/wallet.go"
click node_signer "https://github.com/conduition/wos/blob/main/signer.go"
click node_simple "https://github.com/conduition/wos/blob/main/signer.go"
click node_account "https://github.com/conduition/wos/blob/main/reader.go"
click node_history "https://github.com/conduition/wos/blob/main/reader.go"
click node_fees "https://github.com/conduition/wos/blob/main/reader.go"
click node_invoices "https://github.com/conduition/wos/blob/main/wallet.go"
click node_payments "https://github.com/conduition/wos/blob/main/wallet.go"
click node_invoiceparse "https://github.com/conduition/wos/blob/main/bolt11.go"
click node_bech32 "https://github.com/conduition/wos/blob/main/bech32/bech32.go"
click node_lnaddress "https://github.com/conduition/wos/blob/main/lnaddress.go"

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_wallet,node_credentials,node_caller toneBlue
class node_reader,node_walletops,node_account,node_history,node_fees,node_invoices,node_payments toneAmber
class node_invoiceparse,node_bech32,node_lnaddress,node_wosapi toneMint
class node_signer,node_simple toneRose
class node_remote,node_externalpay toneIndigo
```

## Components

### Wallet access

- [Wallet lifecycle](https://github.com/conduition/wos/blob/main/wallet.go): `wallet.go`
- [Credentials](https://github.com/conduition/wos/blob/main/wallet.go): `wallet.go`

### WoS API operations

- [Read-only access](https://github.com/conduition/wos/blob/main/reader.go): `reader.go`
- [Wallet operations](https://github.com/conduition/wos/blob/main/wallet.go): `wallet.go`
- [Addresses and balances](https://github.com/conduition/wos/blob/main/reader.go): `reader.go`
- [Payment history](https://github.com/conduition/wos/blob/main/reader.go): `reader.go`
- [Fee estimates](https://github.com/conduition/wos/blob/main/reader.go): `reader.go`
- [Invoice creation](https://github.com/conduition/wos/blob/main/wallet.go): `wallet.go`
- [Payment actions](https://github.com/conduition/wos/blob/main/wallet.go): `wallet.go`

### Payment formats

- [BOLT11 amount parsing](https://github.com/conduition/wos/blob/main/bolt11.go): `bolt11.go`
- [Bech32 codec](https://github.com/conduition/wos/blob/main/bech32/bech32.go): `bech32/bech32.go`
- [Lightning Address](https://github.com/conduition/wos/blob/main/lnaddress.go): `lnaddress.go`

### Signing

- [Signer interface](https://github.com/conduition/wos/blob/main/signer.go): `signer.go`
- [HMAC signer](https://github.com/conduition/wos/blob/main/signer.go): `signer.go`

### Other components

- **Go client**
- **WoS REST API**
- **Remote signer**
- **Lightning / Bitcoin networks**

## Connections

- Go client → Wallet lifecycle: creates or opens (evidence: `README.md`)
- Wallet lifecycle → Read-only access: uses for reads (evidence: `wallet.go`)
- Wallet lifecycle → Signer interface: uses for writes (evidence: `wallet.go`)
- Credentials → Wallet lifecycle: opens (evidence: `wallet.go`)
- Credentials → Read-only access: provides token (evidence: `wallet.go`)
- Credentials → HMAC signer: creates (evidence: `wallet.go`)
- Wallet lifecycle → Addresses and balances: loads addresses (evidence: `wallet.go`)
- Read-only access → Addresses and balances: fetches (evidence: `reader.go`)
- Read-only access → Payment history: fetches (evidence: `reader.go`)
- Read-only access → Fee estimates: fetches (evidence: `reader.go`)
- Wallet operations → WoS REST API: sends signed requests (evidence: `wallet.go`)
- Read-only access → WoS REST API: sends GET requests (evidence: `reader.go`)
- Wallet operations → Invoice creation: creates (evidence: `README.md`)
- Wallet operations → Payment actions: sends (evidence: `README.md`)
- Wallet operations → Signer interface: requests signature (evidence: `wallet.go`)
- HMAC signer → Signer interface: implements (evidence: `signer.go`)
- Remote signer → Signer interface: can implement (evidence: `README.md`)
- Payment actions → BOLT11 amount parsing: parses invoice amount (evidence: `wallet.go`)
- BOLT11 amount parsing → Bech32 codec: decodes invoice (evidence: `bolt11.go`)
- Payment actions → Lightning Address: uses address URL (evidence: `wallet.go`)
- Payment actions → Lightning / Bitcoin networks: initiates payments
- Invoice creation → WoS REST API: creates invoice
