From f3f4eb46b86df734e73e0d8052baa3b4ca7f551f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 31 Oct 2026 18:40:55 +0000 Subject: [PATCH] docs: Sync documentation from node repository v0.6.0-rc.3 - Source: genlayerlabs/genlayer-node@v0.6.0-rc.3 - Version: v0.6.0-rc.3 - Total changes: 20 - Added: 1 files - Updated: 19 files - Deleted: 0 files --- content/validators/bradbury.yaml | 3 +- .../changelog/v0.2.0-testnet001.mdx | 8 +- .../changelog/v0.2.0-testnet007.mdx | 10 +- content/validators/changelog/v0.3.11.mdx | 8 +- content/validators/changelog/v0.4.0.mdx | 26 +-- content/validators/changelog/v0.4.4.mdx | 16 +- content/validators/changelog/v0.4.5.mdx | 12 +- content/validators/changelog/v0.5.0.mdx | 14 +- content/validators/changelog/v0.5.10.mdx | 12 +- content/validators/changelog/v0.5.2.mdx | 8 +- content/validators/changelog/v0.5.5.mdx | 8 +- content/validators/changelog/v0.5.7.mdx | 10 +- content/validators/changelog/v0.5.8.mdx | 12 +- content/validators/changelog/v0.5.9.mdx | 14 +- content/validators/changelog/v0.6.0-rc.3.mdx | 42 ++++ content/validators/config.yaml | 27 ++- .../validators/docker-compose-monitoring.yaml | 2 +- pages/api-references/genlayer-node.mdx | 199 +++++++++++++++-- .../genlayer-node/ops/health.mdx | 20 +- .../genlayer-node/ops/metrics.mdx | 113 +++++++++- .../genlayer-node/ops/snapshot.mdx | 66 +++++- pages/validators/changelog.mdx | 201 +++++++++++------- pages/validators/monitoring.mdx | 2 +- pages/validators/setup-guide.mdx | 33 ++- 24 files changed, 671 insertions(+), 195 deletions(-) create mode 100644 content/validators/changelog/v0.6.0-rc.3.mdx diff --git a/content/validators/bradbury.yaml b/content/validators/bradbury.yaml index 6265477d7..3e8de7c9f 100644 --- a/content/validators/bradbury.yaml +++ b/content/validators/bradbury.yaml @@ -12,7 +12,8 @@ rollup: # The WebSocket refuses a connection without an API key. The chain is # operated by Conduit: create a key at https://app.conduit.xyz/rpc-keys and # set it in the environment as - # GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY, never in these URLs or this file. + # GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY (or in the file that + # genlayerchainrpckeyfile names), never in these URLs or this file. # The node sends it in the X-AccessKey header on the RPC and WebSocket # connections. provider: "conduit" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. diff --git a/content/validators/changelog/v0.2.0-testnet001.mdx b/content/validators/changelog/v0.2.0-testnet001.mdx index 314da77ec..94edf44c9 100644 --- a/content/validators/changelog/v0.2.0-testnet001.mdx +++ b/content/validators/changelog/v0.2.0-testnet001.mdx @@ -4,12 +4,12 @@ - Updated genvm to v0.0.16 +### Misc + +- Updated module golang.org/x/net to v0.38.0 (security) + ### Bug fixes - Log level is no longer ignored - Revived trie dumping and enhanced logging - Always kill genvm modules - -### Misc - -- Updated module golang.org/x/net to v0.38.0 (security) diff --git a/content/validators/changelog/v0.2.0-testnet007.mdx b/content/validators/changelog/v0.2.0-testnet007.mdx index 5fd2ae32c..9da37418c 100644 --- a/content/validators/changelog/v0.2.0-testnet007.mdx +++ b/content/validators/changelog/v0.2.0-testnet007.mdx @@ -9,13 +9,13 @@ - Log file support for node - Ability to export private key in account command +### Misc + +- Updated module github.com/btcsuite/btcd to v0.24.2 (security) +- Improved sync speed on node startup + ### Bug fixes - Build info logs now display correctly - Fixed config relative path - Node now fails fast when accepted transaction processing fails - -### Misc - -- Updated module github.com/btcsuite/btcd to v0.24.2 (security) -- Improved sync speed on node startup diff --git a/content/validators/changelog/v0.3.11.mdx b/content/validators/changelog/v0.3.11.mdx index d6b4e1b79..f394f6160 100644 --- a/content/validators/changelog/v0.3.11.mdx +++ b/content/validators/changelog/v0.3.11.mdx @@ -4,10 +4,10 @@ - Add validator telemetry push monitoring -### Bug fixes - -- Validator banning on parallel transactions executions - ### Misc - Document health RPC endpoint + +### Bug fixes + +- Validator banning on parallel transactions executions diff --git a/content/validators/changelog/v0.4.0.mdx b/content/validators/changelog/v0.4.0.mdx index 98af64b62..ef017113a 100644 --- a/content/validators/changelog/v0.4.0.mdx +++ b/content/validators/changelog/v0.4.0.mdx @@ -33,6 +33,19 @@ - Store and expose genvm execution information - Add sign admin endpoint for genvm +### Misc + +- Simplify environment variable configuration using .env file +- Add environment variable override support for config values +- Update webdriver image to v0.0.9 +- Update RPC and WebSocket endpoints in config.yaml.example +- Correct status for validatorTimeout after appeal time window +- Validate presence of abigen in dependency check +- Rename environment validation functions for clarity +- Use cockroachdb errors package for error handling +- Remove wallet.yaml file handling +- Rename archive to full + ### Bug fixes - GenVM architecture on arm64 @@ -57,16 +70,3 @@ - Leader idleness - Accidental deadlock in genvm - Lazy validators commit order - -### Misc - -- Simplify environment variable configuration using .env file -- Add environment variable override support for config values -- Update webdriver image to v0.0.9 -- Update RPC and WebSocket endpoints in config.yaml.example -- Correct status for validatorTimeout after appeal time window -- Validate presence of abigen in dependency check -- Rename environment validation functions for clarity -- Use cockroachdb errors package for error handling -- Remove wallet.yaml file handling -- Rename archive to full diff --git a/content/validators/changelog/v0.4.4.mdx b/content/validators/changelog/v0.4.4.mdx index b9be3fc81..1f1d87301 100644 --- a/content/validators/changelog/v0.4.4.mdx +++ b/content/validators/changelog/v0.4.4.mdx @@ -6,6 +6,14 @@ - Refactor ZkSync client to split RPC and WSS connections for better reliability - Move storage writing to genvm for improved performance +### Misc + +- Fix signer for full nodes +- Improve logs for http servers +- Improve signer initialization for faster and more reliable transaction signing +- Add logs for previous activator on idleness checks +- Migrate zksync-go to go-ethereum + ### Bug fixes - Skip priming check for full nodes @@ -15,11 +23,3 @@ - Fix memory leak in consensus processing - Fix bug in latest transaction with effect calculation - Fix wallet mutex using read lock instead of write lock when unlocking accounts - -### Misc - -- Fix signer for full nodes -- Improve logs for http servers -- Improve signer initialization for faster and more reliable transaction signing -- Add logs for previous activator on idleness checks -- Migrate zksync-go to go-ethereum diff --git a/content/validators/changelog/v0.4.5.mdx b/content/validators/changelog/v0.4.5.mdx index bb4fe7923..46a0901ce 100644 --- a/content/validators/changelog/v0.4.5.mdx +++ b/content/validators/changelog/v0.4.5.mdx @@ -6,14 +6,14 @@ - Implement sync waiting mechanism to ensure GenVM has latest state before contract execution - Add `genlayer_node_info` Prometheus metric exposing node and protocol version -### Bug fixes - -- Add canPrime check to verify epoch state before validator priming, preventing priming when epochs are out of sync -- Return user-friendly error instead of system error when sync times out -- Fix genvm executor process handling - ### Misc - Improve GenVM logging with context-aware logger - Update health checker to use ZkSync connectivity checks - Increase default genvm permits to 8 in config.yaml.example + +### Bug fixes + +- Add canPrime check to verify epoch state before validator priming, preventing priming when epochs are out of sync +- Return user-friendly error instead of system error when sync times out +- Fix genvm executor process handling diff --git a/content/validators/changelog/v0.5.0.mdx b/content/validators/changelog/v0.5.0.mdx index 4e050d522..138f0e797 100644 --- a/content/validators/changelog/v0.5.0.mdx +++ b/content/validators/changelog/v0.5.0.mdx @@ -6,6 +6,13 @@ - Add gen_getContractCode endpoint - Return full VMResult data from gen_call +### Misc + +- Inject txID into context for automatic log propagation +- Enable validator idle reveal idleness +- Add profiling with pyroscope +- Fix to handle zksync local-node compatibility + ### Bug fixes - Check pending queue head before activation @@ -24,10 +31,3 @@ - Prevent panic on closing done channel during event processing - Handle new consensus ResultType - New behavior for finalizing epochs - -### Misc - -- Inject txID into context for automatic log propagation -- Enable validator idle reveal idleness -- Add profiling with pyroscope -- Fix to handle zksync local-node compatibility diff --git a/content/validators/changelog/v0.5.10.mdx b/content/validators/changelog/v0.5.10.mdx index 6c6d31198..ff08e45fd 100644 --- a/content/validators/changelog/v0.5.10.mdx +++ b/content/validators/changelog/v0.5.10.mdx @@ -4,6 +4,12 @@ - Resilient WS RPC for fallback path +### Misc + +- Label RPC metrics with provider +- Add chain nonce and desync gauges metrics +- Log timestamps after acquireTransaction + ### Bug fixes - Close activator-binding race @@ -16,9 +22,3 @@ - Make chain-submit buffer configurable and stop collapsing on short step_timeout - Add fault label to RPC error metric - Unwedge replay and filter sync - -### Misc - -- Label RPC metrics with provider -- Add chain nonce and desync gauges metrics -- Log timestamps after acquireTransaction diff --git a/content/validators/changelog/v0.5.2.mdx b/content/validators/changelog/v0.5.2.mdx index cedf8ea67..b567fbfa7 100644 --- a/content/validators/changelog/v0.5.2.mdx +++ b/content/validators/changelog/v0.5.2.mdx @@ -4,6 +4,10 @@ - Add recovery for missing TxData +### Misc + +- Use CtxLogger in HTTP handler constructors + ### Bug fixes - Invalidate timeout cache on SetTimeouts @@ -14,7 +18,3 @@ - Reject stale block in idle check - Increment leader revealed metric counter - Sync commit idle timeout with contract timestamps - -### Misc - -- Use CtxLogger in HTTP handler constructors diff --git a/content/validators/changelog/v0.5.5.mdx b/content/validators/changelog/v0.5.5.mdx index b8490ba2a..70451655f 100644 --- a/content/validators/changelog/v0.5.5.mdx +++ b/content/validators/changelog/v0.5.5.mdx @@ -6,6 +6,10 @@ - Add network label to logger and all metrics - Add metrics to rollup RPC transport and WebSocket +### Misc + +- Downgrade finalized-not-in-cache log to Debug + ### Bug fixes - Recover from cache miss on late lifecycle events @@ -14,7 +18,3 @@ - Raise gas bump ceiling and retries - Stuck nonce and finalize resilience - Patch GenVM dylib references on macOS during download - -### Misc - -- Downgrade finalized-not-in-cache log to Debug diff --git a/content/validators/changelog/v0.5.7.mdx b/content/validators/changelog/v0.5.7.mdx index 1c236df5d..ac0db023e 100644 --- a/content/validators/changelog/v0.5.7.mdx +++ b/content/validators/changelog/v0.5.7.mdx @@ -4,6 +4,11 @@ - Add LLM greyboxing with configurable chain order via YAML meta +### Misc + +- Include Alloy healthcheck script in release tarball +- Increase Alloy push intervals to 60s + ### Bug fixes - Use PendingAt for idle activator rotation @@ -11,8 +16,3 @@ - Restart sync pipeline after RPC failures - Suppress shutdown errors in watchers - Reduce FindAcceptanceBlock range to fit RPC limit - -### Misc - -- Include Alloy healthcheck script in release tarball -- Increase Alloy push intervals to 60s diff --git a/content/validators/changelog/v0.5.8.mdx b/content/validators/changelog/v0.5.8.mdx index 315318a5c..05c3a413d 100644 --- a/content/validators/changelog/v0.5.8.mdx +++ b/content/validators/changelog/v0.5.8.mdx @@ -6,6 +6,12 @@ - Add bounded sync wait for RPC readiness - Add per-IP per-method RPC rate limiting +### Misc + +- Consolidate genvm configs +- Add `gen_getTransactionStatus` docs +- Add `gen_syncing` API docs and clarify RPC config group vs method precedence + ### Bug fixes - Defer GenVM precompile to container startup to avoid AVX-512 incompatibility @@ -18,9 +24,3 @@ - Pass transaction value to GenVM - Standardize RPC error codes per EIP-1474 - Retry tx lookup for RPC indexing lag - -### Misc - -- Consolidate genvm configs -- Add `gen_getTransactionStatus` docs -- Add `gen_syncing` API docs and clarify RPC config group vs method precedence diff --git a/content/validators/changelog/v0.5.9.mdx b/content/validators/changelog/v0.5.9.mdx index ffb50fa0d..a24d11514 100644 --- a/content/validators/changelog/v0.5.9.mdx +++ b/content/validators/changelog/v0.5.9.mdx @@ -1,5 +1,12 @@ ## v0.5.9 +### Misc + +- Use RFC3339Nano for zerolog timestamps +- Extract encoding functions into dedicated encoding package +- Move consensus entity types to entities package +- Add gen_dbg_traceTransaction API doc + ### Bug fixes - Count real provider failures on SLA @@ -9,10 +16,3 @@ - Self-cancel stuck nonce on mempool replacement exhaustion - Prevent sync panic and self-dependency cycle during tx replay - Resume sync after WS reconnect - -### Misc - -- Use RFC3339Nano for zerolog timestamps -- Extract encoding functions into dedicated encoding package -- Move consensus entity types to entities package -- Add gen_dbg_traceTransaction API doc diff --git a/content/validators/changelog/v0.6.0-rc.3.mdx b/content/validators/changelog/v0.6.0-rc.3.mdx new file mode 100644 index 000000000..b6ad72a58 --- /dev/null +++ b/content/validators/changelog/v0.6.0-rc.3.mdx @@ -0,0 +1,42 @@ +## v0.6.0-rc.3 + +Before you upgrade, check the alert rules that read `/health`. The `chain.sync` reasons `sync_stalled` and `sync_feed_frozen` are gone: a node far behind that still syncs returns 200, and a sync that fails at the same block for 5 minutes returns 503 with reason `sync_blocked`. A self-stake below the minimum now sets `consensus.stake` to `warning` (HTTP 200), not 503. At its first start, this release moves the node's nonce ledger from `genvm.db` to `ops.db` (log line `moved the nonce ledger from genvm.db to ops.db`); if you then go back to v0.6.0-rc.2, that node does not start while a transaction it signed is still pending. + +### New features + +- `doctor` checks that the operator key unlocks when you give the node password (`--password` or `GENLAYERNODE_PASSWORD`, as for the node); without a password it shows a warning and does not fail +- `doctor --output json` writes one JSON document with a stable `code` and `action` for each finding, and exits `0` (start), `1` (blocked) or `2` (doctor could not run); the codes are in `docs/deploy/troubleshooting.md` +- Change the chain RPC key without a restart: put the key in a file and set `rollup.genlayerchainrpckeyfile` to its path; the node reads the file again at most every 30 s + - do not also set `GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY`: the node then does not start +- Contract-state pruning: set `node.state.enabled: true` to delete old contract-state versions behind finalized ones after `node.state.retention` (default `336h` of chain time); it is off by default, so the node keeps all history; read `docs/deploy/state-pruning.md` first +- The node makes fewer chain RPC calls: it keeps repeated transaction reads in memory and does no reorg check for blocks at or below the chain's `finalized` block + - the cache is on by default; its settings are under `consensus.transaction_cache` +- `genlayernode snapshot restore --datadir ` installs a `genvm` snapshot, and the node continues its sync after the snapshot block + - to take a snapshot at a known block, a full node can stop its sync at `consensus.sync_halt_block` and keep RPC and ops serving +- The RPC API answers `net_version` with the configured chain id + +### Misc + +- The node runs contracts through the WebSocket endpoint (`/ws`) of the GenVM manager, not its HTTP run API; a manager that you run yourself (`genvm.start_manager: false`) must serve that endpoint, as the shipped GenVM does +- Update the release image to Alpine 3.24.3, the Alloy image of the release compose file to v1.21.2, and `go-ethereum` to v1.17.10 + +### Bug fixes + +- A leader no longer gets a strike when the commit phase ends on a timeout with enough commits: the leader did not reveal in that case, and now it does +- A new validator whose self-stake is still a pending deposit no longer fails `doctor` or gets a 503 from `/health`: both show a warning (`VALIDATOR_STAKE_PENDING`, reason `self_stake_pending`) until the next epoch moves the deposit into the stake + - a self-stake below the minimum is a warning too, and `doctor` exits 0 +- `/health` no longer returns 503 for hours while a node far behind syncs from genesis; `chain.sync` is `unavailable` only when the sync fails at the same block for 5 minutes (`sync_blocked`) or cannot read the logs of a block (`sync_block_unreadable`) +- When the node cannot read a recent transaction of a contract from the chain, a GenVM or RPC read of that contract's latest state now fails, instead of giving an older state +- The nonce ledger of the transactions the node signed is now in `ops.db`, not `genvm.db`: a resync that deletes `genvm.db` no longer deletes it, and a `genvm` snapshot no longer carries it +- A start-up failure now logs its cause in `node.log` (`Failed to build dependencies`), and the error no longer says only `previously failed` +- `gen_dbg_traceTransaction` now reads all the fee inputs of a replayed transaction at its processing block; some came from the latest block +- Correct the API reference: the `directory` label of the `genlayer_node_disk_*` metrics is `genvm.db`, `ops.db`, `logs` or `keystore` + +### Removed + +- The node no longer renames a v0.5 `/genlayer.db` to `genvm.db` at start: it ignores that folder and syncs from genesis into a new `genvm.db`; you can delete the old folder + +### Security + +- Build with Go 1.26.10, which has the fix for `GO-2026-6809` in the standard library +- Update `labstack/echo` to v4.16.3 for `GHSA-246p-cpwv-v3jq` (a rate-limit bypass with a spoofed `X-Forwarded-For` header) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 0ff0edecd..beca9c680 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -3,7 +3,9 @@ rollup: genlayerchainrpcurl: "TODO: Set your GenLayer Chain HTTP RPC URL here" # GenLayer Chain RPC URL genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain WebSocket RPC URL here" # GenLayer Chain WebSocket URL # An API key of the RPC provider never goes in these URLs or in this file: - # set it in the environment as GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY. + # set it in the environment as GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY, + # or, for a key that changes while the node runs, in a file named here: + # genlayerchainrpckeyfile: "/run/secrets/genlayer-rpc/key" # The node sends it in this header (default X-AccessKey): # genlayerchainrpckeyheader: "X-AccessKey" provider: "TODO: Set your GenLayer Chain provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. @@ -14,8 +16,22 @@ consensus: manifestpath: "configs/node/protocol-manifest.json" # Trusted producer protocol manifest for this deployment: save your network's manifest (from its documentation) at this path; a dev-env deploy places its own here too. Relative paths resolve against the node root. A mismatch with consensusaddress is refused at startup. chainid: "" # DECIMAL chain id this deployment was made on (not hex, no leading zeros). Held independently of the manifest so a manifest describing another deployment is caught. # genesis: 47930 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. + # sync_halt_block: 20000 # Node-local, full mode only; stop replay exactly here and keep RPC/ops serving. Zero disables. # chain_submit_buffer: "30s" # (Optional) Slack reserved at the end of each consensus step to submit the resulting on-chain tx (commit vote, reveal vote, proposed receipt) before the slot closes. Tune to underlying settlement chain latency. Default 30s. # admissiontimeout: "15s" # (Optional) Bound on the startup deployment admission check. Never unbounded. Default 15s. + # Cache of repeated transaction reads; on by default. A value read at a finalized + # block cannot change; one read above it can be replaced by a reorg, so it is kept + # shorter, and a detected reorg empties the cache. Tune with the + # genlayer_node_transaction_read_cache_* metrics. + # transaction_cache: + # enabled: true + # settled_ttl: 15m # values read at or below the finalized block + # unsettled_ttl: 30s # snapshots read above it + # unsettled_long_ttl: 10m # fee states and history answers read above it + # max_snapshots: 1024 + # max_fee_states: 1024 + # max_history: 4096 + # preload_workers: 5 # sync filter history preloads reading the chain at a time # data directory datadir: "./data/node" # logging configuration @@ -193,6 +209,15 @@ node: # # output, so its size is contract-controlled. Over the cap, the field is # # truncated and the cut is marked in-band. 0 takes the default. # max_debug_field_bytes: 262144 # 256 KB per field + # Contract-state history pruning; off by default (archive node). Past the + # window (chain time) the node keeps only the finalized state, so reads at + # older blocks fail. The window is raised at run time to the sum of + # the phase timeouts times the maximum rounds. Irreversible: read + # docs/deploy/state-pruning.md before enabling. + # state: + # enabled: false + # retention: 336h # two weeks + # sweep_interval: 10m # how often aged-out history is scheduled for pruning # genvm configuration genvm: root_dir: ./opt/genvm/v0.6.0-rc10 diff --git a/content/validators/docker-compose-monitoring.yaml b/content/validators/docker-compose-monitoring.yaml index 89ed4db92..e28ed8c96 100644 --- a/content/validators/docker-compose-monitoring.yaml +++ b/content/validators/docker-compose-monitoring.yaml @@ -164,7 +164,7 @@ services: # Set SCRAPE_TARGETS_JSON in .env # docker compose --profile monitoring up -d alloy: - image: grafana/alloy:v1.20.1 + image: grafana/alloy:v1.21.2 init: true container_name: genlayer-node-alloy labels: diff --git a/pages/api-references/genlayer-node.mdx b/pages/api-references/genlayer-node.mdx index a37ea68ef..6bf4434b1 100644 --- a/pages/api-references/genlayer-node.mdx +++ b/pages/api-references/genlayer-node.mdx @@ -1900,7 +1900,9 @@ If **no** condition has been observed at all, `status` is `unknown` — nothing A condition can never exceed the liveness cap its catalog entry declares. The GenVM conditions are capped at `degraded`, so a dead LLM provider returns **200**: that node is still booted, synced and voting — it votes Timeout on the transactions it cannot execute, which is the designed behaviour rather than an outage. Failing the endpoint would pull a working validator out of a load balancer. -`consensus.ban`, `consensus.stake`, `chain.rpc`, `chain.websocket` and `chain.sync` are capped at `unavailable`, because each of them stops the node doing its job. +`consensus.ban`, `chain.rpc`, `chain.websocket` and `chain.sync` are capped at `unavailable`, because each of them stops the node doing its job. + +`consensus.stake` is capped at `warning`: below the minimum self-stake the node keeps syncing, and only the consensus contracts do not select the validator for duties. The reason is `self_stake_pending` when a pending self-stake deposit covers the gap (it becomes stake at the validator's prime in a later epoch), and `self_stake_below_minimum` otherwise. **WebDriver render check** @@ -1967,16 +1969,16 @@ that owns the manager configuration. Observed `genvm.web` results still apply. } ``` -**`chain.sync` — 503 only when the node stops syncing** +**`chain.sync` — 503 only when the sync is blocked** -Depth is not a fault. A node syncing from genesis is millions of blocks behind and perfectly healthy. What matters is whether the stored synced block advances. +Depth is not a fault. A node syncing from genesis is millions of blocks behind and healthy while its synced block advances. The node reports 503 only when its sync cannot get past a block. -| Reason | State | HTTP | -|---|---|---| -| `sync_lagging` | `warning` | 200 | -| `sync_catching_up` | `degraded` | 200 | -| `sync_stalled` | `unavailable` | **503** | -| `sync_feed_frozen` | `unavailable` | **503** | +| Reason | State | HTTP | When | +|---|---|---|---| +| `sync_lagging` | `warning` | 200 | 1–100 blocks behind for 30 s, or the sync cursor cannot be read | +| `sync_catching_up` | `degraded` | 200 | More than 100 blocks behind, at any depth | +| `sync_blocked` | `unavailable` | **503** | The sync has failed at the same block for 5 minutes (`details`: `failing_block`, `failures`, `failing_seconds`) | +| `sync_block_unreadable` | `unavailable` | **503** | The node cannot read the logs of a block (`details`: `unreadable_block`, `unreadable_seconds`) | The node never skips a duty because it is behind. It votes Timeout only on a transaction that reads state it has not synced; a new contract deploy still runs. @@ -2165,7 +2167,7 @@ Available free disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_total_bytes** @@ -2176,7 +2178,7 @@ Total disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_usage_bytes** @@ -2187,7 +2189,7 @@ Used disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_usage_percent** @@ -2198,7 +2200,7 @@ Used disk space as percentage. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **Node Status Metrics** @@ -2248,6 +2250,15 @@ Node synchronization status (1 = synced, 0 = not synced). **Labels:** - `node`: Node address (hex format) +**genlayer_node_sync_halted** + +Whether replay has stopped at `consensus.sync_halt_block` (1 = halted, 0 = running). An intentional halt is not a stalled sync; the node continues serving RPC and snapshots. + +**Type:** Gauge + +**Labels:** +- `node`: Node address (hex format) + **genlayer_node_prime_blocked_insufficient_funds** Whether a mandatory validator prime is currently blocked by an unfunded operator wallet (1 = blocked, 0 = not blocked). While blocked the validator cannot pay for consensus duty transactions and is flagged idle each round — fund the operator wallet to recover. @@ -2257,6 +2268,21 @@ Whether a mandatory validator prime is currently blocked by an unfunded operator **Labels:** - `node`: Node address (hex format) +**State pruning metrics** + +Contract-state pruning (`node.state.enabled`). All are gauges labelled with `node`; the `_total` ones count since the process started. + +| Metric | Description | +|---|---| +| `genlayer_node_state_pruning_enabled` | 1 when pruning is on, 0 for an archive node | +| `genlayer_node_state_pruning_cutoff_block` | Newest block whose finalized transactions were handed to the collector | +| `genlayer_node_state_pruned_versions_total` | Versions merged into a contract's pruned base | +| `genlayer_node_state_discarded_versions_total` | Overturned or superseded versions deleted without merging | +| `genlayer_node_state_pruning_deleted_bytes_total` | Uncompressed size of the deleted versions; the merge rewrites part of it, so the disk reclaimed is lower | +| `genlayer_node_state_pruning_skipped_contracts_total` | Contracts left unpruned in a sweep because a version is not built on the finalized chain; the next finalization retries them | +| `genlayer_node_state_pruning_pending_tasks` | Prune tasks the collector has not finished | +| `genlayer_node_state_disk_bytes` | Estimated on-disk size of all contract state | + **genlayer_node_uptime_seconds** Node uptime in seconds. @@ -2398,6 +2424,85 @@ Decoded revert causes, one increment per observed revert (attempt-level). - `method`: Contract method name - `error`: Decoded custom error from the fee/gas allowlist (`InsufficientFeesForRound`, `InsufficientFees`, `FailedFeeTransfer`, `FeeSettlementNotCompleted`, `MaxPriceExceeded`, `ExecutionBudgetExceeded`, `MessageBudgetExceeded`, `BudgetTooLow`, `RollupBudgetBelowFloor`, `InsufficientBondCustody`, `InvalidAppealBond`, `AppealBondTooLow`, `InsufficientGasForInternalMessageCreation`, `OutOfGas`); anything else collapses to `other` +**Transaction Read Metrics** + +**genlayer_node_transaction_reads_total** + +Reads of consensus transaction data from the chain, made through the node's one transaction reader. One read can be several chain calls: a `snapshot` is the transaction record plus, unless the caller skips them, its idleness timestamps and phase timeouts; a `fee_state` read is the fee inputs of one execution at the transaction's processing block: 8 reads in parallel, plus the idleness timeouts when the transaction has no phase timeouts of its own, plus 2 reads when it has a message fee allocation tree; a `latest_*_with_effect` lookup pages the contract's history and makes one `snapshot` read for each candidate with an agreed execution, which counts separately. Use it to see which node path reads which data, and how often. + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot` (the transaction as the chain holds it at a block), `fee_state` (the fee inputs GenVM needs to execute the transaction), `latest_accepted_with_effect`, `latest_finalized_with_effect` (the newest accepted or finalized transaction of a contract that changed its state) +- `flow`: The node path that asked: `duty` (a consensus duty, including the leader's and validators' executions), `sync` (the sync filter and its history preload), `recovery` (accepted data missing from a replay batch), `replay` (a replayed execution and the finalized-state settle of the replay), `tribunal` (the judgement of an accused execution), `genvm` (a contract history lookup of a GenVM execution), `rpc` (a JSON-RPC request, including the replay of a trace that is not stored), `other` (no path named) +- `outcome`: One of `ok`, `error` + +Reads the node's transaction read cache answers from memory are not counted here: this counter is the chain reads only. + +**genlayer_node_transaction_read_cache_total** + +Transaction reads answered by the node's transaction read cache. The cache keeps a transaction's snapshot at an explicit block, its fee state at a processing block, and the answers of the contract history lookup ("latest accepted / finalized transaction with an effect on contract C at block A", which every GenVM execution asks and the sync filter preloads), so the repeats of one node read the chain once: the sync filter, the accepted handler and the last-vote reveal reading an accepted transaction at the same block; a validator's duty run and its replay reading the fee state and the history of the same round. A value read at or below the chain's finalized block is kept for `consensus.transaction_cache.settled_ttl`; one read above it, which a reorg can replace, for `unsettled_ttl` (snapshots) or `unsettled_long_ttl` (fee states, history). See the configuration reference. + +`miss` and `bypass` match the `genlayer_node_transaction_reads_total` reads of the same method and flow, except the `snapshot` reads a history lookup makes for its candidates, which do not go through the cache. A history preload counts the accepted answer and, when that answer has no transaction, the finalized answer a GenVM execution then falls back to: each `miss` when the preload read the chain and `hit` when the answer was already kept or being read. Only a preload that read the accepted answer reads the finalized one. A history lookup that excludes the latest answer itself counts `miss`: only the chain can give the older answer. + +The share of reads the chain did not serve, per method: + +```promql +sum by (method) (rate(genlayer_node_transaction_read_cache_total{outcome=~"hit|shared"}[1h])) +/ sum by (method) (rate(genlayer_node_transaction_read_cache_total[1h])) +``` + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_accepted_with_effect`, `latest_finalized_with_effect` +- `flow`: The node path that asked, as in `genlayer_node_transaction_reads_total` +- `outcome`: One of `hit` (served from the cache), `miss` (read from the chain; kept when the read succeeded), `shared` (served by another caller's chain read of the same data, made at the same time), `bypass` (a read the cache does not keep: one at the latest block) + +With `consensus.transaction_cache.enabled: false` the cache passes every read through and none of the `genlayer_node_transaction_read_cache_*` metrics move. + +**genlayer_node_sync_preloads_queued_total** + +History preloads the sync filter queued: one per accepted transaction it read, to put into the transaction read cache the answers the replay's GenVM execution will ask for. `consensus.transaction_cache.preload_workers` preloads read the chain at a time; the others wait for a free worker, and none is dropped while the sync runs. A sync that stops, for a restart or a shutdown, drops its backlog; a restart filters the blocks it did not sync again and queues their preloads again. Each finished preload counts once in `genlayer_node_transaction_read_cache_total{flow="sync",method="latest_accepted_with_effect"}`, whether or not it also loaded the finalized answer, so the difference is the backlog, plus the backlogs that sync restarts dropped: + +```promql +genlayer_node_sync_preloads_queued_total +- sum(genlayer_node_transaction_read_cache_total{flow="sync",method="latest_accepted_with_effect"}) +``` + +A backlog that keeps growing in a catch-up means the preloads cannot keep up with the filter; more workers fill the cache sooner and add chain RPC load. With `consensus.transaction_cache.enabled: false` a preload does nothing and the query does not apply. + +**Type:** Counter + +**genlayer_node_transaction_read_cache_purges_total** + +Times the transaction read cache was emptied. The cache pins its reads by block number, and a reorg can replace a block above the chain's finalized block, so the node empties it when it detects one. A steady rate means the chain reorganizes often; each purge costs the cache, not correctness. + +**Type:** Counter + +**Labels:** +- `reason`: One of `canonical_reorg` (the replay rolled back to the canonical chain), `router_rewind` (the event router rewound over a replaced block range) + +**genlayer_node_transaction_read_cache_evictions_total** + +Values the transaction read cache dropped by itself. Use it to tune the cache: many `expired` mean a TTL is shorter than the time between the reads it should serve; any `capacity` means a size limit is too small for what the node reads within the TTL. A value nobody read again that is dropped after its TTL is not counted. + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_with_effect` (the history answers, accepted and finalized together) +- `reason`: One of `expired` (a read found its value past its TTL), `capacity` (a live value dropped to make room) + +**genlayer_node_transaction_read_cache_entries** + +Values the transaction read cache keeps now, per tier and per finality of the block they were read at. Expired values not yet dropped are included. + +**Type:** Gauge + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_with_effect` +- `finality`: `settled` (read at or below the chain's finalized block) or `unsettled` (above it) + **Fee Flow Metrics (v0.6 ConsensusMainWithFees)** Note: there are no dedicated appeal-bond metrics. No node runtime path submits appeals — appellants are external clients funding bonds from their own wallets. If a validator appeal duty ever ships, the method-labeled gas/submission metrics above cover it under `method="topUpAndSubmitAppeal"` with no code change. @@ -2526,7 +2631,7 @@ docker ps | grep genlayer-node-webdriver If not running, start it: ```bash -task docker:webdriver:docker-compose:up:detach +task docker:webdriver:up ``` **Metrics Not Updating** @@ -2572,6 +2677,26 @@ The token is the value of `GENLAYERNODE_NODE_OPERATOR_TOKEN` on the node process Every archive carries a `snapshot.json` manifest recording the format version, the scopes inside, the rollup block the GenVM store was captured at, and — for `all` and `ops` — the operator address that produced it. + Manifest version remains `1`. `finalizedRoot` contains a `0x`-prefixed, + 32-byte chain-trie proof. The cursor and root are + read from the completed GenVM checkpoint opened read-only, so they describe + the archived files even while live replay advances. An absent root is + unavailable, not a zero root. For a pristine empty store, the empty root is + `Keccak256(0x000000)`, the proof of an empty root branch. Replay from genesis + maintains the finalized trie, including an empty root before any finalization. + Every GenVM snapshot past genesis has this field unless its datadir predates + root maintenance. Such datadirs require a resync from genesis to obtain roots; + continuing replay or restoring their snapshots does not reconstruct missing history. + + The trie maps each address to the storage root of its latest finalized + transaction with a storage effect. Only canonical replay finalization updates + it, identically on full nodes and validators. A failed execution, a decision + without storage state, or a successful execution whose proof equals its + predecessor leaves the entry unchanged (and does not insert an absent address). + A first empty storage generation also leaves the entry absent. + Storage and root writes share one reversible batch, so a canonical reorg rolls + both back. Speculative execution, acceptance and appeals do not update this root. + - `destDir` (string, optional): Absolute path on the node's filesystem, which must resolve to a location inside the configured snapshot directory (`node.admin.snapshot_dir`, default `/snapshots`). When set, switches to write-to-path mode; when omitted or empty, the snapshot is streamed back as `application/gzip`. Paths outside the snapshot directory are rejected with `400`. **Returns:** @@ -2620,6 +2745,7 @@ curl -X POST http://127.0.0.1:9153/snapshot \ -H "X-Admin-Auth: $GENLAYERNODE_NODE_OPERATOR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"destDir": "/var/lib/genlayer/data/node/snapshots/bradbury-100"}' +``` Take only the portable half, to hand to another operator: @@ -2629,7 +2755,6 @@ curl -sS -X POST http://localhost:9153/snapshot \ -H 'Content-Type: application/json' \ -d '{"scope": "genvm"}' -o genvm-snapshot.tar.gz ``` -``` **Example Response — Write-to-Path Mode:** @@ -2656,6 +2781,50 @@ HTTP/1.1 204 No Content - Token comparison is constant-time and length-padded so neither the value nor the length of the secret can be inferred from response timing. - Rotation: update `GENLAYERNODE_NODE_OPERATOR_TOKEN` and restart the node. Tokens are read once at startup and not hot-reloaded. +**Restore A Portable Snapshot:** + +```bash +genlayernode snapshot restore genvm-snapshot.tar.gz --datadir /var/lib/genlayer/restored +# An extracted snapshot directory is also accepted +genlayernode run --config /path/to/network.yaml --config /path/to/restore-overlay.yaml +``` + +The overlay sets `datadir: /var/lib/genlayer/restored` and keeps the default +`node.genvmdb: genvm.db` and `node.opsdb: ops.db`. Use the source deployment's +network configuration; the manifest does not identify the network. The restore +command requires an absent or empty datadir, validates version 1 and exactly +`scope=genvm`, checks the manifest cursor and any roots against the checkpoint, +and installs the files at `/genvm.db`. It refuses links, unexpected +archive entries, and nonportable scopes. It creates no operation store; normal +startup creates a fresh `ops.db` and resumes replay at the durable cursor + 1. +Archives are trusted local input with no extraction size cap. Written files and +directories are fsynced before installation, and the datadir is fsynced before +and after the rename. + +Non-default `node.genvmdb` paths are not supported by restore. A rootless snapshot +with a non-zero cursor is accepted with a CLI warning: the restored node will not +maintain roots and needs a resync from genesis for root comparisons. + +To capture an exact replay boundary, run in full mode with +`consensus.sync_halt_block` set to the target block and wait for +`genlayer_node_sync_halted == 1` before requesting the snapshot. See the +[configuration guide](../../deploy/configuration.md#consensus-configuration) +for halt health and restart semantics. Restore verifies the checkpoint's +metadata, not the correctness of its historical execution. Compare snapshots +captured at the same halt block with `sync-check.sh --expect-root` or +`--reference-snapshot`; restoring at N and replaying to M preserves the same +finalized root as replaying from genesis to M. + +`sync-check.sh --network bradbury --checkpoint N --checkpoint M --halt-at H` +captures an ascending chain on one datadir, saving `snapshots/.tar.gz` +and `.json` under its work directory. Every output requires a finalized root. +`--reference-dir ` compares available `.tar.gz` references and +`checkpoints.json` records each halt, including mismatches before exit 4. +Without `--halt-at`, the final segment reaches its boot head; the timeout covers +all segments. `--config` overrides network defaults, and `--genvm-root` selects +the GenVM directory. The Task equivalent uses `NETWORK`, comma-separated +`CHECKPOINTS`, `HALT_AT`, `REFERENCE_DIR`, and `GENVM_ROOT`. + **Forward-compatibility note:** when the zero-downtime upgrade controller (Phase 3) lands, `/snapshot` will additionally accept a second role (`upgrade`) so the controller can drive the snapshot + stop + start sequence with its own credential. The operator-token path documented here remains the same — no migration is required for operator tooling. **cURL Example with Bearer header:** diff --git a/pages/api-references/genlayer-node/ops/health.mdx b/pages/api-references/genlayer-node/ops/health.mdx index fdd2fe13f..71b79eb5b 100644 --- a/pages/api-references/genlayer-node/ops/health.mdx +++ b/pages/api-references/genlayer-node/ops/health.mdx @@ -84,7 +84,9 @@ If **no** condition has been observed at all, `status` is `unknown` — nothing A condition can never exceed the liveness cap its catalog entry declares. The GenVM conditions are capped at `degraded`, so a dead LLM provider returns **200**: that node is still booted, synced and voting — it votes Timeout on the transactions it cannot execute, which is the designed behaviour rather than an outage. Failing the endpoint would pull a working validator out of a load balancer. -`consensus.ban`, `consensus.stake`, `chain.rpc`, `chain.websocket` and `chain.sync` are capped at `unavailable`, because each of them stops the node doing its job. +`consensus.ban`, `chain.rpc`, `chain.websocket` and `chain.sync` are capped at `unavailable`, because each of them stops the node doing its job. + +`consensus.stake` is capped at `warning`: below the minimum self-stake the node keeps syncing, and only the consensus contracts do not select the validator for duties. The reason is `self_stake_pending` when a pending self-stake deposit covers the gap (it becomes stake at the validator's prime in a later epoch), and `self_stake_below_minimum` otherwise. **WebDriver render check** @@ -151,16 +153,16 @@ that owns the manager configuration. Observed `genvm.web` results still apply. } ``` -**`chain.sync` — 503 only when the node stops syncing** +**`chain.sync` — 503 only when the sync is blocked** -Depth is not a fault. A node syncing from genesis is millions of blocks behind and perfectly healthy. What matters is whether the stored synced block advances. +Depth is not a fault. A node syncing from genesis is millions of blocks behind and healthy while its synced block advances. The node reports 503 only when its sync cannot get past a block. -| Reason | State | HTTP | -|---|---|---| -| `sync_lagging` | `warning` | 200 | -| `sync_catching_up` | `degraded` | 200 | -| `sync_stalled` | `unavailable` | **503** | -| `sync_feed_frozen` | `unavailable` | **503** | +| Reason | State | HTTP | When | +|---|---|---|---| +| `sync_lagging` | `warning` | 200 | 1–100 blocks behind for 30 s, or the sync cursor cannot be read | +| `sync_catching_up` | `degraded` | 200 | More than 100 blocks behind, at any depth | +| `sync_blocked` | `unavailable` | **503** | The sync has failed at the same block for 5 minutes (`details`: `failing_block`, `failures`, `failing_seconds`) | +| `sync_block_unreadable` | `unavailable` | **503** | The node cannot read the logs of a block (`details`: `unreadable_block`, `unreadable_seconds`) | The node never skips a duty because it is behind. It votes Timeout only on a transaction that reads state it has not synced; a new contract deploy still runs. diff --git a/pages/api-references/genlayer-node/ops/metrics.mdx b/pages/api-references/genlayer-node/ops/metrics.mdx index 2a2bdb5c0..dee2567fa 100644 --- a/pages/api-references/genlayer-node/ops/metrics.mdx +++ b/pages/api-references/genlayer-node/ops/metrics.mdx @@ -175,7 +175,7 @@ Available free disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_total_bytes** @@ -186,7 +186,7 @@ Total disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_usage_bytes** @@ -197,7 +197,7 @@ Used disk space in bytes. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **genlayer_node_disk_usage_percent** @@ -208,7 +208,7 @@ Used disk space as percentage. **Labels:** - `component`: `node` -- `directory`: One of `genlayer.db`, `keystore`, `logs` +- `directory`: One of `genvm.db`, `ops.db`, `keystore`, `logs` - `node`: Node address (hex format) **Node Status Metrics** @@ -258,6 +258,15 @@ Node synchronization status (1 = synced, 0 = not synced). **Labels:** - `node`: Node address (hex format) +**genlayer_node_sync_halted** + +Whether replay has stopped at `consensus.sync_halt_block` (1 = halted, 0 = running). An intentional halt is not a stalled sync; the node continues serving RPC and snapshots. + +**Type:** Gauge + +**Labels:** +- `node`: Node address (hex format) + **genlayer_node_prime_blocked_insufficient_funds** Whether a mandatory validator prime is currently blocked by an unfunded operator wallet (1 = blocked, 0 = not blocked). While blocked the validator cannot pay for consensus duty transactions and is flagged idle each round — fund the operator wallet to recover. @@ -267,6 +276,21 @@ Whether a mandatory validator prime is currently blocked by an unfunded operator **Labels:** - `node`: Node address (hex format) +**State pruning metrics** + +Contract-state pruning (`node.state.enabled`). All are gauges labelled with `node`; the `_total` ones count since the process started. + +| Metric | Description | +|---|---| +| `genlayer_node_state_pruning_enabled` | 1 when pruning is on, 0 for an archive node | +| `genlayer_node_state_pruning_cutoff_block` | Newest block whose finalized transactions were handed to the collector | +| `genlayer_node_state_pruned_versions_total` | Versions merged into a contract's pruned base | +| `genlayer_node_state_discarded_versions_total` | Overturned or superseded versions deleted without merging | +| `genlayer_node_state_pruning_deleted_bytes_total` | Uncompressed size of the deleted versions; the merge rewrites part of it, so the disk reclaimed is lower | +| `genlayer_node_state_pruning_skipped_contracts_total` | Contracts left unpruned in a sweep because a version is not built on the finalized chain; the next finalization retries them | +| `genlayer_node_state_pruning_pending_tasks` | Prune tasks the collector has not finished | +| `genlayer_node_state_disk_bytes` | Estimated on-disk size of all contract state | + **genlayer_node_uptime_seconds** Node uptime in seconds. @@ -408,6 +432,85 @@ Decoded revert causes, one increment per observed revert (attempt-level). - `method`: Contract method name - `error`: Decoded custom error from the fee/gas allowlist (`InsufficientFeesForRound`, `InsufficientFees`, `FailedFeeTransfer`, `FeeSettlementNotCompleted`, `MaxPriceExceeded`, `ExecutionBudgetExceeded`, `MessageBudgetExceeded`, `BudgetTooLow`, `RollupBudgetBelowFloor`, `InsufficientBondCustody`, `InvalidAppealBond`, `AppealBondTooLow`, `InsufficientGasForInternalMessageCreation`, `OutOfGas`); anything else collapses to `other` +**Transaction Read Metrics** + +**genlayer_node_transaction_reads_total** + +Reads of consensus transaction data from the chain, made through the node's one transaction reader. One read can be several chain calls: a `snapshot` is the transaction record plus, unless the caller skips them, its idleness timestamps and phase timeouts; a `fee_state` read is the fee inputs of one execution at the transaction's processing block: 8 reads in parallel, plus the idleness timeouts when the transaction has no phase timeouts of its own, plus 2 reads when it has a message fee allocation tree; a `latest_*_with_effect` lookup pages the contract's history and makes one `snapshot` read for each candidate with an agreed execution, which counts separately. Use it to see which node path reads which data, and how often. + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot` (the transaction as the chain holds it at a block), `fee_state` (the fee inputs GenVM needs to execute the transaction), `latest_accepted_with_effect`, `latest_finalized_with_effect` (the newest accepted or finalized transaction of a contract that changed its state) +- `flow`: The node path that asked: `duty` (a consensus duty, including the leader's and validators' executions), `sync` (the sync filter and its history preload), `recovery` (accepted data missing from a replay batch), `replay` (a replayed execution and the finalized-state settle of the replay), `tribunal` (the judgement of an accused execution), `genvm` (a contract history lookup of a GenVM execution), `rpc` (a JSON-RPC request, including the replay of a trace that is not stored), `other` (no path named) +- `outcome`: One of `ok`, `error` + +Reads the node's transaction read cache answers from memory are not counted here: this counter is the chain reads only. + +**genlayer_node_transaction_read_cache_total** + +Transaction reads answered by the node's transaction read cache. The cache keeps a transaction's snapshot at an explicit block, its fee state at a processing block, and the answers of the contract history lookup ("latest accepted / finalized transaction with an effect on contract C at block A", which every GenVM execution asks and the sync filter preloads), so the repeats of one node read the chain once: the sync filter, the accepted handler and the last-vote reveal reading an accepted transaction at the same block; a validator's duty run and its replay reading the fee state and the history of the same round. A value read at or below the chain's finalized block is kept for `consensus.transaction_cache.settled_ttl`; one read above it, which a reorg can replace, for `unsettled_ttl` (snapshots) or `unsettled_long_ttl` (fee states, history). See the configuration reference. + +`miss` and `bypass` match the `genlayer_node_transaction_reads_total` reads of the same method and flow, except the `snapshot` reads a history lookup makes for its candidates, which do not go through the cache. A history preload counts the accepted answer and, when that answer has no transaction, the finalized answer a GenVM execution then falls back to: each `miss` when the preload read the chain and `hit` when the answer was already kept or being read. Only a preload that read the accepted answer reads the finalized one. A history lookup that excludes the latest answer itself counts `miss`: only the chain can give the older answer. + +The share of reads the chain did not serve, per method: + +```promql +sum by (method) (rate(genlayer_node_transaction_read_cache_total{outcome=~"hit|shared"}[1h])) +/ sum by (method) (rate(genlayer_node_transaction_read_cache_total[1h])) +``` + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_accepted_with_effect`, `latest_finalized_with_effect` +- `flow`: The node path that asked, as in `genlayer_node_transaction_reads_total` +- `outcome`: One of `hit` (served from the cache), `miss` (read from the chain; kept when the read succeeded), `shared` (served by another caller's chain read of the same data, made at the same time), `bypass` (a read the cache does not keep: one at the latest block) + +With `consensus.transaction_cache.enabled: false` the cache passes every read through and none of the `genlayer_node_transaction_read_cache_*` metrics move. + +**genlayer_node_sync_preloads_queued_total** + +History preloads the sync filter queued: one per accepted transaction it read, to put into the transaction read cache the answers the replay's GenVM execution will ask for. `consensus.transaction_cache.preload_workers` preloads read the chain at a time; the others wait for a free worker, and none is dropped while the sync runs. A sync that stops, for a restart or a shutdown, drops its backlog; a restart filters the blocks it did not sync again and queues their preloads again. Each finished preload counts once in `genlayer_node_transaction_read_cache_total{flow="sync",method="latest_accepted_with_effect"}`, whether or not it also loaded the finalized answer, so the difference is the backlog, plus the backlogs that sync restarts dropped: + +```promql +genlayer_node_sync_preloads_queued_total +- sum(genlayer_node_transaction_read_cache_total{flow="sync",method="latest_accepted_with_effect"}) +``` + +A backlog that keeps growing in a catch-up means the preloads cannot keep up with the filter; more workers fill the cache sooner and add chain RPC load. With `consensus.transaction_cache.enabled: false` a preload does nothing and the query does not apply. + +**Type:** Counter + +**genlayer_node_transaction_read_cache_purges_total** + +Times the transaction read cache was emptied. The cache pins its reads by block number, and a reorg can replace a block above the chain's finalized block, so the node empties it when it detects one. A steady rate means the chain reorganizes often; each purge costs the cache, not correctness. + +**Type:** Counter + +**Labels:** +- `reason`: One of `canonical_reorg` (the replay rolled back to the canonical chain), `router_rewind` (the event router rewound over a replaced block range) + +**genlayer_node_transaction_read_cache_evictions_total** + +Values the transaction read cache dropped by itself. Use it to tune the cache: many `expired` mean a TTL is shorter than the time between the reads it should serve; any `capacity` means a size limit is too small for what the node reads within the TTL. A value nobody read again that is dropped after its TTL is not counted. + +**Type:** Counter + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_with_effect` (the history answers, accepted and finalized together) +- `reason`: One of `expired` (a read found its value past its TTL), `capacity` (a live value dropped to make room) + +**genlayer_node_transaction_read_cache_entries** + +Values the transaction read cache keeps now, per tier and per finality of the block they were read at. Expired values not yet dropped are included. + +**Type:** Gauge + +**Labels:** +- `method`: One of `snapshot`, `fee_state`, `latest_with_effect` +- `finality`: `settled` (read at or below the chain's finalized block) or `unsettled` (above it) + **Fee Flow Metrics (v0.6 ConsensusMainWithFees)** Note: there are no dedicated appeal-bond metrics. No node runtime path submits appeals — appellants are external clients funding bonds from their own wallets. If a validator appeal duty ever ships, the method-labeled gas/submission metrics above cover it under `method="topUpAndSubmitAppeal"` with no code change. @@ -536,7 +639,7 @@ docker ps | grep genlayer-node-webdriver If not running, start it: ```bash -task docker:webdriver:docker-compose:up:detach +task docker:webdriver:up ``` **Metrics Not Updating** diff --git a/pages/api-references/genlayer-node/ops/snapshot.mdx b/pages/api-references/genlayer-node/ops/snapshot.mdx index 8139b5ba5..aebe8fc06 100644 --- a/pages/api-references/genlayer-node/ops/snapshot.mdx +++ b/pages/api-references/genlayer-node/ops/snapshot.mdx @@ -32,6 +32,26 @@ The token is the value of `GENLAYERNODE_NODE_OPERATOR_TOKEN` on the node process Every archive carries a `snapshot.json` manifest recording the format version, the scopes inside, the rollup block the GenVM store was captured at, and — for `all` and `ops` — the operator address that produced it. + Manifest version remains `1`. `finalizedRoot` contains a `0x`-prefixed, + 32-byte chain-trie proof. The cursor and root are + read from the completed GenVM checkpoint opened read-only, so they describe + the archived files even while live replay advances. An absent root is + unavailable, not a zero root. For a pristine empty store, the empty root is + `Keccak256(0x000000)`, the proof of an empty root branch. Replay from genesis + maintains the finalized trie, including an empty root before any finalization. + Every GenVM snapshot past genesis has this field unless its datadir predates + root maintenance. Such datadirs require a resync from genesis to obtain roots; + continuing replay or restoring their snapshots does not reconstruct missing history. + + The trie maps each address to the storage root of its latest finalized + transaction with a storage effect. Only canonical replay finalization updates + it, identically on full nodes and validators. A failed execution, a decision + without storage state, or a successful execution whose proof equals its + predecessor leaves the entry unchanged (and does not insert an absent address). + A first empty storage generation also leaves the entry absent. + Storage and root writes share one reversible batch, so a canonical reorg rolls + both back. Speculative execution, acceptance and appeals do not update this root. + - `destDir` (string, optional): Absolute path on the node's filesystem, which must resolve to a location inside the configured snapshot directory (`node.admin.snapshot_dir`, default `/snapshots`). When set, switches to write-to-path mode; when omitted or empty, the snapshot is streamed back as `application/gzip`. Paths outside the snapshot directory are rejected with `400`. **Returns:** @@ -80,6 +100,7 @@ curl -X POST http://127.0.0.1:9153/snapshot \ -H "X-Admin-Auth: $GENLAYERNODE_NODE_OPERATOR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"destDir": "/var/lib/genlayer/data/node/snapshots/bradbury-100"}' +``` Take only the portable half, to hand to another operator: @@ -89,7 +110,6 @@ curl -sS -X POST http://localhost:9153/snapshot \ -H 'Content-Type: application/json' \ -d '{"scope": "genvm"}' -o genvm-snapshot.tar.gz ``` -``` **Example Response — Write-to-Path Mode:** @@ -116,6 +136,50 @@ HTTP/1.1 204 No Content - Token comparison is constant-time and length-padded so neither the value nor the length of the secret can be inferred from response timing. - Rotation: update `GENLAYERNODE_NODE_OPERATOR_TOKEN` and restart the node. Tokens are read once at startup and not hot-reloaded. +**Restore A Portable Snapshot:** + +```bash +genlayernode snapshot restore genvm-snapshot.tar.gz --datadir /var/lib/genlayer/restored +# An extracted snapshot directory is also accepted +genlayernode run --config /path/to/network.yaml --config /path/to/restore-overlay.yaml +``` + +The overlay sets `datadir: /var/lib/genlayer/restored` and keeps the default +`node.genvmdb: genvm.db` and `node.opsdb: ops.db`. Use the source deployment's +network configuration; the manifest does not identify the network. The restore +command requires an absent or empty datadir, validates version 1 and exactly +`scope=genvm`, checks the manifest cursor and any roots against the checkpoint, +and installs the files at `/genvm.db`. It refuses links, unexpected +archive entries, and nonportable scopes. It creates no operation store; normal +startup creates a fresh `ops.db` and resumes replay at the durable cursor + 1. +Archives are trusted local input with no extraction size cap. Written files and +directories are fsynced before installation, and the datadir is fsynced before +and after the rename. + +Non-default `node.genvmdb` paths are not supported by restore. A rootless snapshot +with a non-zero cursor is accepted with a CLI warning: the restored node will not +maintain roots and needs a resync from genesis for root comparisons. + +To capture an exact replay boundary, run in full mode with +`consensus.sync_halt_block` set to the target block and wait for +`genlayer_node_sync_halted == 1` before requesting the snapshot. See the +[configuration guide](../../deploy/configuration.md#consensus-configuration) +for halt health and restart semantics. Restore verifies the checkpoint's +metadata, not the correctness of its historical execution. Compare snapshots +captured at the same halt block with `sync-check.sh --expect-root` or +`--reference-snapshot`; restoring at N and replaying to M preserves the same +finalized root as replaying from genesis to M. + +`sync-check.sh --network bradbury --checkpoint N --checkpoint M --halt-at H` +captures an ascending chain on one datadir, saving `snapshots/.tar.gz` +and `.json` under its work directory. Every output requires a finalized root. +`--reference-dir ` compares available `.tar.gz` references and +`checkpoints.json` records each halt, including mismatches before exit 4. +Without `--halt-at`, the final segment reaches its boot head; the timeout covers +all segments. `--config` overrides network defaults, and `--genvm-root` selects +the GenVM directory. The Task equivalent uses `NETWORK`, comma-separated +`CHECKPOINTS`, `HALT_AT`, `REFERENCE_DIR`, and `GENVM_ROOT`. + **Forward-compatibility note:** when the zero-downtime upgrade controller (Phase 3) lands, `/snapshot` will additionally accept a second role (`upgrade`) so the controller can drive the snapshot + stop + start sequence with its own credential. The operator-token path documented here remains the same — no migration is required for operator tooling. **cURL Example with Bearer header:** diff --git a/pages/validators/changelog.mdx b/pages/validators/changelog.mdx index 2b203bd7a..0128843fa 100644 --- a/pages/validators/changelog.mdx +++ b/pages/validators/changelog.mdx @@ -1,5 +1,48 @@ # Changelog +## v0.6.0-rc.3 + +Before you upgrade, check the alert rules that read `/health`. The `chain.sync` reasons `sync_stalled` and `sync_feed_frozen` are gone: a node far behind that still syncs returns 200, and a sync that fails at the same block for 5 minutes returns 503 with reason `sync_blocked`. A self-stake below the minimum now sets `consensus.stake` to `warning` (HTTP 200), not 503. At its first start, this release moves the node's nonce ledger from `genvm.db` to `ops.db` (log line `moved the nonce ledger from genvm.db to ops.db`); if you then go back to v0.6.0-rc.2, that node does not start while a transaction it signed is still pending. + +### New features + +- `doctor` checks that the operator key unlocks when you give the node password (`--password` or `GENLAYERNODE_PASSWORD`, as for the node); without a password it shows a warning and does not fail +- `doctor --output json` writes one JSON document with a stable `code` and `action` for each finding, and exits `0` (start), `1` (blocked) or `2` (doctor could not run); the codes are in `docs/deploy/troubleshooting.md` +- Change the chain RPC key without a restart: put the key in a file and set `rollup.genlayerchainrpckeyfile` to its path; the node reads the file again at most every 30 s + - do not also set `GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY`: the node then does not start +- Contract-state pruning: set `node.state.enabled: true` to delete old contract-state versions behind finalized ones after `node.state.retention` (default `336h` of chain time); it is off by default, so the node keeps all history; read `docs/deploy/state-pruning.md` first +- The node makes fewer chain RPC calls: it keeps repeated transaction reads in memory and does no reorg check for blocks at or below the chain's `finalized` block + - the cache is on by default; its settings are under `consensus.transaction_cache` +- `genlayernode snapshot restore --datadir ` installs a `genvm` snapshot, and the node continues its sync after the snapshot block + - to take a snapshot at a known block, a full node can stop its sync at `consensus.sync_halt_block` and keep RPC and ops serving +- The RPC API answers `net_version` with the configured chain id + +### Misc + +- The node runs contracts through the WebSocket endpoint (`/ws`) of the GenVM manager, not its HTTP run API; a manager that you run yourself (`genvm.start_manager: false`) must serve that endpoint, as the shipped GenVM does +- Update the release image to Alpine 3.24.3, the Alloy image of the release compose file to v1.21.2, and `go-ethereum` to v1.17.10 + +### Bug fixes + +- A leader no longer gets a strike when the commit phase ends on a timeout with enough commits: the leader did not reveal in that case, and now it does +- A new validator whose self-stake is still a pending deposit no longer fails `doctor` or gets a 503 from `/health`: both show a warning (`VALIDATOR_STAKE_PENDING`, reason `self_stake_pending`) until the next epoch moves the deposit into the stake + - a self-stake below the minimum is a warning too, and `doctor` exits 0 +- `/health` no longer returns 503 for hours while a node far behind syncs from genesis; `chain.sync` is `unavailable` only when the sync fails at the same block for 5 minutes (`sync_blocked`) or cannot read the logs of a block (`sync_block_unreadable`) +- When the node cannot read a recent transaction of a contract from the chain, a GenVM or RPC read of that contract's latest state now fails, instead of giving an older state +- The nonce ledger of the transactions the node signed is now in `ops.db`, not `genvm.db`: a resync that deletes `genvm.db` no longer deletes it, and a `genvm` snapshot no longer carries it +- A start-up failure now logs its cause in `node.log` (`Failed to build dependencies`), and the error no longer says only `previously failed` +- `gen_dbg_traceTransaction` now reads all the fee inputs of a replayed transaction at its processing block; some came from the latest block +- Correct the API reference: the `directory` label of the `genlayer_node_disk_*` metrics is `genvm.db`, `ops.db`, `logs` or `keystore` + +### Removed + +- The node no longer renames a v0.5 `/genlayer.db` to `genvm.db` at start: it ignores that folder and syncs from genesis into a new `genvm.db`; you can delete the old folder + +### Security + +- Build with Go 1.26.10, which has the fix for `GO-2026-6809` in the standard library +- Update `labstack/echo` to v4.16.3 for `GHSA-246p-cpwv-v3jq` (a rate-limit bypass with a spoofed `X-Forwarded-For` header) + ## v0.6.0-rc.2 ### New features @@ -270,6 +313,12 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Resilient WS RPC for fallback path +### Misc + +- Label RPC metrics with provider +- Add chain nonce and desync gauges metrics +- Log timestamps after acquireTransaction + ### Bug fixes - Close activator-binding race @@ -283,13 +332,14 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Add fault label to RPC error metric - Unwedge replay and filter sync -### Misc +## v0.5.9 -- Label RPC metrics with provider -- Add chain nonce and desync gauges metrics -- Log timestamps after acquireTransaction +### Misc -## v0.5.9 +- Use RFC3339Nano for zerolog timestamps +- Extract encoding functions into dedicated encoding package +- Move consensus entity types to entities package +- Add gen_dbg_traceTransaction API doc ### Bug fixes @@ -301,13 +351,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Prevent sync panic and self-dependency cycle during tx replay - Resume sync after WS reconnect -### Misc - -- Use RFC3339Nano for zerolog timestamps -- Extract encoding functions into dedicated encoding package -- Move consensus entity types to entities package -- Add gen_dbg_traceTransaction API doc - ## v0.5.8 ### New features @@ -316,6 +359,12 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Add bounded sync wait for RPC readiness - Add per-IP per-method RPC rate limiting +### Misc + +- Consolidate genvm configs +- Add `gen_getTransactionStatus` docs +- Add `gen_syncing` API docs and clarify RPC config group vs method precedence + ### Bug fixes - Defer GenVM precompile to container startup to avoid AVX-512 incompatibility @@ -329,18 +378,17 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Standardize RPC error codes per EIP-1474 - Retry tx lookup for RPC indexing lag -### Misc - -- Consolidate genvm configs -- Add `gen_getTransactionStatus` docs -- Add `gen_syncing` API docs and clarify RPC config group vs method precedence - ## v0.5.7 ### New features - Add LLM greyboxing with configurable chain order via YAML meta +### Misc + +- Include Alloy healthcheck script in release tarball +- Increase Alloy push intervals to 60s + ### Bug fixes - Use PendingAt for idle activator rotation @@ -349,11 +397,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Suppress shutdown errors in watchers - Reduce FindAcceptanceBlock range to fit RPC limit -### Misc - -- Include Alloy healthcheck script in release tarball -- Increase Alloy push intervals to 60s - ## v0.5.6 ### Bug fixes @@ -368,6 +411,10 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Add network label to logger and all metrics - Add metrics to rollup RPC transport and WebSocket +### Misc + +- Downgrade finalized-not-in-cache log to Debug + ### Bug fixes - Recover from cache miss on late lifecycle events @@ -377,10 +424,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Stuck nonce and finalize resilience - Patch GenVM dylib references on macOS during download -### Misc - -- Downgrade finalized-not-in-cache log to Debug - ## v0.5.4 ### New features @@ -399,6 +442,10 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Add recovery for missing TxData +### Misc + +- Use CtxLogger in HTTP handler constructors + ### Bug fixes - Invalidate timeout cache on SetTimeouts @@ -410,10 +457,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Increment leader revealed metric counter - Sync commit idle timeout with contract timestamps -### Misc - -- Use CtxLogger in HTTP handler constructors - ## v0.5.1 ### New features @@ -446,6 +489,13 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Add gen_getContractCode endpoint - Return full VMResult data from gen_call +### Misc + +- Inject txID into context for automatic log propagation +- Enable validator idle reveal idleness +- Add profiling with pyroscope +- Fix to handle zksync local-node compatibility + ### Bug fixes - Check pending queue head before activation @@ -465,13 +515,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Handle new consensus ResultType - New behavior for finalizing epochs -### Misc - -- Inject txID into context for automatic log propagation -- Enable validator idle reveal idleness -- Add profiling with pyroscope -- Fix to handle zksync local-node compatibility - ## v0.4.5 ### New features @@ -480,18 +523,18 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Implement sync waiting mechanism to ensure GenVM has latest state before contract execution - Add `genlayer_node_info` Prometheus metric exposing node and protocol version -### Bug fixes - -- Add canPrime check to verify epoch state before validator priming, preventing priming when epochs are out of sync -- Return user-friendly error instead of system error when sync times out -- Fix genvm executor process handling - ### Misc - Improve GenVM logging with context-aware logger - Update health checker to use ZkSync connectivity checks - Increase default genvm permits to 8 in config.yaml.example +### Bug fixes + +- Add canPrime check to verify epoch state before validator priming, preventing priming when epochs are out of sync +- Return user-friendly error instead of system error when sync times out +- Fix genvm executor process handling + ## v0.4.4 ### New features @@ -500,6 +543,14 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Refactor ZkSync client to split RPC and WSS connections for better reliability - Move storage writing to genvm for improved performance +### Misc + +- Fix signer for full nodes +- Improve logs for http servers +- Improve signer initialization for faster and more reliable transaction signing +- Add logs for previous activator on idleness checks +- Migrate zksync-go to go-ethereum + ### Bug fixes - Skip priming check for full nodes @@ -510,14 +561,6 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Fix bug in latest transaction with effect calculation - Fix wallet mutex using read lock instead of write lock when unlocking accounts -### Misc - -- Fix signer for full nodes -- Improve logs for http servers -- Improve signer initialization for faster and more reliable transaction signing -- Add logs for previous activator on idleness checks -- Migrate zksync-go to go-ethereum - ## v0.4.3 ### Bug fixes @@ -595,6 +638,19 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Store and expose genvm execution information - Add sign admin endpoint for genvm +### Misc + +- Simplify environment variable configuration using .env file +- Add environment variable override support for config values +- Update webdriver image to v0.0.9 +- Update RPC and WebSocket endpoints in config.yaml.example +- Correct status for validatorTimeout after appeal time window +- Validate presence of abigen in dependency check +- Rename environment validation functions for clarity +- Use cockroachdb errors package for error handling +- Remove wallet.yaml file handling +- Rename archive to full + ### Bug fixes - GenVM architecture on arm64 @@ -620,33 +676,20 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Accidental deadlock in genvm - Lazy validators commit order -### Misc - -- Simplify environment variable configuration using .env file -- Add environment variable override support for config values -- Update webdriver image to v0.0.9 -- Update RPC and WebSocket endpoints in config.yaml.example -- Correct status for validatorTimeout after appeal time window -- Validate presence of abigen in dependency check -- Rename environment validation functions for clarity -- Use cockroachdb errors package for error handling -- Remove wallet.yaml file handling -- Rename archive to full - ## v0.3.11 ### New features - Add validator telemetry push monitoring -### Bug fixes - -- Validator banning on parallel transactions executions - ### Misc - Document health RPC endpoint +### Bug fixes + +- Validator banning on parallel transactions executions + ## v0.3.10 ### New features @@ -802,17 +845,17 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Log file support for node - Ability to export private key in account command +### Misc + +- Updated module github.com/btcsuite/btcd to v0.24.2 (security) +- Improved sync speed on node startup + ### Bug fixes - Build info logs now display correctly - Fixed config relative path - Node now fails fast when accepted transaction processing fails -### Misc - -- Updated module github.com/btcsuite/btcd to v0.24.2 (security) -- Improved sync speed on node startup - ## v0.2.0-testnet005 ### New features @@ -849,12 +892,12 @@ v0.6 is a breaking release. It runs only against the v0.6 consensus contracts (r - Updated genvm to v0.0.16 +### Misc + +- Updated module golang.org/x/net to v0.38.0 (security) + ### Bug fixes - Log level is no longer ignored - Revived trie dumping and enhanced logging -- Always kill genvm modules - -### Misc - -- Updated module golang.org/x/net to v0.38.0 (security) \ No newline at end of file +- Always kill genvm modules \ No newline at end of file diff --git a/pages/validators/monitoring.mdx b/pages/validators/monitoring.mdx index 3c1da34f0..33e83f49a 100644 --- a/pages/validators/monitoring.mdx +++ b/pages/validators/monitoring.mdx @@ -147,7 +147,7 @@ HEALTHCHECK_AUTO_RESTART=true # Set SCRAPE_TARGETS_JSON in .env # docker compose --profile monitoring up -d alloy: - image: grafana/alloy:v1.20.1 + image: grafana/alloy:v1.21.2 init: true container_name: genlayer-node-alloy labels: diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index c79fbb0fc..eb1d02460 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -273,6 +273,7 @@ One full node can be shared between multiple validators. The optimal validator-t You should see a list like this ```sh + v0.6.0-rc.3 v0.6.0-rc.2 v0.6.0-rc.1 ``` @@ -281,7 +282,7 @@ One full node can be shared between multiple validators. The optimal validator-t 2. Download the packaged application ```sh copy - export version=v0.6.0-rc.2 # example target; confirm it is published and approved before use + export version=v0.6.0-rc.3 # example target; confirm it is published and approved before use base=https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${version} curl -fI "${base}/genlayer-node-linux-amd64-${version}.tar.gz" curl -fI "${base}/genlayer-node_${version}_SHA256SUMS" @@ -358,7 +359,9 @@ rollup: genlayerchainrpcurl: "TODO: Set your GenLayer Chain HTTP RPC URL here" # GenLayer Chain RPC URL genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain WebSocket RPC URL here" # GenLayer Chain WebSocket URL # An API key of the RPC provider never goes in these URLs or in this file: - # set it in the environment as GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY. + # set it in the environment as GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY, + # or, for a key that changes while the node runs, in a file named here: + # genlayerchainrpckeyfile: "/run/secrets/genlayer-rpc/key" # The node sends it in this header (default X-AccessKey): # genlayerchainrpckeyheader: "X-AccessKey" provider: "TODO: Set your GenLayer Chain provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. @@ -369,8 +372,22 @@ consensus: manifestpath: "configs/node/protocol-manifest.json" # Trusted producer protocol manifest for this deployment: save your network's manifest (from its documentation) at this path; a dev-env deploy places its own here too. Relative paths resolve against the node root. A mismatch with consensusaddress is refused at startup. chainid: "" # DECIMAL chain id this deployment was made on (not hex, no leading zeros). Held independently of the manifest so a manifest describing another deployment is caught. # genesis: 47930 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. + # sync_halt_block: 20000 # Node-local, full mode only; stop replay exactly here and keep RPC/ops serving. Zero disables. # chain_submit_buffer: "30s" # (Optional) Slack reserved at the end of each consensus step to submit the resulting on-chain tx (commit vote, reveal vote, proposed receipt) before the slot closes. Tune to underlying settlement chain latency. Default 30s. # admissiontimeout: "15s" # (Optional) Bound on the startup deployment admission check. Never unbounded. Default 15s. + # Cache of repeated transaction reads; on by default. A value read at a finalized + # block cannot change; one read above it can be replaced by a reorg, so it is kept + # shorter, and a detected reorg empties the cache. Tune with the + # genlayer_node_transaction_read_cache_* metrics. + # transaction_cache: + # enabled: true + # settled_ttl: 15m # values read at or below the finalized block + # unsettled_ttl: 30s # snapshots read above it + # unsettled_long_ttl: 10m # fee states and history answers read above it + # max_snapshots: 1024 + # max_fee_states: 1024 + # max_history: 4096 + # preload_workers: 5 # sync filter history preloads reading the chain at a time # data directory datadir: "./data/node" # logging configuration @@ -548,6 +565,15 @@ node: # # output, so its size is contract-controlled. Over the cap, the field is # # truncated and the cut is marked in-band. 0 takes the default. # max_debug_field_bytes: 262144 # 256 KB per field + # Contract-state history pruning; off by default (archive node). Past the + # window (chain time) the node keeps only the finalized state, so reads at + # older blocks fail. The window is raised at run time to the sum of + # the phase timeouts times the maximum rounds. Irreversible: read + # docs/deploy/state-pruning.md before enabling. + # state: + # enabled: false + # retention: 336h # two weeks + # sweep_interval: 10m # how often aged-out history is scheduled for pruning # genvm configuration genvm: root_dir: ./opt/genvm/v0.6.0-rc10 @@ -637,7 +663,8 @@ rollup: # The WebSocket refuses a connection without an API key. The chain is # operated by Conduit: create a key at https://app.conduit.xyz/rpc-keys and # set it in the environment as - # GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY, never in these URLs or this file. + # GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCKEY (or in the file that + # genlayerchainrpckeyfile names), never in these URLs or this file. # The node sends it in the X-AccessKey header on the RPC and WebSocket # connections. provider: "conduit" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics.