Getting started
Overview
Evergreen reads the time-to-live on a Soroban contract’s ledger entries, tells you which one ends first, and can extend it. Everything on this page and under it describes behaviour that exists today: the command line and engine in the published package, and the account pages on this site.
What it does
Soroban keeps a contract’s state in ledger entries, and each one carries a time to live measured in ledgers. When it runs out the entry is archived — or, for temporary entries, deleted. An archived code entry stops the contract until something pays to restore it: the next invocation that lists it does so and is charged for it, and simulation is what puts it on that list. A deleted temporary entry is a loss, and no amount of XLM brings it back.
Evergreen is three things over that fact. A command line tool that reads a contract’s entries and reports what expires first. An engine that re-reads the entries you configure on a schedule and decides whether any of them need acting on. And a GitHub Action that fails a pull request when a contract is closer to expiry than you allow.
What it will not do
Four of these are enforced in code rather than promised in prose, and each one is documented where it is enforced.
| It will not | Where that is enforced |
|---|---|
| Write to any network but testnet | The config loader compares the network passphrase rather than trusting a label. Security |
| Submit anything you did not ask it to | extend simulates by default; submitting needs --submit, a named secret variable and a fee cap. extend |
| Read a secret from a file or an argument | Secrets are passed by environment variable name only. There is no .env auto-loading. |
| Claim a contract is healthy when it did not look | A scan reports what it read and names what it could not. Undetermined, unread, not found |
Four kinds of entry, and one that matters most
Most descriptions of Soroban storage name three kinds — instance, persistent and temporary. There is a fourth, and on a real bill it is usually the largest: the code entry, which holds the compiled Wasm and is shared by every contract deployed from it.
On guinea-pig A, one shared code entry is 8,116,648 of 8,264,289 stroops — 98% of the rent across all four of its entries. It is also the entry a single-contract scan cannot fully resolve, because the chain does not index reverse dependencies. How state archival works
Where to start
If you want to see it work, the quickstart is one command and needs no key and no account. If you want to know whether you can trust it, read the refusals above and then the exit codes — what a tool does when it cannot answer is more informative than what it prints when it can. An account is optional: what signing in does today says what the email sign-in, the wallet link and the watchlist do, and what they do not.
Package @evergreen-stellar/cli@0.2.0, published to npm and verified from a clean machine on 2026-09-25. Testnet only.
Next