Metadata-Version: 2.4
Name: fluxwallet
Version: 2.1.0
Summary: A Wallet implementation for Flux
Author: David White
Author-email: David White <david@runonflux.io>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx>=0.24.1,<1
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: certifi>=2024.0.0
Requires-Dist: cryptography>=46.0.0,<48
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: coincurve>=21.0.0,<23
Requires-Dist: msgpack>=1.0.0
Requires-Dist: python-socketio[asyncio-client]>=5.16.1
Requires-Dist: qrcode>=8.2
Requires-Dist: typer>=0.24.1
Requires-Dist: keyring>=25.7.0
Requires-Dist: yarl>=1.0.0
Requires-Dist: lmdb>=2.1.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: fluxwallet-sapling>=0.1.0,<1 ; extra == 'shielded'
Requires-Python: >=3.13
Provides-Extra: shielded
Description-Content-Type: text/markdown

# fluxwallet

Python wallet library and CLI for the Flux blockchain with SSP 2-of-2 multisig co-signing support.

## Features

- **HD wallets** — BIP32/BIP44 key derivation with BIP39 mnemonic support
- **Multisig** — 2-of-2 (SSP) and m-of-n P2SH multisig wallets
- **SSP integration** — pair with SSP Key mobile app for 2FA transaction co-signing via relay
- **CLI** — full wallet management via `fluxwallet` command (typer + rich)
- **MCP server** — expose wallet operations to Claude Code and other MCP clients
- **Encrypted storage** — AES-256-GCM with Argon2id key derivation, OS keychain integration
- **Fully async** — async/await throughout, SQLAlchemy 2.0 with aiosqlite

## Installation

```bash
pip install fluxwallet
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add fluxwallet
```

Requires Python 3.13+.

## Quick Start

### CLI

```bash
# Generate a mnemonic
fluxwallet mnemonic

# Create a new wallet
fluxwallet wallet create my_wallet

# Restore a wallet from mnemonic (prompted)
fluxwallet wallet restore my_wallet

# Check balance
fluxwallet wallet balance my_wallet

# Get receive address
fluxwallet key address my_wallet

# Send a transaction
fluxwallet tx send my_wallet t1abc... 1.5

# List all wallets
fluxwallet wallet list
```

### Library

```python
import asyncio
from fluxwallet.db import Db
from fluxwallet.wallet import Wallet

async def main():
    await Db.start()
    w = await Wallet.create("my_wallet", network="flux")
    key = await w.new_key()
    print(key.address)

asyncio.run(main())
```

## SSP Multisig

Create a 2-of-2 multisig wallet paired with the [SSP Key](https://sspwallet.io) mobile app:

```bash
# Create and pair a new SSP wallet
fluxwallet ssp pair --new my_ssp

# Send (auto-detects SSP, waits for phone approval)
fluxwallet tx send my_ssp t1abc... 0.5

# Re-pair an existing wallet
fluxwallet ssp pair my_ssp
```

## Database Encryption

Private keys are encrypted at rest with AES-256-GCM. The encryption key is derived from your password via Argon2id and stored in your OS keychain.

```bash
# Encrypt the database (first time)
fluxwallet db setup

# Check encryption status
fluxwallet db info

# Change password
fluxwallet db change-password

# Export key for headless servers
fluxwallet db setup --export-key /path/to/keyfile

# Unlock on a headless server
fluxwallet --key-file /path/to/keyfile wallet list

# Or pipe the key via stdin
cat /path/to/keyfile | fluxwallet wallet list
```

Auto-unlock priority: stdin > key file > OS keychain.

### Platform support

| Platform | Keychain backend | Notes |
|----------|-----------------|-------|
| macOS | Keychain Access | Works out of the box |
| Windows | Credential Locker | Works out of the box |
| Linux (GNOME) | GNOME Keyring | Requires desktop session |
| Linux (KDE) | KWallet | Requires desktop session |
| Headless | Key file or stdin | `--key-file` or pipe |

## CLI Reference

```
fluxwallet
  wallet list|create|restore|info|rename|delete|balance|scan
  key    import|address|list|new
  tx     list|utxos|update|send|sweep
  ssp    pair|info
  db     info|setup|unlock|change-password
  mnemonic
```

Global options:
- `--key-file PATH` — path to encryption key file

## Examples

```bash
uv run python examples/wallet_demo.py       # Wallet creation and key generation
uv run python examples/mnemonic_demo.py      # BIP39 mnemonic generation
uv run python examples/keys_demo.py          # HD key derivation and multisig addresses
uv run python examples/multisig_demo.py      # 2-of-2 and 2-of-3 multisig wallets
uv run python examples/transaction_demo.py   # Transaction creation and signing
uv run python examples/encryption_demo.py    # Database encryption round-trip
uv run python examples/ssp_pair.py           # SSP Key pairing
uv run python examples/ssp_send.py           # SSP co-signed transaction
uv run python examples/wallet_balance.py     # Check balance and UTXOs
```

## Development

```bash
git clone https://github.com/MorningLightMountain713/fluxwallet.git
cd fluxwallet
uv sync
uv run pytest tests/
```

## License

MIT
