Engine
Configuration
One file, shared by the CLI and the engine so their behaviour cannot drift. Three of its properties are enforced by the loader rather than described in a comment.
The file
Copy evergreen.config.example.json to a private Testnet config as a starting shape for a dry run. Replace its placeholder contract and payer; the displayed example alone is not a ready-to-run selected-payer simulation. Add the payer's public sourceAccount and a decimal-string maxFeeStroops cap as shown in the engine setup guide. Keep secrets out of the file. Fields beginning with an underscore are documentation and are ignored.
What the loader enforces
These are not conventions. The loader validates them at the input boundary, so a bad config fails when it is read rather than when a bump tries to sign.
| Rule | Why |
|---|---|
| Omitted mode means dry-run | Live is an explicit opt-in. A config that forgot to say so does not submit. |
| Every contract’s payer must resolve | Checked when the file is read, not discovered mid-run with half the contracts already processed. |
| Only testnet | The passphrase is compared against the expected value. A label saying “testnet” proves nothing. |
| Secrets are named, never stored | A config carrying a secret key would be committed by someone, eventually. The loader rejects anything that looks like one. |
The fields
| Field | Meaning |
|---|---|
| network.rpcUrl | The Soroban RPC endpoint every read goes through. |
| network.networkPassphrase | Compared, not trusted. This is the mainnet guard. |
| defaults.warnBelowLedgers | The warning tier. 120,960 ledgers, about seven days. |
| defaults.bumpWhenRemainingLedgersBelow | The act-now tier. 17,280 ledgers, about one day. Inclusive. |
| defaults.extendToLedgers | How far an extension reaches. 518,400 ledgers, about thirty days. |
| contracts[] | An id, a label used in logs and alerts, and which payer funds its extensions. |
| payers.<name>.signer | The signer kind. ed25519 is the implemented one. Security |
| payers.<name>.secretEnvVar | The NAME of an environment variable. Never the secret. |
| notifications.channel | Email. Notifications |
| notifications.toEnvVar | The name of the variable holding the recipient. |
| mode | dry-run or live. Omitted means dry-run. |
Adding a contract safely
Adding an entry to contracts does not extend anything by itself — the engine correctly does nothing until a threshold is crossed. A mismatched threshold can still cause an unexpected decision. Use only a contract and Testnet fee account you control; run pnpm engine:execute --config PATH --dry-run and inspect its decisions, preview, liveness and fee diagnostics. Neither a quiet dry run nor an exit code authorizes a write. Live execution is a separate, bounded local operator procedure in the setup guide; no unattended live-submission workflow is shipped.
Next