Configuration
Fields, file paths, secret permissions, RPC quorum and validation.
This manual targets 0.1.0-beta.3. Read the source and availability policy before installing. Historical reports retain their original scope.
PPOps reads JSON from –config, default ./ppops.config.json. All relative storage and secret paths resolve against the configuration file’s directory, not the shell’s working directory. init writes portable relative secret paths.
Generate a config using init; the container example shows all deployment sections. config and secrets must be owner-owned regular files with no group/other permissions (0600 on Unix); directories should be 0700.
Sections
| Section | Required inputs and defaults |
|---|---|
| schemaVersion | 1 |
| server | host 127.0.0.1, port 8787, allowRemote false |
| network | RAILGUN name, chain ID, token address/symbol/decimals, RPC URLs, deployment block and finality |
| storage | Distinct SQLite, LevelDB, proving-artifact and wallet-state paths |
| secrets | Separate API token, merchant identity key, DB encryption key and viewing-key files; HMAC when using webhooks |
| scanner | intervalMs 30000; PPOI URLs; providerPollingIntervalMs 10000; rpcTimeoutMs 20000; maxRpcBlockLag 5 |
| webhook | Optional fixed destination; keyId; timeoutMs 10000, maxAttempts 12, baseRetryMs 5000, maxRetryMs 3600000 |
The Arbitrum profile enforces chain 42161, native USDC 0xaf88d065e77c8cc2239327c5edb3a432268e5831, symbol USDC and 6 decimals. It requires finalized-block finality, distinct RPC origins and at least one PPOI endpoint. Two origins must both agree; three allow a 2-of-3 majority. Distinct origins are checked mechanically; independent administration is the operator’s responsibility.
The operator selects providers and PPOI nodes. URLs can contain provider API credentials, so keep the configuration private. Remote PPOI/webhook URLs require HTTPS. Remote binding requires allowRemote: true and an appropriate network policy.
Scanning
finalizedRecheckSeconds defaults to 604800 (seven days). scanStallThresholdMs defaults to 1200000 (twenty minutes without a progress update). maxScanStalenessMs written by init is 900000 (fifteen minutes); without an explicit value, runtime uses the larger of fifteen minutes and three scan intervals.
A scan starts only after the preceding one finishes. The SDK’s active scan cannot be cancelled. Readiness requires a complete successful scan that has not become stale; configuration validation alone does not establish readiness.
Paths and secrets
Storage and secret paths must be distinct and non-overlapping. Changing a viewing key while reusing wallet state is an identity change and is rejected.
| File | What it authorizes |
|---|---|
| api-token | Calls to the private merchant API |
| merchant-signing-key | Merchant identity signatures, not RAILGUN spending |
| railgun-db-encryption-key | Opening the encrypted scan database |
| merchant.viewing-key | Viewing the receiver’s private history |
| webhook-hmac-key | Authenticating outbound events |
Use doctor –offline to identify the failing file by its configuration field. It never prints secret values. It checks file metadata and basic format; wallet decoding/import happens on startup. Use preflight for dependencies, then status to observe runtime readiness.
Configuration changes
Back up before changing identity or storage. Edit the private config, validate, preflight and restart. The daemon does not hot-reload secrets. For API/HMAC rotation and downtime planning, follow the runbook.