Feature/sma 4 add nominator pool support by mrnkslv · Pull Request #39 · RSquad/ton-rust-node

mrnkslv · 2026-03-31T07:51:19Z

Summary

Add support for the TON Nominator Pool (kind: "core" / PoolConfig::TONCore) alongside existing Single Nominator Pool: deploy-time parameters resolved in contracts, shared elector opcodes with SNP, and CLI/service integration for pool config, deploy, wallet stake resolution, and runtime pool loading.
Add TONCoreRouter (kind: "core_router" / PoolConfig::TONCoreRouter) — a dual-pool extension of TONCore that manages two pools (pool[1] differs by min_validator_stake + 1), automatically routes stakes to the free pool via get_pool_data().state == 0, recovers from both, and enables uninterrupted validation across election rounds.

Changes

contracts/src/ton_core_nominator/ — NominatorPoolWrapperImpl (embedded pool code, build_state_init / calculate_address / from_init_data), get_pool_data / get_roles, resolve_deploy_pool_params + defaults
contracts/src/ton_core_nominator/messages.rs— pool-specific opcodes and message builders: new_stake, recover_stake, deposit_validator, withdraw_validator (+ unit tests on cells)
contracts/src/ton_core_nominator/ton_core_nominator.rs — resolve_toncore_pool (single pool), resolve_toncore_router (two pools with min_validator_stake + 1 for pool[1])
contracts/src/nominator/wrapper.rs — NodePools enum (Single / Router) with primary(), all(), select_free() methods; select_free() queries on-chain pool state for Router
contracts/src/nominator/single_nominator.rs — extracted new_with_state_init constructor
contracts/src/lib.rs, ton_core_nominator.rs — module wiring and re-exports
common/src/app_config.rs — TONCore and TONCoreRouter variants with optional deploy fields (max_nominators, min_* stakes, addresses: Option<[Option; 2]>), serde tests for all variants
commands/.../config_pool_cmd.rs — config pool add --kind core|router, --address-0/--address-1 for Router (rejects --address), pool ls table for Core/Router, deposit-validator/withdraw-validator with --pool-index
commands/.../config_wallet_cmd.rs — wallet stake with --pool-index for Router target selection; resolve_pool_address handles all pool types
commands/.../deploy_cmd.rs — deploy TONCore / TONCoreRouter (sequential multi-target deploy with seqno increment); SNP unchanged
commands/.../config_cmd.rs — pass CancellationCtx to pool subcommands for deposit-validator / withdraw-validator
elections/src/runner.rs — resolve_staking_target() picks the free pool once per tick, consistent across calc_stake, send_stake, and elector signature; recover_stake iterates all pools with per-tx gas tracking; snapshots use all_staking_addresses() for Router matching
elections/src/runner_tests.rs — 4 Router-specific tests: free pool selection, both-busy error, dual recovery, finished-elections matching on either pool address
elections/src/election_task.rs — pool type updated to HashMap<String, NodePools>
service/src/runtime_config.rs — open_nominator_pool returns NodePools::Single or NodePools::Router; pools stored as HashMap<String, NodePools>
service/src/contracts/contracts_task.rs — ensure_pools_deployed iterates node_pools.all() for multi-pool deployment
-service/src/task/task_manager.rs — NoopRuntimeConfig::pools() returns empty HashMap
service/src/auth/user_store.rs — updated mock pools() return type
README.md — pools schema for core and core_router

Closes SMA-4

linear · 2026-03-31T07:51:22Z

SMA-4 Add Nominator Pool support

Copilot

Pull request overview

This PR adds support for the TON Nominator Pool (also called TONCore pool or pool-core) to the node control system. Previously, only Single Nominator Pools (SNP) were supported. The implementation includes contract wrappers for pool interaction, message builders for pool operations, configuration support with optional deployment parameters, and CLI commands for pool management.

Changes:

