HODLXXI Read Only

Universal Bitcoin Identity Layer

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/factory.py	Flask application, OAuth2/LNURL routes, Prometheus metrics, Socket.IO events, plus the factory-based app initialization
Security	app/security.py	Proxy/header fixes, HTTPS enforcement, Flask-Limiter setup, logging defaults
Identity tokens	app/tokens.py, app/jwks.py	RS256 JWT issuance, keypair persistence, JWKS publication
Storage	app/db_storage.py, app/database.py, app/storage.py	Postgres session helpers, Redis utilities, and in-memory parity for tests
Configuration	app/config.py	Typed env loader, production validation helpers
Observability	app/app.py, deployment/README.md	Prometheus counter wiring and deployment guidance

Further documentation lives in the app/ directory and supporting deployment guides under deployment/.

---

🧰 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

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.

• /.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:

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 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

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 - current product framing: HODLXXI as a Bitcoin-native trust runtime for public-key agents and services.

Agent Readiness

• HODLXXI Readiness Evaluation - current external evaluation path for public agent/runtime readiness.
• HODLXXI External Reviewer Packet - canonical public review packet for live reviewers, developers, investors, agent marketplace reviewers, and technical evaluators.
• Agent Readiness Report v1 - 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 — 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 explains which docs are current, historical, experimental, or archive candidates.
• AGENT_PROTOCOL.md for the signed discovery and job protocol
• TRUST_MODEL.md for the normative trust language and verification boundaries
• 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 and contribution guidelines.

Bug reports and feature proposals are welcome via GitHub Issues.

---

📄 License

Released under the MIT License.

Production readiness artifact storage

Persisted readiness self-scan reports are runtime artifacts, not source files. For hardened production deployments, set:

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.