feat: include node account information in config score response by jstuczyn · Pull Request #6877 · nymtech/nym

jstuczyn · 2026-06-12T12:11:22Z

Factor on-chain account capability into node config score

Summary

A node's config score (used for rewarding and active-set selection) now accounts for whether the node's on-chain account can actually pay for transactions, i.e. it holds a sufficient token balance or is the grantee of a feegrant allowance. Nodes now advertise their on-chain address, nym-api queries each node's balance and feegrant status, and that capability flows into the config score and node annotations.

Changes

Nodes advertise their on-chain address

nym-node /api/v2/auxiliary now carries an address field; added get_auxiliary_details_v2 to the client.
Describe cache queries v2 auxiliary details (with the address) and falls back to v1 (no address) for older nodes.

New v3 described-node model family

Added described::v3 where NymNodeAuxiliaryDetailsV3 adds address: Option<String>. Describe cache now stores NymNodeDescriptionV3, with V3 -> V2 -> V1 conversions so existing v1/v2 endpoints keep working (downcast drops the address).

Feegrant query support in validator-client

New FeegrantQueryClient trait implementing the cosmos.feegrant.v1beta1.Query/Allowances ABCI query (not provided by cosmrs).

Chain-capability lookups in the node-status refresher

On refresh, nym-api queries on-chain balance and feegrant allowances for described nodes with a valid address.
Results live in an in-memory cache keyed by node id, each entry with its own TTL (default 24h) so lookups spread out instead of refreshing in one burst. Only successful lookups are cached; nodes with no address are skipped, and
failed/new nodes are retried next refresh rather than pinned to a stale false. Entries are pruned as nodes unbond.
Lookups are concurrency-limited (default 8) and use a dedicated query client so they don't block the signing client.

Config score / annotations

ConfigScore split into ConfigScoreV1 (unchanged) and ConfigScoreV2, which adds chain_interaction_capabilities (has_sufficient_tokens + is_fee_grant_grantee).
NodeAnnotationV2 gains chain_interaction_capabilities (on-chain balance + feegrant flag). V2 -> V1 downcasts provided.

New config knobs (NodeStatusAPIDebug)

minimum_on_chain_balance_amount (default 1 NYM)
chain_capabilities_retrieval_concurrency (default 8)
chain_capabilities_refresh_interval (default 24h)

Refactor

Dropped glob re-exports from models::described and network_monitor; callers now import from explicit described::{v1,v2,v3} / type_translation / models::v3 paths. Renamed AuxiliaryDetailsV1 -> NymNodeAuxiliaryDetailsV1.
Touches import sites across validator-client, verloc, topology, node-status-api, statistics-api, and the network-monitor orchestrator.

Notes

The feegrant check is intentionally coarse for now: any non-empty allowance counts, regardless of expiry or whether it covers a CosmWasm ExecuteMsg.

Summary by CodeRabbit

New Features
- V3 described-node models introduced.
- Feegrant allowances query and client helpers added.
- New methods to fetch chain details and obtain a query client.
Improvements
- Node scoring now factors per-node chain interaction (balance/feegrant).
- Cache refresher made asynchronous with selective chain-capability refresh; many node APIs migrated to V3 models.
Chores
- Import/re-export reorganization, config defaults adjustments, and log message spelling fix.

… self-described data

…lobal timer

vercel · 2026-06-12T12:11:28Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nym-explorer-v2	Ready	Preview, Comment	Jun 12, 2026 1:53pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs-nextra	Ignored	Preview	Jun 12, 2026 1:53pm

vercel · 2026-06-12T12:11:30Z

Deployment failed with the following error:

There is no GitHub account connected to this Vercel account.

coderabbitai · 2026-06-12T12:11:41Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Migrates described-node models to V3, adds feegrant query primitives and Nyxd chain-detail accessors, extends node-status scoring with per-node chain capability caching, converts the refresher to async startup, and updates consumers/routes/tests to use V3 types.

Changes

V2-to-V3 Node Description & Chain Capabilities Migration