Added NominatorPoolWrapperImpl wrapper for interacting with deployed TON Nominator Pools
Implemented pool contract state initialization with support for configurable deployment parameters (max nominators, min stakes)
Added message builders for pool operations (accept coins, process withdrawals, update validator set, etc.)
Extended configuration to support TONCore pools with optional deploy-time parameters
Updated deployment commands to support deploying TON Nominator Pools alongside SNP
Added configuration commands for managing core pools in the CLI
Updated documentation with TONCore pool configuration details

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/node-control/contracts/src/ton_core_nominator/	New module implementing nominator pool wrapper and message builders with comprehensive tests
src/node-control/service/src/runtime_config.rs	Added support for opening TONCore pools during runtime configuration
src/node-control/common/src/app_config.rs	Extended PoolConfig enum with TONCore variant including optional deployment parameters, with serialization tests
src/node-control/commands/src/commands/nodectl/deploy_cmd.rs	Updated pool deployment command to handle both SNP and TONCore pools
src/node-control/commands/src/commands/nodectl/config_wallet_cmd.rs	Added TONCore pool support for manual stake operations
src/node-control/commands/src/commands/nodectl/config_pool_cmd.rs	Added CLI commands for managing core pools with dedicated configuration options
src/node-control/contracts/src/lib.rs	Exported new nominator pool types and functions
src/node-control/README.md	Updated documentation for TONCore pool configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/node-control/README.md

src/node-control/common/src/app_config.rs

Made-with: Cursor

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Keshoid · 2026-04-01T07:57:29Z

src/node-control/commands/src/commands/nodectl/config_wallet_cmd.rs

