CDK Signatory

ALPHA This library is in early development, the API will change and should be used with caution.

Signing utilities and a standalone gRPC signatory service for the Cashu Development Kit (CDK). The standalone service lets cdk-mintd use a remote signing process instead of keeping mint signing keys in the mint daemon process.

Components

This crate includes:

A Signatory trait for blind signing, proof verification, and keyset rotation
A database-backed signatory implementation
A gRPC client and server for remote signing
The signatory binary for running the standalone service

Installation

Add this to your Cargo.toml:

[dependencies]
cdk-signatory = "*"

Or build the standalone binary from this workspace:

cargo build --release -p cdk-signatory --bin signatory

Quick Start

The standalone binary uses SQLite by default. It stores its database and seed file in the work directory. If CDK_MINTD_MNEMONIC is set, that mnemonic is used as the seed. Otherwise, the binary reads <work-dir>/seed or creates a new mnemonic there on first start.

The gRPC server expects TLS files in the certs directory. The helper script creates the files needed by both the signatory server and cdk-mintd.

mkdir -p ~/.cdk-signatory
bash crates/cdk-signatory/generate_certs.sh ~/.cdk-signatory

cargo run -p cdk-signatory --bin signatory -- \
  --work-dir ~/.cdk-signatory \
  --certs ~/.cdk-signatory \
  --listen-addr 127.0.0.1 \
  --listen-port 15060 \
  --enable-logging \
  --log-level info

For a built release binary:

./target/release/signatory \
  --work-dir ~/.cdk-signatory \
  --certs ~/.cdk-signatory

Options

Show all CLI options:

cargo run -p cdk-signatory --bin signatory -- --help

Common options:

Option	Description	Default
`--work-dir`	Directory for the SQLite database and seed file	`~/.cdk-signatory`
`--certs`	Directory containing `server.pem`, `server.key`, and `ca.pem`	Same as `--work-dir`
`--listen-addr`	gRPC bind address	`127.0.0.1`
`--listen-port`	gRPC bind port	`15060`
`--units`	Supported unit in `name,input_fee_ppk,max_order` format	`sat,0,32`
`--enable-logging`	Enable tracing output	`false`
`--log-level`	Log level when logging is enabled	`debug`

--units can be repeated to support multiple units. max_order controls the generated powers-of-two amounts, from 2^0 through 2^(max_order - 1).

Configuration for cdk-mintd

Config File

Point cdk-mintd at the remote signatory with [signatory].enabled = true:

[signatory]
enabled = true
address = "127.0.0.1"
port = 15060
tls_dir = "/home/user/.cdk-signatory"
allow_insecure = false

tls_dir must contain ca.pem, client.pem, and client.key for the cdk-mintd gRPC client. The same directory created by generate_certs.sh can be used for both services.

Environment Variables

All cdk-mintd signatory configuration can also be set via environment variables:

Variable	Description	Required
`CDK_MINTD_SIGNATORY_ENABLED`	Enable the remote signatory client	Yes
`CDK_MINTD_SIGNATORY_ADDRESS`	Remote signatory address	No
`CDK_MINTD_SIGNATORY_PORT`	Remote signatory port	No
`CDK_MINTD_SIGNATORY_TLS_DIR`	Directory with client TLS files	Recommended
`CDK_MINTD_SIGNATORY_ALLOW_INSECURE`	Allow connecting without TLS	No

Example:

export CDK_MINTD_SIGNATORY_ENABLED=true
export CDK_MINTD_SIGNATORY_ADDRESS=127.0.0.1
export CDK_MINTD_SIGNATORY_PORT=15060
export CDK_MINTD_SIGNATORY_TLS_DIR="$HOME/.cdk-signatory"
cdk-mintd

Security Notes

Back up the seed file or set a stable CDK_MINTD_MNEMONIC; losing the seed loses access to the mint signing keys.
Keep server.key, client.key, and the seed file private.
Use TLS for remote deployments. allow_insecure = true should only be used for local testing.

License

This project is licensed under the MIT License.

cdk-signatory 0.18.0