Layer / File(s)	Summary
Feegrant Query Client Infrastructure `common/client-libs/validator-client/src/nyxd/cosmwasm_client/module_traits/feegrant/*`	Introduces feegrant module with `QueryAllowancesRequest`, `QueryAllowancesResponse`, `Grant` types; implements protobuf conversions and `FeegrantQueryClient` trait for async `allowances` queries via ABCI.
V3 Node Description Model Definitions `nym-api/nym-api-requests/src/models/described/v3.rs`	Defines `NymNodeDescriptionV3`, `NymNodeDataV3`, `NymNodeAuxiliaryDetailsV3` with type aliases, conversion methods, sphinx key rotation logic, port defaulting helpers, and test fixtures.
Auxiliary Details V1 Rename & V3 Conversions `nym-api/nym-api-requests/src/models/described/type_translation.rs`, `v1.rs`	Renames `AuxiliaryDetailsV1` → `NymNodeAuxiliaryDetailsV1`; adds `From` conversions to V3, mapping `address` appropriately.
V2 Auxiliary Details & Mock Cleanup `nym-api/nym-api-requests/src/models/described/v2.rs`	Introduces v2 aliases (`AnnouncePortsV2`, `NymNodeAuxiliaryDetailsV2`), removes older auxiliary alias and some semi-skimmed conversion helpers and mocks.
Chain Interaction Capabilities & Config Score V2 `nym-api/nym-api-requests/src/models/node_status.rs`	Adds `ChainInteractionCapabilitiesDetailed`, `ChainInteractionCapabilities`, `ConfigScoreV2` and `ConfigScoreV1`; updates `NodeAnnotationV2` and score conversion mapping.
NyxdClient Accessors & Chain Details Query `common/client-libs/validator-client/src/nyxd/mod.rs`, `nym-api/src/support/nyxd/mod.rs`	Adds `Config::chain_details()`, `Config::contracts()`, `NyxdClient::get_chain_details()`, and `Client::query_client()` accessors.
Described Node Cache Migration to V3 `nym-api/src/node_describe_cache/cache.rs`, `mod.rs`	Migrates `DescribedNodes` storage and accessors to V3 types and adds `NodeDescriptionTopologyExt` for V3.
Node Describe Cache Query Helpers V3 Migration `nym-api/src/node_describe_cache/query_helpers.rs`	Updates helper futures to produce V3 types; `auxiliary_details_future` attempts v2 endpoint then falls back to dedicated endpoint; intermediate structs now use V3 types.
Node Describe Refresh to V3 Models `nym-api/src/node_describe_cache/refresh.rs`	Converts refresh path to produce `NymNodeDescriptionV3`, updates signatures and construction accordingly.
Config Score V2 Calculation with Chain Validation `nym-api/src/node_status_api/cache/config_score.rs`	`calculate_config_score` now returns `ConfigScoreV2`, accepts `minimum_balance` and optional chain capabilities, and validates on-chain balances.
Chain Capabilities TTL Cache & Async Refresher `nym-api/src/node_status_api/cache/refresher.rs`	Introduces `ChainCapabilitiesCache`; converts refresher constructor to async; adds `refresh_chain_capabilities`, concurrent retrieval of balance+feegrant, and `retrieve_chain_capabilities` helper.
Node Status Cache Async Initialization `nym-api/src/node_status_api/mod.rs`, `nym-api/src/support/cli/run.rs`	Converts `start_cache_refresh` to async, derives `minimum_on_chain_balance` from chain client, and awaits refresher initialization.
Node Status API Config Extensions `nym-api/src/support/config/mod.rs`	Adds `minimum_on_chain_balance_amount`, `chain_capabilities_retrieval_concurrency`, `chain_capabilities_refresh_interval` to `NodeStatusAPIDebug` and default constants.
Network Monitor & Result Submitter V3 `nym-api/src/network_monitor/monitor/preparer.rs`, `nym-network-monitor-v3/*`	Preparer and orchestrator/storage consumers switch to V3 described-node and v3 stress-test/result models.
Nym Nodes Handlers V1/V2/V3 Versioning `nym-api/src/nym_nodes/handlers/*`	Separates v1/v2 imports; updates v2 handlers to use v2-specific types and `OutputParamsV2`; v3 stress-test imports consolidated.
Unstable Routes V2/V3 Semi-Skimmed Node Builders `nym-api/src/unstable_routes/*`	Moves semi-skimmed/skimmed builders to consume V3 described-node data; changes annotation extraction from `copied()` to `cloned()`.
Module Import Path Reorganization various `common/`, `nym-api/nym-api-requests/`, `tools/ts-rs-cli/*`	Replaces many glob re-exports with explicit submodule imports, updates sealed trait import targets, and narrows network_monitor exports.
Peripheral Topology & Verloc Updates `common/topology/src/node.rs`, `common/verloc/src/measurements/measurer.rs`, `nym-node/`, `nym-node-status-api/`, `nym-statistics-api/*`, `nym-api/src/support/caching/cache.rs`	Minor import reorganizations, API client addition `get_auxiliary_details_v2`, auxiliary-details type updates, and a small log-spelling fix.

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

