From 59c753eae800258de0d76e16bdf93b8d4191e5aa Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 30 Jul 2026 16:20:44 +0000 Subject: [PATCH 1/3] docs: Sync documentation from node repository v0.5.13 - Source: genlayerlabs/genlayer-node@v0.5.13 - Version: v0.5.13 - Total changes: 4 - Added: 1 files - Updated: 3 files - Deleted: 0 files --- content/validators/changelog/v0.5.13.mdx | 7 ++++ content/validators/config.yaml | 4 +- content/validators/greybox-setup-guide.md | 22 +++++++++++ pages/api-references/genlayer-node.mdx | 39 +++++++++++++++++++ .../genlayer-node/ops/health.mdx | 39 +++++++++++++++++++ pages/validators/changelog.mdx | 8 ++++ pages/validators/setup-guide.mdx | 8 ++-- 7 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 content/validators/changelog/v0.5.13.mdx diff --git a/content/validators/changelog/v0.5.13.mdx b/content/validators/changelog/v0.5.13.mdx new file mode 100644 index 000000000..bbd4e9998 --- /dev/null +++ b/content/validators/changelog/v0.5.13.mdx @@ -0,0 +1,7 @@ +## v0.5.13 + +### Bug fixes + +- Self-recover stalled sync gate +- Boot degraded when a module fails +- Stop dealing turns to non-actors diff --git a/content/validators/config.yaml b/content/validators/config.yaml index b4a46f828..487236428 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -43,7 +43,7 @@ node: mode: "validator" # Address of the ValidatorWallet contract (required for validator mode) validatorWalletAddress: "" - # Address of the operator that performs consensus duties for the ValidatorWallet + # Address of the operator that owns the ValidatorWallet operatorAddress: "" admin: port: 9155 @@ -148,6 +148,8 @@ node: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint + dev: + disableSubscription: false # Useful for testing with zksync-anvil # genvm configuration genvm: root_dir: ./third_party/genvm diff --git a/content/validators/greybox-setup-guide.md b/content/validators/greybox-setup-guide.md index b71bf00d2..d690436f5 100644 --- a/content/validators/greybox-setup-guide.md +++ b/content/validators/greybox-setup-guide.md @@ -174,4 +174,26 @@ After editing the YAML, restart the LLM module (see "Updating Greybox on a Runni **All models exhausted error:** - OpenRouter may be down or your key is invalid - Check your key at https://openrouter.ai/settings/keys +- Run `task node:doctor` — the "LLM Providers" section probes each enabled backend and reports which ones actually answer, rather than only whether a key variable is set - Fallback providers (heurist, ionet) also need valid keys if you want fallback to work + +## No usable LLM backend: the node starts DEGRADED + +A node with no working LLM backend no longer refuses to start. It boots, syncs and +stays in the validator set, but it votes **Timeout** on every transaction that +needs an LLM, logs a loud alert naming the broken module, and reports +`genvm_modules.llm.state = "degraded"` on ops `/health` while `status` stays +`"up"`. That is better than the old behaviour — the node used to exit about 75 +seconds after start and then be banned for idleness — but it is **not** a working +validator: Timeout votes are penalized. Treat it as a failure to fix, not a state +to run in. The same applies to the web module when the webdriver is unreachable. + +Recovery is automatic once a provider answers again — the node learns from its own +transaction traffic and needs no restart. The **one exception** is a key added to +`.env`: the node reads its environment at exec, so a running process cannot pick +that up. Restart it. Editing `genvm-module-llm.yaml` does not require a restart. + +**Configure more than one provider.** A backend only enters the fallback chain if +its key is set, so a node set up with OpenRouter alone has no fallback: when that +provider goes down or is decommissioned, the chain exhausts immediately. `doctor` +warns when only one backend is usable. diff --git a/pages/api-references/genlayer-node.mdx b/pages/api-references/genlayer-node.mdx index 9c79a3a17..5f1091159 100644 --- a/pages/api-references/genlayer-node.mdx +++ b/pages/api-references/genlayer-node.mdx @@ -1126,6 +1126,18 @@ curl -X GET http://localhost:9153/health "status": "up", "node_version": "v1.2.3", "protocol_version": "consensus-v2.1", + "genvm_modules": { + "llm": { + "state": "healthy", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T10:30:45Z" + }, + "web": { + "state": "healthy", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T10:30:45Z" + } + }, "checks": { "test-check": { "status": "up", @@ -1140,12 +1152,39 @@ curl -X GET http://localhost:9153/health - `status` (string): Overall health status - "up" if all checks pass, "down" if any check fails - `node_version` (string): The version of the GenLayer node software - `protocol_version` (string): The consensus protocol version +- `genvm_modules` (object): Per-module GenVM health — whether this node can currently do LLM and web work. Reported for `llm` and `web`. + - `state` (string): `healthy`, `suspect`, `degraded`, or `unknown`. `suspect` means one failure has been observed and is not yet treated as confirmed; `unknown` means the module has not been exercised yet. + - `timestamp` (string, optional): ISO 8601 time the verdict was last updated. Absent until the module is first observed. + - `last_ok` (string, optional): ISO 8601 time the module last answered successfully. Absent if it never has. + - `detail` (string, optional): the module's own error text. Present only while not healthy. - `checks` (object, optional): Map of individual health check results - `[check-name]` (object): Results for a specific health check - `status` (string): Check status - "up" or "down" - `timestamp` (string): ISO 8601 timestamp of when the check was performed - `error` (string, optional): Error message if check failed +**GenVM module health does not affect `status`.** + +A node with a broken module is still booted, synced and voting — it votes Timeout on the transactions that need that module, which is the designed degraded behaviour rather than an outage. Failing the endpoint would pull a working validator out of load balancers and page an operator about a node behaving as intended. So `genvm_modules` is reported alongside `checks` rather than as one of them, and `status` stays `up`: + +```json +{ + "status": "up", + "genvm_modules": { + "llm": { + "state": "degraded", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T04:12:03Z", + "detail": "provider unreachable — voting Timeout on transactions that need an LLM" + }, + "web": { "state": "healthy", "timestamp": "2024-01-15T10:30:45Z", "last_ok": "2024-01-15T10:30:45Z" } + } +} +``` + +`timestamp` and `last_ok` answer different questions and are both reported. `timestamp` is when the verdict was last updated; `last_ok` is when the module last worked. They match while healthy, and the gap between them while degraded shows how long the outage has run. `timestamp` matters more here than under `checks`: those entries are re-evaluated on every request, whereas module state is folded from real transaction traffic and is not polled while healthy — so on a quiet validator a `healthy` verdict can rest on an older observation. + + **HTTP Status Codes:** - `200 OK`: Node is healthy (all checks passing) diff --git a/pages/api-references/genlayer-node/ops/health.mdx b/pages/api-references/genlayer-node/ops/health.mdx index cba05433c..6b86402d6 100644 --- a/pages/api-references/genlayer-node/ops/health.mdx +++ b/pages/api-references/genlayer-node/ops/health.mdx @@ -21,6 +21,18 @@ curl -X GET http://localhost:9153/health "status": "up", "node_version": "v1.2.3", "protocol_version": "consensus-v2.1", + "genvm_modules": { + "llm": { + "state": "healthy", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T10:30:45Z" + }, + "web": { + "state": "healthy", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T10:30:45Z" + } + }, "checks": { "test-check": { "status": "up", @@ -35,12 +47,39 @@ curl -X GET http://localhost:9153/health - `status` (string): Overall health status - "up" if all checks pass, "down" if any check fails - `node_version` (string): The version of the GenLayer node software - `protocol_version` (string): The consensus protocol version +- `genvm_modules` (object): Per-module GenVM health — whether this node can currently do LLM and web work. Reported for `llm` and `web`. + - `state` (string): `healthy`, `suspect`, `degraded`, or `unknown`. `suspect` means one failure has been observed and is not yet treated as confirmed; `unknown` means the module has not been exercised yet. + - `timestamp` (string, optional): ISO 8601 time the verdict was last updated. Absent until the module is first observed. + - `last_ok` (string, optional): ISO 8601 time the module last answered successfully. Absent if it never has. + - `detail` (string, optional): the module's own error text. Present only while not healthy. - `checks` (object, optional): Map of individual health check results - `[check-name]` (object): Results for a specific health check - `status` (string): Check status - "up" or "down" - `timestamp` (string): ISO 8601 timestamp of when the check was performed - `error` (string, optional): Error message if check failed +**GenVM module health does not affect `status`.** + +A node with a broken module is still booted, synced and voting — it votes Timeout on the transactions that need that module, which is the designed degraded behaviour rather than an outage. Failing the endpoint would pull a working validator out of load balancers and page an operator about a node behaving as intended. So `genvm_modules` is reported alongside `checks` rather than as one of them, and `status` stays `up`: + +```json +{ + "status": "up", + "genvm_modules": { + "llm": { + "state": "degraded", + "timestamp": "2024-01-15T10:30:45Z", + "last_ok": "2024-01-15T04:12:03Z", + "detail": "provider unreachable — voting Timeout on transactions that need an LLM" + }, + "web": { "state": "healthy", "timestamp": "2024-01-15T10:30:45Z", "last_ok": "2024-01-15T10:30:45Z" } + } +} +``` + +`timestamp` and `last_ok` answer different questions and are both reported. `timestamp` is when the verdict was last updated; `last_ok` is when the module last worked. They match while healthy, and the gap between them while degraded shows how long the outage has run. `timestamp` matters more here than under `checks`: those entries are re-evaluated on every request, whereas module state is folded from real transaction traffic and is not polled while healthy — so on a quiet validator a `healthy` verdict can rest on an older observation. + + **HTTP Status Codes:** - `200 OK`: Node is healthy (all checks passing) diff --git a/pages/validators/changelog.mdx b/pages/validators/changelog.mdx index a2ccf0ca7..1ccb558b5 100644 --- a/pages/validators/changelog.mdx +++ b/pages/validators/changelog.mdx @@ -1,5 +1,13 @@ # Changelog +## v0.5.13 + +### Bug fixes + +- Self-recover stalled sync gate +- Boot degraded when a module fails +- Stop dealing turns to non-actors + ## v0.5.12 ### Misc diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 7a82fb119..0868e89ad 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -216,18 +216,18 @@ One full node can be shared between multiple validators. The optimal validator-t You should see a list like this ```sh + v0.5.13 v0.5.12 v0.5.11 v0.5.10 v0.5.9 - v0.5.8 ``` Typically, you will want to run the latest version 2. Download the packaged application ```sh copy - export version=v0.5.12 # set your desired version here + export version=v0.5.13 # set your desired version here wget https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${version}/genlayer-node-linux-amd64-${version}.tar.gz ``` 3. Extract the node software @@ -311,7 +311,7 @@ node: mode: "validator" # Address of the ValidatorWallet contract (required for validator mode) validatorWalletAddress: "" - # Address of the operator that performs consensus duties for the ValidatorWallet + # Address of the operator that owns the ValidatorWallet operatorAddress: "" admin: port: 9155 @@ -416,6 +416,8 @@ node: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint + dev: + disableSubscription: false # Useful for testing with zksync-anvil # genvm configuration genvm: root_dir: ./third_party/genvm From ccba955c0551484ff1dfb916bafc9c27924f59ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darien=20Hern=C3=A1ndez=20Gonz=C3=A1lez?= Date: Thu, 30 Jul 2026 18:25:10 +0200 Subject: [PATCH 2/3] Remove dev in config.yaml --- content/validators/config.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 487236428..991c8b5a3 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -148,8 +148,6 @@ node: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint - dev: - disableSubscription: false # Useful for testing with zksync-anvil # genvm configuration genvm: root_dir: ./third_party/genvm From ee483bbfa1532a2646c3801ff740180bb03d5d15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darien=20Hern=C3=A1ndez=20Gonz=C3=A1lez?= Date: Thu, 30 Jul 2026 18:25:41 +0200 Subject: [PATCH 3/3] remove dev setup-guide.mdx --- pages/validators/setup-guide.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 0868e89ad..78e639a48 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -416,8 +416,6 @@ node: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint - dev: - disableSubscription: false # Useful for testing with zksync-anvil # genvm configuration genvm: root_dir: ./third_party/genvm