HODLXXI Read-Only
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Open source Repository Open in the app JSON README (API)
About
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- hodlxxi
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.1
- Open pull requests
- 6
- Last push
- 2026-09-07T22:41:08Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:07
- Updated
- 2026-08-29 04:00:07
- Origin id
io.github.hodlxxi/hodlxxi-readonly
README
# Universal Bitcoin Identity Layer [](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/pytest.yml) [](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/lint.yml) [](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/actions/workflows/security.yml) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/psf/black) A production-focused Flask service that bridges OAuth2/OpenID Connect with Lightning Network authentication. The project couples hardened security defaults, Redis-backed rate limiting, RS256 JWT issuance, and Postgres persistence so Bitcoin-enabled applications can expose standards-compliant identity endpoints. --- ## 🚀 Highlights - **Security-first OAuth2/OIDC core** – RS256 tokens with on-disk JWKS rotation, PKCE validation, HTTPS enforcement through `app.security`, and Redis-powered rate limiting with production fail-closed behavior and explicit non-production in-memory fallback warnings. - **Lightning-aware identity workflows** – LNURL-auth challenge storage, Bitcoin signature verification helpers, and adapters that keep the legacy authorization views working while the storage layer matured. - **Persistent storage** – SQLAlchemy models for OAuth clients/codes/tokens, sessions, LNURL challenges, proof-of-funds requests, and audit logs backed by Postgres with Redis coordination for ephemeral state. - **Operational tooling** – `/metrics/prometheus` endpoint, structured JSON logging, and a reusable `create_app()` factory (`app/factory.py`) for factory-based deployments. - **Typed configuration surface** – Environment-driven configuration validated by `app.config`, including production guardrails for secrets, Redis, and database connectivity. --- ## 🏗️ Architecture at a Glance | Layer | Key Modules | Responsibilities | | --- | --- | --- | | Web application | [`app/app.py`](app/app.py), [`app/factory.py`](app/factory.py) | Flask application, OAuth2/LNURL routes, Prometheus metrics, Socket.IO events, plus the factory-based app initialization | | Security | [`app/security.py`](app/security.py) | Proxy/header fixes, HTTPS enforcement, Flask-Limiter setup, logging defaults | | Identity tokens | [`app/tokens.py`](app/tokens.py), [`app/jwks.py`](app/jwks.py) | RS256 JWT issuance, keypair persistence, JWKS publication | | Storage | [`app/db_storage.py`](app/db_storage.py), [`app/database.py`](app/database.py), [`app/storage.py`](app/storage.py) | Postgres session helpers, Redis utilities, and in-memory parity for tests | | Configuration | [`app/config.py`](app/config.py) | Typed env loader, production validation helpers | | Observability | [`app/app.py`](app/app.py), [`deployment/README.md`](deployment/README.md) | Prometheus counter wiring and deployment guidance | Further documentation lives in the [`app/`](app/README.md) directory and supporting deployment guides under [`deployment/`](deployment/README.md). --- ## 🧰 Prerequisites - Python 3.10+ - Postgres 13+ - Redis 6+ - Bitcoin Core 24+ (for RPC-backed features) For local development you can omit Postgres/Redis by exporting `DATABASE_URL` and `REDIS_URL` pointing to ephemeral services (e.g. docker-compose) or by relying on the in-memory storage adapter for tests. --- ## 🏁 Quick Start ```bash python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt export FLASK_APP=app.app:app export FLASK_ENV=development export RPC_USER=bitcoinrpc export RPC_PASSWORD=change-me flask run ``` The service exposes: - `/.well-known/openid-configuration`, `/oauth/token`, `/oauth/authorize` For third-party login setup, see [Sign in with HODLXXI Integration Guide](docs/OIDC_INTEGRATION.md). - `/.well-known/agent.json`, `/agent/capabilities`, `/agent/capabilities/schema` - `/agent/skills`, `/agent/marketplace/listing`, `/agent/reputation`, `/agent/attestations` - `/lnurl/auth` LNURL challenge endpoints - `/metrics/prometheus` for Prometheus scrapers - `/health` basic liveness probe ### Docker Compose quick start If you want a production-like stack without installing Postgres/Redis/Bitcoin Core locally, use the bundled Compose file: ```bash cp env.example .env docker compose up --build ``` The Postgres, Redis, and Bitcoin services wait for health checks before the Flask app starts. Mounts for `./app`, `./logs`, and `./keys` ensure code edits and generated keys persist on the host. See `docs/DEV_ONBOARDING_CHECKLIST.md` for the full onboarding flow and smoke tests. See [`TESTING.md`](TESTING.md) for pytest, mypy, and linting guidance. --- ## ⚙️ Configuration Reference `app/config.py` documents every supported environment variable. Highlights include: - `JWT_ALGORITHM=RS256` to force asymmetric signing; JWKS files are stored in `JWKS_DIR`. - `RATE_LIMIT_ENABLED` / `RATE_LIMIT_DEFAULT` for limiter tuning. - `DATABASE_URL` or discrete `DB_*` variables for SQLAlchemy. - `REDIS_URL`/`REDIS_*` for rate limiting and challenge/session TTL handling. - `SOCKETIO_ASYNC_MODE` to pick a compatible backend (defaults to `eventlet` when available, otherwise falls back to `threading`). - `FORCE_HTTPS`, `SECURE_COOKIES`, and `CSRF_ENABLED` for deployment hardening. Run `python -m app.config` (or import `validate_config`) inside your deployment pipeline to fail fast on insecure production settings. --- ## 🧪 Testing ```bash pytest ``` Unit tests cover configuration parsing/validation along with storage adapters. Integration tests spin up the in-memory backend to exercise OAuth and LNURL flows without external services. --- ## Product Positioning - [Runtime Product Positioning](docs/RUNTIME_PRODUCT_POSITIONING.md) - current product framing: HODLXXI as a Bitcoin-native trust runtime for public-key agents and services. ## Agent Readiness - [HODLXXI Readiness Evaluation](docs/READINESS_EVALUATION.md) - current external evaluation path for public agent/runtime readiness. - [HODLXXI External Reviewer Packet](docs/EXTERNAL_REVIEWER_PACKET.md) - canonical public review packet for live reviewers, developers, investors, agent marketplace reviewers, and technical evaluators. - [Agent Readiness Report v1](docs/AGENT_READINESS_REPORT_V1.md) - contract for public agent/service readiness reports backed by receipts and attestations. - `GET /agent/readiness/self-scan` - public machine-readable self-scan report for the current HODLXXI runtime. It returns `schema`, `summary`, `checks`, `verification`, `report_sha256`, and current `receipt` / `attestation` status. ## Developer Quickstarts - [Agent Receipt Quickstart](docs/AGENT_RECEIPT_QUICKSTART.md) — external developer flow: discovery, paid job request, polling, receipt verification, attestations, and reputation. ## 🤖 Agent, Skills, and Marketplace Discovery The repository now exposes a coherent machine-readable agent surface: - `/.well-known/agent.json` for the public identity/discovery document - `/agent/capabilities` for the signed capabilities handshake - `/agent/capabilities/schema` for the canonical JSON Schema of that handshake - `/agent/skills` for first-class skill discovery sourced from `skills/public/` - `/agent/marketplace/listing` for normalized directory/marketplace ingestion For the protocol and trust model, see: - [`docs/DOCUMENTATION_MAP.md`](docs/DOCUMENTATION_MAP.md) explains which docs are current, historical, experimental, or archive candidates. - [`AGENT_PROTOCOL.md`](AGENT_PROTOCOL.md) for the signed discovery and job protocol - [`TRUST_MODEL.md`](TRUST_MODEL.md) for the normative trust language and verification boundaries - [`docs/AGENT_SURFACES.md`](docs/AGENT_SURFACES.md) for how the runtime discovery endpoints expose those claims The current agent surface is intentionally conservative: it exposes public-key identity, declared operator metadata, paid execution, signed receipts, and observable history, while treating time-locked capital and on-chain backing as optional trust anchors rather than verified runtime facts. ### Python SDK for agents Developers can start from the SDK index: - `docs/sdk/README.md` The SDK covers: - public discovery and agent job requests - Bitcoin-message auth challenge flow - Nostr auth challenge flow - receipt helpers - signing helpers with caller-provided signers Examples: - `examples/python/ping_agent.py` - `examples/python/auth_challenge_flow.py` - `examples/python/nostr_auth_challenge_flow.py` The SDK does not hold private keys. Applications bring their own wallet, hardware, Bitcoin Core, Nostr, or agent-runtime signer. --- ## 🤝 Contributing 1. Fork the repository and create a virtual environment. 2. Install dev dependencies with `pip install -r requirements-dev.txt`. 3. Run `pytest` before opening a pull request. 4. Follow the [code of conduct](CODE_OF_CONDUCT.md) and [contribution guidelines](CONTRIBUTING.md). Bug reports and feature proposals are welcome via [GitHub Issues](https://github.com/hodlxxi/Universal-Bitcoin-Identity-Layer/issues). --- ## 📄 License Released under the [MIT License](LICENSE). ### Production readiness artifact storage Persisted readiness self-scan reports are runtime artifacts, not source files. For hardened production deployments, set: ```text AGENT_READINESS_REPORT_DIR=/srv/ubid/runtime/agent_readiness_reports ``` For `hodlxxi.service`, this path should live under the writable runtime area and be owned by the service user.