Metadata-Version: 2.4
Name: bsv-brc
Version: 0.1.1
Summary: Python implementations of BSV BRC protocols — BRC-52 (identity certificates), BRC-94 (verifiable key linkage), BRC-105 (HTTP micropayments)
Project-URL: Repository, https://github.com/datamynt/bsv-brc-python
Project-URL: Issues, https://github.com/datamynt/bsv-brc-python/issues
License: Open BSV License
License-File: LICENSE
Keywords: 402,brc-105,brc-52,brc-94,bsv,certificates,identity,micropayments,schnorr,secp256k1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: bsv-sdk>=1.0.0
Requires-Dist: pycryptodomex>=3.19
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: starlette
Requires-Dist: starlette>=0.27; extra == 'starlette'
Description-Content-Type: text/markdown

# bsv-brc

Python implementations of [BSV BRC protocols](https://bsv.brc.dev).
The higher-level protocol companion to [py-sdk](https://github.com/bsv-blockchain/py-sdk) (`bsv-sdk` on PyPI).

While `bsv-sdk` handles transactions, keys, and SPV — `bsv-brc` implements the
protocol layer: identity certificates, verifiable key linkage, and HTTP micropayments.

| Package | BRC | What |
|---------|-----|------|
| `bsv_brc.brc052` | [BRC-42/43/52/53](https://bsv.brc.dev/peer-to-peer/0052) | Identity certificates, ECDH key derivation, AES-256-GCM |
| `bsv_brc.brc094` | [BRC-94](https://bsv.brc.dev/key-derivation/0094) | Verifiable ECDH shared secrets via Schnorr proof |
| `bsv_brc.brc105` | [BRC-105](https://bsv.brc.dev/payments/0105) | HTTP 402 micropayment middleware + client |

## Install

```bash
pip install bsv-brc
```

For Starlette/FastHTML middleware:

```bash
pip install "bsv-brc[starlette]"
```

## Quick examples

### BRC-105: Accept micropayments on any endpoint

```python
from starlette.applications import Starlette
from bsv_brc.brc105 import PaymentMiddleware, NonceManager, StaticPricing

nonce_manager = NonceManager(secret=b"your-server-secret")

async def verify_payment(payment, identity_key):
    # Call wallet.internalizeAction() or your own verification
    ...

app = Starlette(routes=[...])
app.add_middleware(
    PaymentMiddleware,
    nonce_manager=nonce_manager,
    pricing=StaticPricing(100),  # 100 satoshis per request
    verify_payment=verify_payment,
)
```

### BRC-94: Prove an ECDH shared secret without revealing private keys

```python
from bsv_brc.brc094 import generate_proof, verify_proof

# Prover side
shared_secret, R, S_prime, z = generate_proof(my_private_key, their_public_key)

# Verifier side — no private keys needed
is_valid = verify_proof(prover_public_key, counterparty_public_key, shared_secret, R, S_prime, z)
```

### BRC-52: Issue an identity certificate

```python
from bsv_brc.brc052 import issue, make_certificate_type

cert = issue(
    certifier_private_key=certifier_key,
    cert_type=make_certificate_type("example.com/identity/v1"),
    subject_key=subject_pubkey_hex,
    field_values={"email": "alice@example.com"},
    serial_number=serial,
    encrypted_field_keys=encrypted_keys_from_client,
)
```

## Roadmap

- [ ] BRC-103/104 — Mutual authentication (peer-to-peer + HTTP transport)
- [ ] BRC-108 — Identity-linked tokens
- [ ] BRC-88 — SHIP/SLAP overlay network sync
- [ ] BRC-101 — Extended overlay facilitators (WebSocket, auth+payment URLs)
- [ ] BRC-116 — Proof-of-Indexing Hash-to-Mint

## Development

```bash
git clone https://github.com/datamynt/bsv-brc-python.git
cd bsv-brc-python
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[starlette,dev]"
pytest -v  # 63 tests
```

## License

[Open BSV License](LICENSE)
