pecan

Pecan

Processor and Ecash Console for Alternative Numeraires

A cash counter for a Cashu mint. It lets a mint issue ecash for a unit of your choice (a local currency, a voucher, a community token), settled in person: the wallet creates a quote, the teller matches it by the short code on the customer’s screen, cash changes hands, done.

One command on a Linux server (amd64/arm64)
curl -fsSL https://raw.githubusercontent.com/zeugmaster/pecan/main/install.sh | bash

Two pieces: a processor that plugs into a cdk mint over the stock payment-processor interface, and a web console — a match-first teller page plus an operator view with a live attachment checklist, an end-to-end self-test, and account management.

Install

Run the installer as your normal user with access to Docker, including rootless Docker. It installs into ~/pecan and links ~/.local/bin/mintctl. Root installs on Linux use /opt/pecan and /usr/local/bin/mintctl. Choose another location with --dir.

Make sure docker info works and Docker Compose v2 supports up --wait --wait-timeout. If needed, add the user CLI directory to your shell’s PATH:

export PATH="$HOME/.local/bin:$PATH"

The guided installer asks what this server should run:

  • Processor + a new mint — pick a unit and the mint’s hostname; the mint (official cashubtc/mintd image) is configured, connected, and verified by the time the installer finishes. Its seed is shown once — write it down.
  • Processor only — attach a mint you already run afterwards, in the console’s Mint tab. Pecan never touches that mint’s seed, database, or keysets; it verifies the attachment and says exactly what to fix.

Then choose how the server is reached: a domain with automatic HTTPS (have DNS A records ready — the installer shows exactly which), behind your own reverse proxy, or plain HTTP on a trusted LAN. The console forces a password change at the first sign-in. Every question has a flag twin for automation (mintctl install --help):

mintctl install --yes --with-mint --unit ora \
  --console-domain console.example.org --mint-domain mint.example.org

Rootless Docker may need host configuration to publish ports 80/443. You can use --behind-proxy with an existing reverse proxy, or --plain-http on a trusted LAN. --install-docker installs system Docker and requires root; set up rootless Docker separately. See the non-root setup guide.

If setup fails after configuration was saved, run ~/pecan/mintctl start (or the CLI in your chosen directory) to retry. Your generated password and mint seed stay in place; rerunning the installer refuses to replace them.

First steps

With a bundled mint: write down the seed, let the checklist confirm itself, add teller accounts in the Access tab. Attaching your own mint: set unit and mint URL in the Mint tab, apply the generated snippet to your mintd (cdk-mintd config apply), restart it, and watch the checklist settle green.

Day to day

mintctl status | logs | update | domain | backup | restore | start | stop | uninstall

Backups, restore drills, server migration, proxy setups, and bundled-mint operations live in docs/operations.md.

Updates

Pecan v0.3.1 adds staged updates with automatic backups. Choose whether to update the console and processor, the bundled mint, or both:

mintctl update --check               # preview a console update
mintctl update                       # console + processor; keep the mint pin
mintctl update --with-mint           # also use the release-tested mint
mintctl update --mint-version <tag>  # mint only; keep the console version

Add --version v0.3.1 to choose a Pecan release or --yes for unattended updates. You can preview both components with mintctl update --with-mint --check. The default preserves the mint version; --with-mint uses the mint version tested with the selected Pecan release. External mints use their own update tools.

The CLI shows the version changes and asks for confirmation. It downloads and validates the target deployment before changing live files, then briefly pauses running services for a consistent backup. It recreates the selected services and waits for their health checks to pass. A console-only update pauses the mint for the backup but preserves its container and version.

Backups and previous deployment files are saved privately under <install-dir>/updates/before-*/. With a bundled mint, the archive includes its database and seed. Store off-server copies encrypted. If startup fails, check mintctl logs and retry mintctl start; RECOVERY.txt in the backup directory explains how to restore the snapshot. Pecan never automatically downgrades a mint database. Restoring a snapshot discards activity since the backup.

If your existing CLI predates these options, run the bootstrap as the installation’s owner. Adjust MINTCTL_DIR to the existing directory; root installations normally use /opt/pecan:

curl -fsSL https://raw.githubusercontent.com/zeugmaster/pecan/main/install.sh \
  | MINTCTL_DIR="$HOME/pecan" bash -s -- update --with-mint

Pre-0.2 installations with a managed mint need the migration in the operations guide before updating. After changing a mint/processor pairing, check the console’s Mint tab to confirm the attachment.

Good to know

  • Needs cdk-mintd v0.18.0-rc.0 or later — the first release containing cashubtc/cdk#2295. The protocol is checked at connect time and the console names the required release. Wallet developers: docs/wallet-integration.md.
  • Deposits are only accepted on wallet-locked quotes (NUT-20), and every settlement is cross-checked with the mint first.
  • mintctl backup archives hold password hashes and the ticket ledger — and, with a bundled mint, its database and SEED. Store them encrypted.

Development

docker compose up --build from a checkout — console on http://localhost:9090 (demo admin/admin). Frontend in web/, processor in processor/, installer in mintctl/; CI tests every PR and publishes multi-arch images to ghcr.io/zeugmaster/pecan. The upstream research and rescope record live in docs/.