mail-grpc settings
Part of the configuration reference. Covers the
chain gateway’s own settings — the gRPC listen address, the mutual-TLS
[auth] section that decides who may call it, the fee-payer keypair, and
the alias enumeration index.
mail-grpc
Config file mail_grpc.toml (or MAIL_GRPC_CONFIG), env prefix
MAIL_GRPC. An empty or missing file is a runnable dev gateway: the
chain endpoint and the signing keypair fall back to the operator’s
Solana CLI config (~/.config/solana/cli/config.yml),1 exactly like
the sithbit CLI — a missing CLI config means the stock CLI defaults
(mainnet-beta). This replaced the legacy environment-only configuration
as a clean break: GRPC_SERVER_ADDRESS, DEFAULT_KEYPAIR, and the other
old names are no longer read — see the mail-grpc chapter
for the migration note. The one legacy name still honored is bare
JSON_RPC_URL, which overrides the endpoint for parity with the CLI (see
the json_rpc_url row below). Row markers follow the going-public
legend.
| Key | Default | Meaning |
|---|---|---|
bind_addr | "127.0.0.1:50051" | OPTIONAL on loopback. gRPC listen address. Loopback is the one address that runs unauthenticated; naming any other makes the whole [auth] section REQUIRED, and startup fails without it |
max_bounty_lamports | 100000000 (0.1 SOL) | Ceiling on a SendMail request’s bounty_lamports, which the gateway escrows from its own wallet; over-cap requests are refused with INVALID_ARGUMENT before anything reaches the chain. 0 refuses bountied sends outright. See the guardrails |
fee_payer_floor_lamports | 10000000 (0.01 SOL) | Balance below which the write RPCs are refused with UNAVAILABLE and /readyz reports not-ready, so a drained wallet is one honest refusal and an alert rather than every write failing a preflight at a time. The balance is sampled in the background (every 30 s), so the check costs no per-request round trip; a balance that has never been read successfully permits writes. 0 disables the floor |
json_rpc_url | (unset — Solana CLI config) | Solana RPC endpoint; unset falls back to the CLI config’s json_rpc_url. A bare JSON_RPC_URL environment variable overrides this (env > this key > CLI config), matching the sithbit CLI |
keypair | (unset — Solana CLI config) | The fee-payer/signing keypair, a key source: a keypair-file path (not the keypair content) or a cloud secret-manager secret holding the keypair JSON. Unset falls back to the CLI config’s keypair_path (~/.config/solana/id.json by default) |
alias_cache_seconds | 30 | TTL for the ResolveAlias cache (0 disables caching). Kept short because sold/transferred aliases must not resolve stale; when the alias indexer runs, marketplace events evict entries within its poll interval anyway |
[auth] cert | (unset) | REQUIRED when bind_addr is not loopback. PEM certificate chain for the mTLS listener — an Ed25519 certificate, because callers pin the gateway by the Ed25519 key in it (their gateway_key), not by a CA. A bare path reads a file; the table form fetches from a cloud secret manager (kind = "akv"/"asm"/"gsm"), like keypair |
[auth] key | (unset) | REQUIRED when bind_addr is not loopback. Private key matching cert, PEM. Same source forms |
[auth] authorized_keys | [] | REQUIRED when bind_addr is not loopback. Base58 Ed25519 public keys allowed to call — the same 32-byte transport identity the MX servers bind for SASL EXTERNAL. An empty list is not “allow all”: it is an incomplete section and startup is refused. One entry per calling process (sithbitd, a standalone smtp-server, account-api) so revocation and attribution are per-process; the four protocols inside sithbitd share one channel and therefore one key |
[alias_index] database | "alias_index.db" | SQLite path for the alias-enumeration index. Set explicitly empty to disable the indexer (ListAliases/ListSales then answer UNAVAILABLE) |
[alias_index] poll_seconds | 5 | How often the indexer polls for new alias transactions |
[health], [observability] | health on 127.0.0.1:8193 | The two shared sections above |
The callers’ half. Each calling process presents its own Ed25519
client certificate and pins the gateway’s key: sithbitd’s
[grpc.tls], the
standalone SMTP server’s
[grpc_tls], and account-api’s
[chain.grpc_tls] all take the same three settings —
cert, key, gateway_key — and the endpoint they dial becomes
https://. sithbit-console has no such table and reaches only an
unauthenticated (loopback) gateway.
The alias index is derived state: it backfills from chain history on an empty database, so the file needs no backup (see Monitoring and backups).
-
This is the same file (
~/.config/solana/cli/config.yml, same location on Windows too) the Solana CLI’s ownsolana configcommand reads and writes, if you already have it installed — see CLI Quickstart. ↩