Getting Started

Install

git clone https://github.com/trbouma/clear.git
cd clear
poetry install --with dev,docs

Configure secrets

Generate independent development secrets:

export CLEAR_MASTER_SECRET="$(openssl rand -hex 32)"
export CLEAR_OPERATOR_TOKEN="$(openssl rand -hex 32)"
export CLEAR_ROOT_AUTHORITY_NPUB="npub..."
export CLEAR_MINT_URL="http://127.0.0.1:3339"
export CLEAR_CURRENCY_NAME="Clear Lab Credit Program"
export CLEAR_CURRENCY_ALIAS="Clear Lab Credits"
export CLEAR_CURRENCY_UNIT_ALIAS="credits"
export CLEAR_ROOT_API_URL="http://127.0.0.1:3339"

The master secret deterministically derives denomination keys and must remain local to the mint. When CLEAR_ROOT_AUTHORITY_NPUB is configured, it is also included in keyset derivation so a root authority change creates a new CMU. The operator token protects routine lab issuance and retirement actions and should be managed separately. The optional currency alias and unit alias are wallet-facing display hints for this CMU.

CLEAR_MINT_URL is the canonical URL advertised to wallets and encoded in tokens. CLEAR_ROOT_API_URL is the private connection used by clear-root, which rejects non-loopback URLs. A Docker deployment keeps this administrative connection on container loopback even when the public mint URL is behind a reverse proxy.

Start Clear

poetry run clear \
  --host 127.0.0.1 \
  --port 3339 \
  --database ./data/clear.sqlite3 \
  --currency-name "Example Credits"

Useful development paths:

• http://127.0.0.1:3339/
• http://127.0.0.1:3339/health
• http://127.0.0.1:3339/docs
• http://127.0.0.1:3339/v1/info
• http://127.0.0.1:3339/v1/keys

Root CLI

poetry run clear-root config \
  --currency-name "Clear Lab Credit Program" \
  --currency-alias "Clear Lab Credits" \
  --currency-unit-alias "credits" \
  --root-authority-npub "npub..."
poetry run clear-root info
poetry run clear-root issue 25 --memo "wallet circulation test"
poetry run clear-root wallet balance
poetry run clear-root withdraw 25 --memo "disbursement"
poetry run clear-root issue 5 --memo "immediate token" --to-token
poetry run clear-root address alice@example.com
poetry run clear-root send 5 alice@example.com --memo "address delivery"
poetry run clear-root redeem "cashuA..." --memo "returned from wallet"
poetry run clear-root summary

A Lightning-address or NIP-05 well-known response can advertise lab Clear delivery with a clear object. The current Safebox-compatible shape advertises NIP-59 delivery with inner kind 7379:

{
  "clear": {
    "alice": {
      "protocols": ["clear-token-transfer"],
      "transports": ["nip59"],
      "kinds": [7379],
      "mints": ["http://127.0.0.1:3339"],
      "units": ["cmu-0011223344556677"]
    }
  }
}

The mints and units arrays are optional restrictions. When omitted, the receiver advertises general Clear support and validates the mint, CMU, and keyset ids after decrypting the transfer.

Run checks

poetry run pytest
poetry run ruff check .
poetry run mkdocs build --strict

Clear reports the generated protocol unit and keyset identifiers at / and /v1/keys. Record them with the organization's issuance policy before issuing Mint Notes. The /v1/info response also includes a suggested wallet alias. Wallets may display it, but must still bind balances to the mint URL, CMU, and keyset id.

Warning

The target unit is cmu-<keyset-id> and is bound to the exact keyset. Changing the master secret, configured root authority npub, or denomination set creates a new keyset and a new CMU. Clear refuses to open an existing database when the configured keyset identity does not match.

Current implementation vocabulary

The running service reports cmu-<keyset-id>. Do not rewrite an existing database's unit or keyset identity by hand.