Documentation
¶
Overview ¶
Package upgrades is the ledger of every binary a gno.land network has run.
misc/deployments/<chain>/upgrades.json is the source of truth; UPGRADES.md next to it carries a table rendered from the JSON between two markers. This package owns the format: parsing, the invariants a replaying supervisor relies on, the rendering, and the check that the two files agree. The rules live in Go, tested, rather than in a shell script forked per chain.
The contract: a version runs the blocks from its own halt_height + 1 (1 for genesis) up to and including its successor's halt_height. Entries are in chain order: strictly increasing versions and strictly increasing halt heights. A rolling release — a PATCH that changes no consensus code, switched to whenever an operator likes — has no halt and bounds no range: it can serve the same blocks as the entry before it.
Index ¶
Constants ¶
const ( // LedgerFile and DocFile are the two files a deployment directory holds. LedgerFile = "upgrades.json" DocFile = "UPGRADES.md" // BeginMarker and EndMarker delimit the generated table inside DocFile. BeginMarker = "<!-- BEGIN GENERATED (gno.land/pkg/upgrades) -->" EndMarker = "<!-- END GENERATED -->" // SchemaVersion is the only format this package reads and writes. SchemaVersion = 1 )
Variables ¶
This section is empty.
Functions ¶
func ParseVersion ¶
ParseVersion normalises a release tag the way the node does (gno.land/pkg/gnoland.parseReleaseVersion): vMAJOR.MINOR.PATCH with an optional pre-release, build metadata dropped. The ledger only ever holds tags the node can order, because halt_min_version is compared with them.
Types ¶
type Entry ¶
type Entry struct {
Kind Kind `json:"kind"`
Version string `json:"version"`
Commit string `json:"commit"`
HaltHeight *int64 `json:"halt_height"`
HaltTime *time.Time `json:"halt_time"`
HaltMinVersion *string `json:"halt_min_version"`
Proposal *int64 `json:"proposal"`
Image Image `json:"image"`
Binaries map[string]string `json:"binaries"`
RanAs *string `json:"ran_as"`
Release string `json:"release"`
}
Entry is one binary the network ran. Pointer fields are null in the JSON until the fact they record has happened: the digest until CI built the image, the halt time until the halt, the proposal until it was created. Binaries is null by the same rule, until CI built the release; only the last entry may still be pending, and it is never an empty object, so a pending entry cannot pass for a built one with no downloads. The image digest is never filled in before the binaries. HaltMinVersion is null when the proposal set no floor; an empty string is refused, so "the gate was off" and "someone forgot" cannot be confused.
type Image ¶
Image is the gnoland container image for an entry: the tag operators pin, and the digest that tag resolved to when the ledger was written.
type Kind ¶
type Kind string
Kind says what an entry is: the genesis the chain started on, a coordinated upgrade that changed the binary at a halt height, or a rolling release that operators switch to at their convenience.
type Ledger ¶
type Ledger struct {
Schema string `json:"$schema,omitempty"`
SchemaVersion int `json:"schema_version"`
ChainID string `json:"chain_id"`
GenesisSHA256 string `json:"genesis_sha256"`
GenesisTime time.Time `json:"genesis_time"`
Upgrades []Entry `json:"upgrades"`
}
Ledger is one chain's upgrades.json.
func Parse ¶
Parse decodes a ledger. Unknown fields are an error: a misspelled field would otherwise vanish silently, which for a null-able field looks exactly like "pending".
func (*Ledger) BlockRanges ¶
BlockRanges is the contract made explicit: which version produced which blocks. Only the genesis and the coordinated upgrades open a range; a rolling release is attached to the range it was released into. The last range's To is 0 because the current version is still running.
func (*Ledger) Entry ¶
Entry returns the entry a release of v is recorded under: the entry for v itself, or else the last entry for the same final version. A chain that runs finals only, like mainnet, has no entry for a candidate; the entry for its final stands in, since a final is cut on its last candidate's commit.
func (*Ledger) Has ¶
Has reports whether the ledger has an entry for v, ignoring a pre-release suffix on either side (see Entry).
func (*Ledger) RenderTable ¶
RenderTable renders the Markdown table, markers included, with a readable word in every cell whose fact has not happened yet.
Source Files