+            min_nominator_stake,
+        } => {
+            let configured_validator =
+                addresses[0].parse::<MsgAddressInt>().context("invalid TONCore addresses[0]")?;


use with_context(|| format!("invalid pool address: {}", addresses[0]))

Keshoid · 2026-04-01T07:59:16Z

src/node-control/commands/src/commands/nodectl/config_wallet_cmd.rs

+            min_validator_stake,
+            min_nominator_stake,
+        } => {
+            let configured_validator =


Why it is called `XXX_validator? It's a pool address, isn't it?

Keshoid · 2026-04-01T08:03:06Z

src/node-control/commands/src/commands/nodectl/config_pool_cmd.rs

    owner: Option<String>,
+    #[arg(long = "addr1", help = "Core: addresses[0] (with --kind core)")]
+    addr1: Option<String>,
+    #[arg(long = "addr2", help = "Core: addresses[1] (with --kind core)")]


Use a clear description for that option.

Keshoid · 2026-04-01T09:30:17Z

src/node-control/commands/src/commands/nodectl/deploy_cmd.rs

+                if validator_addr != wallet_address {
+                    return Err(set_err(anyhow::anyhow!(
+                        "TONCore addresses[0] must match this node's wallet (expected {}, config has {})",
+                        wallet_address,


Design issue: addresses[0] is not the validator wallet.

Both addresses[0] and addresses[1] should be pool contract addresses (for even/odd validation rounds, as pool.fc itself notes: "The validator in most cases have two pools").

The validator wallet address is already available from the wallets config section via the node binding — no need to store it in the pool config.

This same wrong assumption (addresses[0] == validator wallet) is repeated in runtime_config.rs:525-531 and config_wallet_cmd.rs:716-722.

Fix: get the validator address from the wallet config (already resolved as wallet_address here), and treat both addresses[0] and addresses[1] as the two pool contract addresses. Derive/validate both against (wallet_address, validator_share, deploy_params).

Keshoid · 2026-04-01T09:30:28Z

src/node-control/README.md

+- `validator_share` — validator reward share (basis points; stored as `u16` on-chain)
+- `max_nominators` — optional; if omitted, defaults from the contracts module are used (40 nominators)
+- `min_validator_stake` — optional (nanotons); if omitted, defaults from the contracts module are used (100 TON)
+- `min_nominator_stake` — optional (nanotons); if omitted, defaults from the contracts module are used (10 TON)


Bug: defaults are off by 1000x.

DEFAULT_DEPLOY_MIN_VALIDATOR_STAKE_NANOTONS: u64 = 100_000_000_000_000; // = 100,000 TON DEFAULT_DEPLOY_MIN_NOMINATOR_STAKE_NANOTONS: u64 = 10_000_000_000_000; // = 10,000 TON

The README says 100 TON / 10 TON but the actual code defaults are 100,000 TON / 10,000 TON. This will mislead operators who skip the optional fields.

Keshoid · 2026-04-01T09:30:38Z

src/node-control/contracts/src/ton_core_nominator/messages.rs

+/// Validator sends coins to increase their own stake in the pool.
+/// Attach the desired amount of TON to the message; 1 TON is deducted as a processing fee.
+pub fn deposit_validator(query_id: u64) -> anyhow::Result<Cell> {
+    let mut builder = BuilderData::new();


Missing integration: deposit_validator / withdraw_validator are defined but never wired to any CLI command or automated flow.

After deployment, the pool starts with validator_amount = 0. The pool contract will reject every new_stake at:

throw_unless(83, validator_amount >= min_validator_stake); // 0 >= 100K TON → FAIL

Without a CLI command (e.g. nodectl wallet deposit-validator) or automated deposit step, the pool is deployed but cannot participate in elections. This is a blocker for the feature.

Keshoid · 2026-04-01T09:30:51Z

src/node-control/contracts/src/ton_core_nominator/ton_core_nominator.rs

+                max_nominators_count,
+                min_validator_stake,
+                max_nominators_stake: min_nominator_stake,
+            },


Confusing field reuse. max_nominators_stake (from the SNP model) stores min_nominator_stake for TONCore — semantically opposite names.

Anyone consuming PoolData downstream will read max_nominators_stake and assume it means a maximum, not a minimum. Consider renaming the shared field or adding a method that returns the correct semantic value per pool kind.

Keshoid · 2026-04-01T09:31:02Z

src/node-control/common/src/app_config.rs

+    TONCore {
+        addresses: [String; 2],
+        validator_share: u64,
+        /// Deploy-time pool parameters; if omitted, defaults are applied in `contracts` (`resolve_deploy_pool_params`).


Loose typing. validator_share is u64 here but must fit u16 on-chain (pool.fc stores it as store_uint(validator_reward_share, 16), range 0..=10000 basis points).

Every use site does u16::try_from(*validator_share) — a value like 70000 is accepted at config parse time but fails at deploy/runtime. Using u16 directly (or a serde deserialize validator) would catch this earlier.

Keshoid · 2026-04-01T09:31:14Z

src/node-control/commands/src/commands/nodectl/config_pool_cmd.rs

    )]
    owner: Option<String>,
+    #[arg(long = "addr1", help = "Core: addresses[0] (with --kind core)")]
+    addr1: Option<String>,


Unclear naming. --addr1 / --addr2 with help text addresses[0] / addresses[1] does not tell the operator what these addresses represent.

Since both should be pool contract addresses (for even/odd validation rounds), consider naming them --pool-addr-even / --pool-addr-odd or at minimum documenting what they are in the help text.

Keshoid · 2026-04-01T09:35:32Z

src/node-control/service/src/runtime_config.rs

+            min_nominator_stake,
+        } => {
+            let configured_validator = MsgAddressInt::from_str(addresses[0].as_str())
+                .context(format!("invalid TONCore addresses[0]: {}", addresses[0]))?;


Copy-paste: this ~25-line block is duplicated in 3 files.

The same sequence — parse addresses[0], validate against validator, convert validator_share to u16, call resolve_deploy_pool_params, call calculate_address, validate addresses[1] — is repeated in:

deploy_cmd.rs:330-367

runtime_config.rs:522-556 (here)

config_wallet_cmd.rs:710-746

Only the post-validation action differs (deploy / open wrapper / return address). Consider extracting a helper into the contracts crate, e.g.:

pub fn resolve_toncore_pool( config: &PoolConfig::TONCore, validator_addr: &MsgAddressInt, ) -> anyhow::Result<(MsgAddressInt, u16, u16, u64, u64)>

that validates addresses, converts types, resolves defaults, and returns the resolved params.

Keshoid · 2026-04-01T09:35:43Z

src/node-control/commands/src/commands/nodectl/deploy_cmd.rs

+                )
+                .map_err(set_err)?;
+                let state_init = NominatorPoolWrapperImpl::build_state_init(
+                    &validator_addr,


Redundant work: build_state_init is called twice with the same arguments.

calculate_address (line 354) already calls build_state_init internally to hash the StateInit into an address. Then build_state_init is called again here with identical parameters.

Use from_init_data instead (which stores both the address and the StateInit), or add a method that returns (MsgAddressInt, StateInit) in one pass.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T15:16:05Z

src/node-control/README.md

+- `max_nominators` — optional; if omitted, defaults from the contracts module are used (40 nominators)
+- `min_validator_stake` — optional (nanotons); if omitted, defaults from the contracts module are used (100,000 TON)
+- `min_nominator_stake` — optional (nanotons); if omitted, defaults from the contracts module are used (10,000 TON)



The README documentation is incomplete and inaccurate for the pools section. Line 1341 states "Two pool types are supported" but the implementation now supports three: SNP, TONCore, and TONCoreRouter. Additionally, the TONCore documentation at line 1352 incorrectly states "addresses — two addresses: validator wallet ([0]) and pool contract ([1]...)" but the actual PoolConfig::TONCore only has a single address: Option<String> field. The variant with two addresses is PoolConfig::TONCoreRouter. The section is also missing complete documentation for the TONCoreRouter variant, which should document the addresses: Option<[Option<String>; 2]> field and explain how the router automatically selects free pools.

mrnkslv added 4 commits March 30, 2026 02:26

feat: added messages for ton_core_nominator

2d760d3

feat(core np): added NominatorPoolWrapperImpl

341f407

feat(core np): created mod ton_core_nominator

113d706

feat(core np): configs done

175b02f

Copilot AI review requested due to automatic review settings March 31, 2026 07:51

Copilot started reviewing on behalf of mrnkslv March 31, 2026 07:51 View session

feat: formatting

6396945

Copilot AI reviewed Mar 31, 2026

View reviewed changes

src/node-control/README.md Outdated Show resolved Hide resolved

src/node-control/common/src/app_config.rs Show resolved Hide resolved

mrnkslv and others added 3 commits March 31, 2026 11:02

feat: crates format updated

88aa686

Made-with: Cursor

Update src/node-control/README.md

b52f03d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/node-control/common/src/app_config.rs

a4f0123

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

mrnkslv requested review from a team, ITBear, Keshoid and Lapo4kaKek and removed request for a team March 31, 2026 10:28

Keshoid reviewed Apr 1, 2026

View reviewed changes

Keshoid requested changes Apr 1, 2026

View reviewed changes

mrnkslv added 3 commits April 2, 2026 14:54

fix: fixes according to comments

9bdb165

feat(core np):add opportunity to use 2 pools

670c665

feat: implement logic ton core nominator with 1 pool

296c9f0

mrnkslv added 2 commits April 3, 2026 12:45

feat: ton_core_router implementation

380dd39

feat: upd binding options

4b760de

mrnkslv requested a review from Copilot April 3, 2026 15:12

Copilot started reviewing on behalf of mrnkslv April 3, 2026 15:13 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

mrnkslv added 2 commits April 3, 2026 18:27

feat(documentation): readme updated

4ed3c75

fix: return correct index for snp

3cbbc81

Conversation

mrnkslv commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

linear bot commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mrnkslv commented Mar 31, 2026 •

edited

Loading