# CLAUDE.md — huje.socialvalue.OC-python.src

## What This Is
social-value — economic intelligence for sovereign AI agents. Creates its own Liquid wallet (via Breez SDK) for efficient micropayments. Lightning passports in/out, Liquid handles internal transfers at near-zero fees.

**It IS a wallet** (mnemonic = wallet). It is NOT connecting to an existing wallet. NWC connects to someone else's wallet. social-value IS one.

## Package
- **PyPI**: `social-value` (v0.1.0)
- **Import**: `from social_value import SocialValue`
- **ClawHub**: `social-value` (publish after PyPI)

## Key Files
- `src/social_value/wallet.py` — main SocialValue class
- `src/social_value/types.py` — frozen dataclasses (WalletState, TransferResult, etc.)
- `src/social_value/config.py` — SocialValueConfig with env var loading
- `tests/` — pytest suite (types, config, fee estimation)

## Conventions
- hatchling build system
- Python >=3.10, ruff linter (100 char lines)
- All dataclasses frozen, all collections tuples
- Version synced in: pyproject.toml, __init__.py, clawhub/metadata.json
- Use Johnny5/example.com in examples, not brand names
- Conventional commits, NO Co-Authored-By line

## Dependencies
- `breez-sdk-liquid>=0.11.0` — Breez SDK Liquid Python FFI bindings (creates Liquid wallet)

## Architecture
- `SocialValue` creates/loads a Liquid wallet from a BIP39 mnemonic via Breez SDK
- Internally holds L-BTC (Liquid Bitcoin, 1:1 pegged to BTC)
- Lightning interop via submarine swaps (bolt11 invoices in/out)
- Fee estimation available without connecting (static estimates)
- Context manager support (`with SocialValue(...) as wallet:`)
- Max balance safety cap via SOCIAL_VALUE_MAX_BALANCE

## Boundaries
- IS: its own Liquid wallet, self-custodial, Lightning gateway
- IS NOT: Lightning wallet, connection to existing wallet, Bitcoin on-chain wallet, exchange
- IS NOT: Spark (that's `breez-sdk-spark`, separate package, future backend option)

## TODO
- [ ] Build ccfx.com Liquid/Lightning/Bitcoin exchange integration
- [ ] ClawHub SKILL.md (entity-not-service framing)
- [ ] clawhub/metadata.json
- [ ] examples/basic_usage.py
- [ ] Integration tests with Breez testnet
- [ ] Spark backend (Phase 2 — when Breez SDK Spark matures)
