sovren-adapter

Overview ¶

Command sovren-adapter is the runnable reference adapter (contract: go-client-api.md §cmd/sovren-adapter): one binary hosting the scanner / withdrawals / sweeper / reconciler services plus the Prometheus and admin listeners. Services self-register via init() in their own files.

Usage:

sovren-adapter --config adapter.yaml <service ...|all>

Exit codes: 0 clean stop, 1 config error, 2 storage error, 3 chain-connectivity error at startup.

reconciler service (T069 — owned by the reconciliation track). Registered via init(); other services register from their own files, never this one.

One service, three responsibilities:

1. the data-model §8 reconciliation schedules — near-real-time per-tx, hourly wallet, daily full-address (+ business-layer section), with MANUAL runs served by the admin API (admin_controls.go);
2. the FR-044 node-disagreement monitor, when a secondary node is configured (nodes.secondary) — single-node deployments log the degradation and run without it;
3. the storage-mirroring metric gauge loop (T066): review-queue depth, open chain-review conditions, per-flow controls, deposit backlog and hot-wallet balances are read from the shared store here so no other service needs cross-file emission hooks.

`sovren-adapter all` runs scanner + withdrawals + sweeper + reconciler in one process over one shared store, one controls switchboard, and one metric registry (main.go builds a single Deps for every registered service).

sweeper service (T060 — owned by the sweeps track). Registered via init(); other services register from their own files, never this one.

Drives the data-model §7 sweep engine (go/sweeps): plan → prepare → broadcast → confirm, with the FR-051 `sweep_paused` control honored on every step and deferrals surfaced through the sovren_sweeps_deferred_total counter. Sweep thresholds come exclusively from adapter.yaml `sweeps:` (FR-038/FR-040); gas parameters are shared with the withdrawals section; the signer is the same configured signer kind (secrets via environment, see withdrawals_service.go).

withdrawals service — drives the data-model §5 withdrawal state machine (workflow + FR-035 broadcaster) and wires the configured signer kind (contracts/signer-interface.md §Remote signer transports).

One-MsgSend-per-transaction (FR-036) is enforced by construction: the workflow builds through tx.BuildMsgSend only, and the sign-doc summary derivation rejects any doc that carries more than one message.

Signer transport secrets never appear in adapter.yaml; they arrive via environment variables documented in docs/withdrawal-processing.md:

grpc-remote: SOVREN_SIGNER_TLS_CA_FILE / _TLS_CERT_FILE / _TLS_KEY_FILE
             / _TLS_SERVER_NAME (mTLS REQUIRED in production);
             SOVREN_SIGNER_ALLOW_INSECURE_DEV=true only off-mainnet
exec:        binary path from signer.endpoint
unsafe-local: SOVREN_SIGNER_UNSAFE=UNSAFE_TEST_ONLY +
             SOVREN_SIGNER_MNEMONIC (+ optional SOVREN_SIGNER_HD_PATH);
             refused when the manifest declares mainnet