From b9cd444bb6f184aa614a6f6a508bd22f52e5291f Mon Sep 17 00:00:00 2001 From: Ali EL BROUDI Date: Wed, 26 Aug 2026 12:05:36 +0200 Subject: [PATCH] Document CRN-specific scoring rules Add an "Additional rules for Compute Resource Nodes" section to the scoring page covering the CRN-only checks: IP stability (static IPv4/IPv6 and a limit of 2 address changes over a rolling 30-day window, with IPv6 keyed to the VM address pool), one scored node per machine (duplicate IPv4/IPv6-pool handling), and liveness status (active/inactive/dead). Include the diagnostic code table and a note that the rules are rolled out progressively with warning codes before they affect the score. --- docs/nodes/resources/scoring/index.md | 77 +++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/nodes/resources/scoring/index.md b/docs/nodes/resources/scoring/index.md index b8ccdc0..2bf8eb0 100644 --- a/docs/nodes/resources/scoring/index.md +++ b/docs/nodes/resources/scoring/index.md @@ -68,6 +68,83 @@ Meanwhile, $m1$ and $m2$ serve as proportional multipliers to ensure the total r The $tuning$ a number tuned such that most nodes have a score between `80%` and `100%`.
+## Additional rules for Compute Resource Nodes + +Beyond the performance score above, [Compute Resource Nodes](/nodes/compute/introduction/) +(CRNs) must meet a few requirements that reflect how they are actually used to host +workloads. These rules are specific to CRNs and do not apply to Core Channel Nodes. + +Whenever one of these rules applies, a numeric **diagnostic code** is published on the +node's score so operators can see the problem and fix it. + +::: info +These rules are being rolled out progressively. During the initial phase a node may +receive a diagnostic code as a **warning** before the rule affects its score, so +operators have time to react. Watch the codes on your node's score. +::: + +### Stable IP addresses + +A CRN is expected to keep a stable IPv4 address and a stable IPv6 range. Instances +scheduled on a node are reached through its addresses, so an address that is missing or +changes frequently breaks connectivity to the node and to the VMs it hosts. + +Over a rolling **30-day window**, a node is flagged when: + +- it has no static IPv4 address, or +- it has no static IPv6 range, or +- its IPv4 address changes **2 or more times**, or +- its IPv6 range changes **2 or more times**. + +For IPv6 the check looks at the node's VM address pool (`IPV6_ADDRESS_POOL`, reported by +the node at `/status/config`), not the node's own access address. Some providers give the +node one IPv6 for management and route a separate range for VMs, so the pool is the range +that matters for hosting. + +Because the window is rolling, the flag clears on its own: once the changes are more than +30 days old and the node has kept a stable address, the node is no longer penalized and +its score recovers. This window is separate from the two-year window used for the +performance score above. + +### One scored node per machine + +Only one CRN is scored per underlying machine. When several CRNs present the **same IPv4 +address** or the **same IPv6 pool**, only one keeps its score — the node that proves its +own identity (see [Liveness](#liveness-active-inactive-dead)), or otherwise the +earliest-registered one — and the others are set to `0`. This prevents a single machine +from being registered many times to collect rewards more than once. + +::: warning +If you legitimately run behind a shared IPv4 (NAT, reverse proxy), your node may be +grouped with others. Check the published codes and reach out before this affects you. +::: + +### Liveness (active / inactive / dead) + +Each CRN is given a status based on whether it has recently proven that it is a real, +working CRN — by answering the diagnostic VM, serving its own identity at +`/status/config`, or reporting a valid `aleph-vm` version: + +- **active** — the node is currently proving it is a CRN. +- **inactive** — the node has stopped proving it right now, but did so within the last 24 hours. +- **dead** — the node has not proven it is a CRN for more than 24 hours; its score is set to `0`. + +This is separate from the slow performance score above: a machine that stops being a CRN +(for example, an IP reassigned to a plain web server) is caught within a day instead of +keeping a positive score for about a week. + +### Diagnostic codes + +| Code | Meaning | +| ---- | ------- | +| 1001 | No IPv4 address observed | +| 1002 | No IPv6 range observed | +| 1003 | IPv4 address changed too many times | +| 1004 | IPv6 range changed too many times | +| 1005 | Shares an IPv4 address or IPv6 range with an older node | +| 1006 | No proof of being a CRN for 24 hours (treated as dead) | +| 1007 | Not currently proving it is a CRN | + ## Publishing Scores are published as a POST message on aleph.cloud, with the type `aleph-scoring-scores`.