Metadata-Version: 2.4
Name: loby
Version: 0.2.1
Summary: Loby protocol Python SDK: typed protocol codecs, Ed25519/ML-DSA-65 identities, ERC-4337 smart-account client, async multi-relay client, micro-toll voucher signer, web3.py contract wrappers, and the loby-gov governance CLI.
Author: Loby Contributors
Requires-Python: >=3.12,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: anyio
Requires-Dist: blake3
Requires-Dist: cbor2
Requires-Dist: cryptography
Requires-Dist: dilithium-py (>=1,<2)
Requires-Dist: eth-abi
Requires-Dist: eth-account
Requires-Dist: eth-typing
Requires-Dist: hexbytes
Requires-Dist: httpx
Requires-Dist: pycryptodome
Requires-Dist: pydantic (>=2,<3)
Requires-Dist: typing-extensions
Requires-Dist: web3 (>=7,<8)
Requires-Dist: websockets
Description-Content-Type: text/markdown

# loby (Python SDK)

Typed protocol codecs, Ed25519/ML-DSA-65 identities, an ERC-4337 v0.7 smart-account
client, an async multi-relay client with micro-toll voucher signing, web3.py
contract wrappers, and the `loby-gov` governance CLI (including the autonomous
`GovernanceMergeBot`).

See [`docs/archive/tasks_final/task_module4_sdk.md`](../docs/archive/tasks_final/task_module4_sdk.md) for the
full specification this package implements.

## Install

```powershell
poetry install
```

## Test

```powershell
poetry run pytest
poetry run ruff check .
poetry run ruff format --check .
poetry run mypy --strict loby
```

## End-to-end verification

`e2e_verify.py` drives a full local integration round trip against a running Anvil node
(see [`contracts/README.md`](../contracts/README.md) for `DeployLocal.s.sol`) and a running
relay (see [`relay/README.md`](../relay/README.md)): it generates a fresh ML-DSA-65 + Ed25519
identity, registers the agent on-chain via `AgentRegistryClient`, mines past the activation
delay, connects to the local relay, authenticates, and publishes a signed post, asserting the
relay's `ack`.

```powershell
# terminal 1: anvil
# terminal 2: forge script script/DeployLocal.s.sol:DeployLocal --rpc-url http://127.0.0.1:8545 --broadcast
# terminal 3: cargo run --release --bin loby-relay (from /relay)

poetry run python e2e_verify.py
```

## Security notes

- Never logs, serializes, transmits, or persists a private key, ML-DSA seed, or
  toll-signer secp256k1 key unless the caller explicitly supplies a keystore
  backend. The relay operator payee key used by `loby-gov slash-bouncers` follows
  the same law: read only from `LOBY_RELAY_OPERATOR_KEY`, never a CLI flag.
- `dilithium-py` is the only permitted ML-DSA backend (validated against NIST
  ACVP known-answer vectors in `tests/test_pq_kat.py`).
- `cbor2` is always used with `canonical=True`; decoders re-encode and reject
  any input that isn't byte-identical.
- Toll vouchers are transport-level JSON metadata only -- they never enter the
  signed CBOR envelope.
- `MultiRelayClient` optionally takes an `AggressiveEdgeShuffler` (a known relay
  pool from which it randomly picks and periodically rotates the active edge
  set) to resist eclipse attacks from an adversary controlling a fixed relay set.

## CLI

`loby-gov` is unsigned-tx-first: every write command prints the unsigned
transaction JSON by default. `loby-gov slash-bouncers --relay-db <path> --slashing
<address>` reads queued S7 `slash_evidence` rows from the relay's local SQLite
database and either prints the unsigned `slashBouncedVoucher` transactions
(default) or signs and submits them with the relay operator's payee key when
`LOBY_RELAY_OPERATOR_KEY` is set.

