webylib 0.2.1

Webcash HD wallet library — bearer e-cash with BIP32-style key derivation, SQLite storage, AES-256-GCM encryption, and full C FFI for cross-platform SDKs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# Architecture

## System Overview

Webcash is a **centralized electronic cash system** operated by Webcash LLC. The `webylib` library is a client-side wallet that communicates with the Webcash server to perform transactions. All transaction validation and double-spend prevention happens server-side.

```
┌──────────────────────────────────┐
│         Your Application         │
│  (Rust, Python, C#, Swift, Go)   │
├──────────────────────────────────┤
│            webylib               │
│  ┌────────┐  ┌───────────────┐   │
│  │ Wallet │  │  Server Client │  │
│  │ SQLite │  │  (reqwest/TLS) │  │
│  └────────┘  └───────────────┘   │
├──────────────────────────────────┤
│         FFI C ABI Layer          │
│   (cdylib / staticlib exports)   │
└──────────┬───────────────────────┘
           │ HTTPS (rustls)
           ▼
┌──────────────────────────────────┐
│      webcash.org (Webcash LLC)   │
│  - Transaction validation        │
│  - Double-spend prevention       │
│  - Mining difficulty control     │
│  - Monetary supply enforcement   │
└──────────────────────────────────┘
```

## Trust Model

- The Webcash server is the sole authority for transaction validity
- Client-side secrets are never sent to the server — only SHA256 hashes
- The server cannot see your balance or link your transactions
- Loss of the server means loss of the ability to transact (centralized risk)

## Wallet Architecture

### Storage

The wallet uses SQLite with WAL mode for crash-safe local storage:

| Table | Purpose |
|-------|---------|
| `unspent_outputs` | Secret webcash with amounts, spend status |
| `spent_hashes` | SHA256 hashes of spent secrets (audit trail) |
| `wallet_metadata` | Master secret, configuration key-value pairs |
| `walletdepths` | HD derivation depth per chain code |

### HD Key Derivation

Four chain codes partition the key space:

| Chain | Code | Purpose |
|-------|------|---------|
| RECEIVE | 0 | Incoming payments — ownership transfer |
| PAY | 1 | Outgoing payment outputs |
| CHANGE | 2 | Transaction change returned to wallet |
| MINING | 3 | Mining reward collection |

Derivation algorithm (matches Python reference exactly):

```
tag    = SHA256("webcashwalletv1")
secret = SHA256(tag || tag || master_secret || chain_code_be64 || depth_be64)
```

### Transaction Flow

**Insert (receive funds):**
1. Parse incoming `e{amount}:secret:{hex}` string
2. Derive new RECEIVE secret at current depth
3. Submit `replace` request: old secret → new secret
4. Server atomically invalidates old, creates new
5. Store new secret in wallet, increment depth

**Pay (send funds):**
1. Select unspent inputs covering the amount
2. Derive PAY secret for payment output
3. Derive CHANGE secret for remainder (if any)
4. Submit `replace` request: inputs → [payment, change]
5. Mark inputs spent, store change output

**Merge (consolidate):**
1. Select multiple small outputs
2. Generate single consolidated output
3. Submit `replace`: many inputs → one output
4. Reduces wallet fragmentation

### Server Client

The wallet owns a `Box<dyn ServerClientTrait>` — no global singletons. Each wallet instance creates its own HTTP client with connection pooling. The trait enables mock injection for testing.

Four server endpoints:
- `POST /api/v1/health_check` — Query spend status of outputs
- `POST /api/v1/replace` — Atomic webcash replacement (core transaction)
- `GET /api/v1/target` — Current mining difficulty and parameters
- `POST /api/v1/mining_report` — Submit proof-of-work solution

### Encryption

Two encryption layers available:

1. **Seed encryption** — Argon2 key derivation + AES-256-GCM wrapping of the 32-byte master secret
2. **Database encryption** — Full SQLite file encryption with password or biometric keys

All secret material implements `Zeroize + ZeroizeOnDrop`.