ots-cvm

ContextVM server for creating and verifying OpenTimestamps-backed NIP-03 attestations for Nostr events.

Verification uses a public Bitcoin JSON-RPC API and does not require running a local Bitcoin node.

Run

Local development:

bun install
bun run dev

Easy deployment with the published image:

docker pull ghcr.io/contextvm-org/ots-cvm:latest
docker run --rm --env-file .env -v ./data:/app/data ghcr.io/contextvm-org/ots-cvm:latest

Docker:

docker compose up --build

Environment

Main environment variables:

• SERVER_PRIVATE_KEY: hex-encoded Nostr secret key used by the server
• RELAYS: comma-separated relay URLs for fetch and publish operations
• ATTESTATION_RELAYS: comma-separated relay URLs used specifically to publish NIP-03 attestation events
• BITCOIN_API_URL: Bitcoin JSON-RPC endpoint used by verification
• LOG_LEVEL: info or debug

Optional environment variables:

• SQLITE_PATH: SQLite database file path
• OTS_DATA_DIR: directory used for cached proof files
• OTS_PROOF_TTL_DAYS: retention window for proof artifacts written to OTS_DATA_DIR (default: 30)
• OTS_VERIFY_CACHE_DIR: directory used by Python verification upgrades to cache calendar responses
• OTS_VERIFY_CACHE_TTL_DAYS: retention window for verification cache files (default: 3)
• CLEANUP_INTERVAL_MINUTES: how often expired filesystem artifacts are removed (default: 1440, once per day)
• OTS_CALENDARS: comma-separated OpenTimestamps calendar URLs
• OTS_PYTHON_BIN: optional Python executable override for local host development only

Create a local .env file before starting the service:

cp .env.example .env

Then edit .env and set at least SERVER_PRIVATE_KEY.

Notes:

• SERVER_PRIVATE_KEY is the only variable you should treat as required for production.
• RELAYS, ATTESTATION_RELAYS, BITCOIN_API_URL, and LOG_LEVEL are optional because the app has defaults.
• .env.example contains the minimal starter template for local and Docker usage.
• docker-compose.yml already loads values from .env via env_file, so Docker deployments only need that file present next to the compose file.
• Proof and verification cache files are cleaned up automatically on startup and periodically afterwards using the configured TTL values.

Docker runtime

Docker bundles Bun, Python, and the OpenTimestamps dependencies. No extra Python setup is needed on the host.

docker compose up --build

To run the published image directly, pass the same variables with --env-file:

docker run --rm \
  --env-file .env \
  -v ./data:/app/data \
  ghcr.io/contextvm-org/ots-cvm:latest

The container persists runtime data in data/ and exposes logs through docker compose logs.

For Docker deployments, you normally do not need to set OTS_PYTHON_BIN.