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_MINT_SERVICE_NSEC="$(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. CLEAR_MINT_SERVICE_NSEC is the mint's Nostr communication identity. Clear stores only its derived npub in the database as an identity sentinel and refuses a missing or different key after that first binding. It remains separate from the root authority, treasurer identities, and Cashu signing keys. The service begins in the uncommissioned state. 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 "cashuB..." --memo "returned from wallet"
poetry run clear-root summary

Clear now emits cashuB (Cashu TokenV4) for issuance, withdrawals, and sends. Redemption accepts both cashuB and existing cashuA tokens, including the optional cashu: URI prefix. Existing wallet files need no migration. Receiving wallets must support TokenV4 and Clear's custom CMU units.

TokenV4 preserves the CMU unit string and full proof keyset IDs independently; it does not change the issuance or redemption policy. Abbreviated modern keyset IDs in incoming tokens are resolved through the configured mint's keyset list before retirement. Unknown or ambiguous IDs are rejected.

This upgrade adds token-format support, not an HTTP 402 acceptance endpoint or enforcement of optional spending conditions. Optional DLEQ and witness fields survive codec round trips; decoding alone does not verify them or establish that proofs are unspent.

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.