nymtech/nym#6815: Related work introducing v2 auxiliary-details with address and the auxiliary v2 endpoint referenced by the new fallback logic.

Suggested reviewers

simonwicky
tommyv1987

"🐰 A rabbit's leap through versions new,

From V2's fields to V3 true,
With feegrants queried, balances checked,
Chain capabilities deeply tracked!
Async refreshes, caches aligned,
The finest node descriptions designed! ✨"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary feature change: adding node account/chain interaction information to the config score response, which is the main objective of this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/chain-account-config-score

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@nym-api/src/node_status_api/cache/refresher.rs`:
- Around line 357-359: The loop that calls
self.chain_capabilities.record(node_id, caps, now) is caching transient feegrant
RPC errors as a fresh "false" (is_feegrant_grantee = false); change the feegrant
query path to propagate errors (e.g., return Result/Option) instead of coercing
errors to false, and update the refresher to only call chain_capabilities.record
when the capability value is a definitive success/false (i.e., from an Ok
result), skipping or retrying when the query returned an Err/None so transient
RPC failures are not stored as a stale false; update the code paths around
is_feegrant_grantee and the fresh.into_inner() consumer to handle Result/Option
accordingly.
- Around line 304-328: When building to_query you currently skip nodes with
missing/invalid addresses but do not evict their stale entries from
self.chain_capabilities; update the logic so that whenever a node has no usable
address (the None branch of description.auxiliary_details.address or
AccountId::from_str fails) you call the chain_capabilities eviction API (e.g.
self.chain_capabilities.remove(node_id) or evict(node_id) depending on the
struct) to delete that node's cached capabilities; do this inside the closure
used by filter_map (or immediately after collecting invalid nodes) so stale
capabilities are removed as soon as an address is found unusable, keeping
retain_live and needs_refresh usage unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dd065450-0552-4c14-a36e-fcd8af28a87e

📥 Commits

Reviewing files that changed from the base of the PR and between b6eb391 and 7b8753e.

📒 Files selected for processing (42)

common/client-libs/validator-client/src/client.rs
common/client-libs/validator-client/src/nym_api/mod.rs
common/client-libs/validator-client/src/nyxd/cosmwasm_client/module_traits/feegrant/mod.rs
common/client-libs/validator-client/src/nyxd/cosmwasm_client/module_traits/feegrant/query.rs
common/client-libs/validator-client/src/nyxd/cosmwasm_client/module_traits/mod.rs
common/client-libs/validator-client/src/nyxd/mod.rs
common/topology/src/node.rs
common/verloc/src/measurements/measurer.rs
nym-api/nym-api-requests/src/models/described/mod.rs
nym-api/nym-api-requests/src/models/described/type_translation.rs
nym-api/nym-api-requests/src/models/described/v1.rs
nym-api/nym-api-requests/src/models/described/v2.rs
nym-api/nym-api-requests/src/models/described/v3.rs
nym-api/nym-api-requests/src/models/mod.rs
nym-api/nym-api-requests/src/models/network_monitor.rs
nym-api/nym-api-requests/src/models/node_status.rs
nym-api/nym-api-requests/src/nym_nodes.rs
nym-api/nym-api-requests/src/signable.rs
nym-api/src/network_monitor/monitor/preparer.rs
nym-api/src/node_describe_cache/cache.rs
nym-api/src/node_describe_cache/mod.rs
nym-api/src/node_describe_cache/query_helpers.rs
nym-api/src/node_describe_cache/refresh.rs
nym-api/src/node_status_api/cache/config_score.rs
nym-api/src/node_status_api/cache/refresher.rs
nym-api/src/node_status_api/mod.rs
nym-api/src/nym_nodes/handlers/v1.rs
nym-api/src/nym_nodes/handlers/v2.rs
nym-api/src/nym_nodes/handlers/v3.rs
nym-api/src/support/caching/cache.rs
nym-api/src/support/cli/run.rs
nym-api/src/support/config/mod.rs
nym-api/src/support/nyxd/mod.rs
nym-api/src/support/storage/models.rs
nym-api/src/unstable_routes/v2/nym_nodes/semi_skimmed/mod.rs
nym-api/src/unstable_routes/v2/nym_nodes/skimmed/helpers.rs
nym-api/src/unstable_routes/v3/nym_nodes/semi_skimmed/mod.rs
nym-network-monitor-v3/nym-network-monitor-orchestrator/src/orchestrator/result_submitter.rs
nym-network-monitor-v3/nym-network-monitor-orchestrator/src/storage/models.rs
nym-node-status-api/nym-node-status-api/src/db/models.rs
nym-node/nym-node-requests/src/api/client.rs
nym-statistics-api/src/network_view.rs

💤 Files with no reviewable changes (2)

nym-api/nym-api-requests/src/models/mod.rs
nym-api/nym-api-requests/src/models/network_monitor.rs

jstuczyn added 6 commits June 12, 2026 11:11

attempt to retrieve auxiliary details v2 from nym-nodes when fetching…

b9d96f3

… self-described data

using node's account balance for config score field

60261a0

added basic feegrant module allowances query

4e5dfcb

add query to check for feegrant inclusion

7a7a14f

nits

c248141

change chain capabilities refresh behaviour to not tie new nodes to g…

7b8753e

…lobal timer

jstuczyn added this to the Ziller - (mainnet release 7th july) milestone Jun 12, 2026

jstuczyn requested a review from simonwicky June 12, 2026 12:11

coderabbitai Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread nym-api/src/node_status_api/cache/refresher.rs Outdated

Comment thread nym-api/src/node_status_api/cache/refresher.rs

fix ts-rs-cli by deriving ts_rs::TS on new nym-api-requests types

c1dafce

vercel Bot deployed to Preview – nym-explorer-v2 June 12, 2026 12:50 View deployment

jstuczyn added 2 commits June 12, 2026 14:10

fix cache eviction if node loses its address

d74ae36

fix tools/nym-lp-client build

5f7ff27

vercel Bot deployed to Preview – nym-explorer-v2 June 12, 2026 13:16 View deployment

fix imports in nym-gateway-probe

7468f75

vercel Bot deployed to Preview – nym-explorer-v2 June 12, 2026 13:31 View deployment

vercel Bot deployed to Preview – nym-explorer-v2 June 12, 2026 13:40 View deployment

fix imports in NS API

eaa52f8

jstuczyn force-pushed the feat/chain-account-config-score branch from 59904d5 to eaa52f8 Compare June 12, 2026 13:52

vercel Bot deployed to Preview – nym-explorer-v2 June 12, 2026 13:53 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: include node account information in config score response#6877

feat: include node account information in config score response#6877
jstuczyn wants to merge 11 commits into
developfrom
feat/chain-account-config-score

jstuczyn commented Jun 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jstuczyn commented Jun 12, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Factor on-chain account capability into node config score

Summary

Changes

Notes

Summary by CodeRabbit

Uh oh!

vercel Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jstuczyn commented Jun 12, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jun 12, 2026 •

edited

Loading

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading