# hathornetwork/hathor-wallet-lib architecture

> Architecture diagram of the GitHub repository hathornetwork/hathor-wallet-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hathornetwork/hathor-wallet-lib
- Repository: https://github.com/hathornetwork/hathor-wallet-lib

## Overview

Hathor Wallet Library is a client-side SDK for managing Hathor wallets and transactions. Its principal workflow is to configure a network and persistent storage, create/use a wallet, synchronize wallet state, construct and sign transactions, then submit them through API clients. The repository also includes shielded-address processing, Nano Contract parsing, token/transaction primitives, and wallet/swap service integrations. The README documents storage as a required setup step; some subsystem paths and connections are supported only by the source index, not sampled implementation excerpts.

Main entry points: [`src/new/wallet.ts`](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/wallet.ts) (Wallet API), [`src/new/sendTransaction.ts`](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/sendTransaction.ts) (Transaction creation), [`src/utils/storage.ts`](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/storage.ts) (Wallet scanning), [`src/wallet/sendTransactionWalletService.ts`](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/wallet/sendTransactionWalletService.ts) (Wallet-service sending)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wallet["Wallet lifecycle"]
  node_config["Network configuration<br/>[config.ts]"]
  node_wallet["Wallet API<br/>[wallet.ts]"]
end

subgraph group_transactions["Transaction lifecycle"]
  node_txbuild["Transaction creation<br/>[sendTransaction.ts]"]
  node_walletsend["Wallet-service sending"]
  node_txmodel["Transaction model<br/>[transaction.ts]"]
  node_txutils["Transaction operations<br/>[transaction.ts]"]
end

subgraph group_protocol["Protocol features"]
  node_address["Address model<br/>[address.ts]"]
  node_addressutil["Address derivation<br/>[address.ts]"]
  node_tokens["Token operations<br/>[tokens.ts]"]
  node_headers["Transaction headers<br/>[parser.ts]"]
  node_shielded["Shielded processing<br/>[processing.ts]"]
  node_nano["Nano Contract parsing<br/>[parser.ts]"]
end

subgraph group_connectivity["Network connectivity"]
  node_connection["Wallet connection<br/>[connection.ts]"]
  node_sync["Wallet synchronization<br/>[stream.ts]"]
  node_websocket["WebSocket client<br/>[index.ts]"]
  node_txapi["Transaction API<br/>[txApi.ts]"]
  node_walletapi["Wallet API client<br/>[wallet.ts]"]
  node_swap["Swap service<br/>[swapService.ts]"]
end

subgraph group_persistence["Wallet state"]
  node_storage[("Wallet storage<br/>[storage.ts]")]
  node_storageutil["Wallet scanning<br/>[storage.ts]"]
end

node_developer(("SDK caller"))
node_external(("Hathor node and services"))

node_developer -->|"configures"| node_config
node_developer -->|"uses"| node_wallet
node_wallet -->|"reads settings"| node_config
node_wallet -->|"opens connection"| node_connection
node_connection -->|"uses"| node_websocket
node_connection -->|"coordinates"| node_sync
node_wallet -->|"creates transactions"| node_txbuild
node_wallet -->|"delegates sending"| node_walletsend
node_txbuild -->|"submits transactions"| node_txapi
node_txbuild -->|"builds"| node_txmodel
node_txbuild -->|"uses transaction operations"| node_txutils
node_walletsend -.->|"uses transaction API"| node_txapi
node_walletsend -->|"uses transaction model"| node_txmodel
node_txmodel -->|"parses headers"| node_headers
node_wallet -->|"persists wallet state"| node_storage
node_storageutil -->|"fetches address history"| node_walletapi
node_storageutil -->|"derives addresses"| node_addressutil
node_storageutil -->|"processes outputs"| node_shielded
node_wallet -->|"uses token operations"| node_tokens
node_txbuild -->|"uses address model"| node_address
node_txbuild -->|"uses token operations"| node_tokens
node_wallet -->|"uses wallet API"| node_walletapi
node_wallet -.->|"supports shielded features"| node_shielded
node_wallet -.->|"supports Nano Contracts"| node_nano
node_wallet -.->|"supports swaps"| node_swap
node_txapi -.->|"requests node data"| node_external
node_walletapi -.->|"requests wallet data"| node_external
node_swap -.->|"connects to service"| node_external

click node_config "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/config.ts"
click node_wallet "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/wallet.ts"
click node_connection "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/connection.ts"
click node_sync "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/sync/stream.ts"
click node_websocket "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/websocket/index.ts"
click node_txbuild "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/sendTransaction.ts"
click node_walletsend "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/wallet/sendTransactionWalletService.ts"
click node_txmodel "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/models/transaction.ts"
click node_txutils "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/transaction.ts"
click node_txapi "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/api/txApi.ts"
click node_walletapi "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/api/wallet.ts"
click node_storage "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/storage/storage.ts"
click node_storageutil "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/storage.ts"
click node_address "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/models/address.ts"
click node_addressutil "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/address.ts"
click node_tokens "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/tokens.ts"
click node_headers "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/headers/parser.ts"
click node_shielded "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/shielded/processing.ts"
click node_nano "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/nano_contracts/parser.ts"
click node_swap "https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/wallet/api/swapService.ts"

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_config,node_wallet toneBlue
class node_txbuild,node_walletsend,node_txmodel,node_txutils toneAmber
class node_address,node_addressutil,node_tokens,node_headers,node_shielded,node_nano toneMint
class node_connection,node_sync,node_websocket,node_txapi,node_walletapi,node_swap toneRose
class node_storage,node_storageutil,node_developer,node_external toneIndigo
```

## Components

### Wallet lifecycle

- [Network configuration](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/config.ts): `src/config.ts`
- [Wallet API](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/wallet.ts): `src/new/wallet.ts`

### Transaction lifecycle

- [Transaction creation](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/sendTransaction.ts): `src/new/sendTransaction.ts`
- [Wallet-service sending](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/wallet/sendTransactionWalletService.ts): `src/wallet/sendTransactionWalletService.ts`
- [Transaction model](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/models/transaction.ts): `src/models/transaction.ts`
- [Transaction operations](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/transaction.ts): `src/utils/transaction.ts`

### Protocol features

- [Address model](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/models/address.ts): `src/models/address.ts`
- [Address derivation](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/address.ts): `src/utils/address.ts`
- [Token operations](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/tokens.ts): `src/utils/tokens.ts`
- [Transaction headers](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/headers/parser.ts): `src/headers/parser.ts`
- [Shielded processing](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/shielded/processing.ts): `src/shielded/processing.ts`
- [Nano Contract parsing](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/nano_contracts/parser.ts): `src/nano_contracts/parser.ts`

### Network connectivity

- [Wallet connection](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/new/connection.ts): `src/new/connection.ts`
- [Wallet synchronization](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/sync/stream.ts): `src/sync/stream.ts`
- [WebSocket client](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/websocket/index.ts): `src/websocket/index.ts`
- [Transaction API](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/api/txApi.ts): `src/api/txApi.ts`
- [Wallet API client](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/api/wallet.ts): `src/api/wallet.ts`
- [Swap service](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/wallet/api/swapService.ts): `src/wallet/api/swapService.ts`

### Wallet state

- [Wallet storage](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/storage/storage.ts): `src/storage/storage.ts`
- [Wallet scanning](https://github.com/hathornetwork/hathor-wallet-lib/blob/master/src/utils/storage.ts): `src/utils/storage.ts`

### Other components

- **SDK caller**
- **Hathor node and services**

## Connections

- SDK caller → Network configuration: configures
- SDK caller → Wallet API: uses
- Wallet API → Network configuration: reads settings (evidence: `src/new/wallet.ts`)
- Wallet API → Wallet connection: opens connection (evidence: `src/new/wallet.ts`)
- Wallet connection → WebSocket client: uses (evidence: `src/new/connection.ts`)
- Wallet connection → Wallet synchronization: coordinates (evidence: `src/new/connection.ts`)
- Wallet API → Transaction creation: creates transactions (evidence: `src/new/wallet.ts`)
- Wallet API → Wallet-service sending: delegates sending (evidence: `src/wallet/sendTransactionWalletService.ts`)
- Transaction creation → Transaction API: submits transactions (evidence: `src/new/sendTransaction.ts`)
- Transaction creation → Transaction model: builds (evidence: `src/new/sendTransaction.ts`)
- Transaction creation → Transaction operations: uses transaction operations (evidence: `src/new/sendTransaction.ts`)
- Wallet-service sending → Transaction API: uses transaction API
- Wallet-service sending → Transaction model: uses transaction model (evidence: `src/wallet/sendTransactionWalletService.ts`)
- Transaction model → Transaction headers: parses headers (evidence: `src/models/transaction.ts`)
- Wallet API → Wallet storage: persists wallet state (evidence: `src/new/wallet.ts`)
- Wallet scanning → Wallet API client: fetches address history (evidence: `src/utils/storage.ts`)
- Wallet scanning → Address derivation: derives addresses (evidence: `src/utils/storage.ts`)
- Wallet scanning → Shielded processing: processes outputs (evidence: `src/utils/storage.ts`)
- Wallet API → Token operations: uses token operations (evidence: `src/new/wallet.ts`)
- Transaction creation → Address model: uses address model (evidence: `src/new/sendTransaction.ts`)
- Transaction creation → Token operations: uses token operations (evidence: `src/new/sendTransaction.ts`)
- Wallet API → Wallet API client: uses wallet API (evidence: `src/new/wallet.ts`)
- Wallet API → Shielded processing: supports shielded features
- Wallet API → Nano Contract parsing: supports Nano Contracts
- Wallet API → Swap service: supports swaps
- Transaction API → Hathor node and services: requests node data
- Wallet API client → Hathor node and services: requests wallet data
- Swap service → Hathor node and services: connects to service
