feat(scripts): add wallet-operator mapper for consolidation analysis #3840

lrsaturnino · 2025-10-27T03:19:39Z

Add comprehensive wallet-operator mapping toolset for beta staker consolidation analysis. Enables identification of wallets containing deprecated operators and BTC distribution calculations.

Core functionality:

query-dkg-events.js: Extracts operator membership from on-chain DKG events
analyze-per-operator.js: Calculates BTC distribution by provider
validate-operator-list.js: Verifies operator list completeness

Configuration:

operators.json: Defines KEEP (4 active) vs DISABLE (16 deprecated) operators
Contract ABIs for Bridge and WalletRegistry interactions
Archive node RPC support for historical event queries

Documentation:

README: Usage guide and integration points
Manual sweep procedures and execution scripts
Operator consolidation communication guidelines

Integration:

Provides data source for monitoring dashboard
Supports draining progress assessment
Enables manual sweep decision-making

Technical details:

Uses threshold cryptography (51/100 signatures)
Queries sortition pool for operator address resolution
Classifies operators by provider (STAKED, P2P, BOAR, NUCO)

Add comprehensive wallet-operator mapping toolset for beta staker consolidation analysis. Enables identification of wallets containing deprecated operators and BTC distribution calculations. Core functionality: - query-dkg-events.js: Extracts operator membership from on-chain DKG events - analyze-per-operator.js: Calculates BTC distribution by provider - validate-operator-list.js: Verifies operator list completeness Configuration: - operators.json: Defines KEEP (4 active) vs DISABLE (16 deprecated) operators - Contract ABIs for Bridge and WalletRegistry interactions - Archive node RPC support for historical event queries Documentation: - README: Usage guide and integration points - Manual sweep procedures and execution scripts - Operator consolidation communication guidelines Integration: - Provides data source for monitoring dashboard - Supports draining progress assessment - Enables manual sweep decision-making Technical details: - Uses threshold cryptography (51/100 signatures) - Queries sortition pool for operator address resolution - Classifies operators by provider (STAKED, P2P, BOAR, NUCO)

piotr-roslaniec · 2025-10-27T19:23:02Z

scripts/wallet-operator-mapper/validate-operator-list.js

+const path = require('path');
+
+const MAPPING_FILE = path.join(__dirname, 'wallet-operator-mapping.json');
+const CSV_PATH = '/Users/leonardosaturnino/Documents/GitHub/memory-bank/20250809-beta-staker-consolidation/knowledge/threshold_stakers_may_2025.csv';


Should we commit this file to the repo?

Fixed in commit hash 6461451

piotr-roslaniec · 2025-10-27T19:38:10Z

scripts/wallet-operator-mapper/query-dkg-events.js

+}
+
+// File paths
+const PROOF_OF_FUNDS_PATH = '/Users/leonardosaturnino/Documents/GitHub/memory-bank/20250809-beta-staker-consolidation/knowledge/20251006-tbtc-proof-of-funds.json';


Should we commit this file to the repo?

Fixed in commit hash 6461451

piotr-roslaniec · 2025-10-27T19:41:10Z

scripts/wallet-operator-mapper/analyze-per-operator.js

+  if (providerShares[data.provider]) {
+    if (data.status === 'KEEP') {
+      providerShares[data.provider].keep += data.totalShare;
+      providerShares[data.provider].keepWallets = data.walletCount;


Are we sure this is = and not +=?

Suggested change

providerShares[data.provider].keepWallets = data.walletCount;

providerShares[data.provider].keepWallets += data.walletCount;

Fixed in commit hash 6461451

piotr-roslaniec · 2025-10-27T19:41:35Z

scripts/wallet-operator-mapper/analyze-per-operator.js

+      providerShares[data.provider].keepWallets = data.walletCount;
+    } else {
+      providerShares[data.provider].disable += data.totalShare;
+      providerShares[data.provider].disableWallets = data.walletCount;


Ditto

Suggested change

providerShares[data.provider].disableWallets = data.walletCount;

providerShares[data.provider].disableWallets += data.walletCount;

Fixed in commit hash 6461451

Fix critical bugs and configuration issues identified in code review: Bug Fixes: - Fix wallet count aggregation in analyze-per-operator.js - Changed assignment operator from = to += on lines 122, 125 - Now correctly sums wallet counts across all operators per provider - Previously only recorded last operator's count, causing incorrect analysis Configuration: - Externalize hard-coded file paths to environment variables - query-dkg-events.js: Use PROOF_OF_FUNDS_PATH with ./data/ fallback - validate-operator-list.js: Use THRESHOLD_STAKERS_CSV_PATH with ./data/ fallback - Scripts now portable across team members and environments Documentation: - Add data file setup section to README.md - Document two setup options: default directory and env variables - Create data/README.md with file requirements and sources - Update .env.example with new configuration variables - Add data/ directory to .gitignore All review comments from piotr-roslaniec addressed.

Add gitignore rules for wallet-operator-mapper script working files: - .env for local configuration - data/ directory for analysis outputs - JSON mapping files generated during execution - package-lock.json for npm dependency lock These files are runtime artifacts that should not be tracked.

jose-blockchain · 2025-11-05T08:50:20Z

Looks solid overall! Since these queries archive nodes for historical DKG events, have you run into any RPC rate limting issues? scanning large block ranges can sometimes be flaky depending on the provider.

As a nice to have in the future, might be worth adding some retry logic or at least documenting the expected runtime and which RPC providers work well (I'm guessing this needs archive node access, so not all Infura/Alchemy tiers will work).

Also curious... what's the typical execution time for a full analysis run?

Remove single-purpose investigation scripts and add general-purpose query utilities for ongoing operator management. Removed: - calculate-all-beta-staker-weights.js (governance task complete) - calculate-allowlist-weights.js (superseded) - generate-allowlist-weights-final.js (output saved) - check-current-pool-weights.js (investigation complete) - check-sortition-pool-divisor.js (findings incorporated) - investigate-unknown-operator.js (one-time investigation) - verify-missing-wallets.js (specific verification done) Added utility scripts: - query-proof-of-funds.js: Generate proof-of-funds reports - query-sortition-pool.js: Check operator pool status - query-all-pool-operators.js: Discover all pool operators - query-all-stakers.js: Verify staker documentation completeness Updated README to document all remaining scripts in Main and Utility sections.

piotr-roslaniec

LGTM, just a couple of questions

piotr-roslaniec · 2025-12-17T07:55:33Z

scripts/wallet-operator-mapper/query-all-stakers.js

+  console.log(`\nTotal unique staking providers: ${allStakingProviders.size}\n`);
+
+  // Load our known list
+  const stakersJson = require('/Users/leonardosaturnino/Documents/GitHub/memory-bank/20250809-beta-staker-consolidation/knowledge/threshold_stakers_may_2025.json');


Let's add this JSON to repo or use a permalink to fetch it

piotr-roslaniec · 2025-12-17T07:56:46Z

scripts/wallet-operator-mapper/query-all-stakers.js

+    );
+    const walletRegistry = new ethers.Contract(WALLET_REGISTRY_ADDRESS, walletRegistryAbi, provider);
+
+    for (const provider of unknownProviders) {


Nitpick: We are shadowing const provider = new ethers.JsonRpcProvider(...) from before

Suggested change

for (const provider of unknownProviders) {

for (const stakingProvider of unknownProviders) {

piotr-roslaniec · 2025-12-17T07:58:16Z

scripts/wallet-operator-mapper/query-proof-of-funds.js

+    totalBalance += BigInt(balanceSats);
+
+    // Convert satoshis to BTC as integer string (truncated, no decimals)
+    const balanceBTCInt = Math.floor(balanceSats / 100000000);


I'm not sure about whether or not this will lead to some significant loss in precision

Suggested change

const balanceBTCInt = Math.floor(balanceSats / 100000000);

const balanceBTCInt = (balanceSats / 100000000).toFixed(8);

piotr-roslaniec · 2025-12-17T08:01:01Z

scripts/wallet-operator-mapper/query-dkg-events.js

+      providers.forEach(provider => {
+        if (summary.byProvider[provider]) {
+          summary.byProvider[provider].wallets++;
+          summary.byProvider[provider].btc += wallet.btcBalance;


What happens if wallet has operators from multiple deprecated providers? Is that possible? If yes, is it going to be counted multiple times?

Suggested change

summary.byProvider[provider].btc += wallet.btcBalance;

summary.byProvider[provider].btc += wallet.btcBalance / providers.size

lrsaturnino requested a review from piotr-roslaniec October 27, 2025 03:19

piotr-roslaniec reviewed Oct 27, 2025

View reviewed changes

lrsaturnino requested a review from piotr-roslaniec October 29, 2025 18:08

piotr-roslaniec previously approved these changes Oct 29, 2025

View reviewed changes

lrsaturnino dismissed piotr-roslaniec’s stale review via 68e8357 December 16, 2025 05:21

lrsaturnino requested a review from piotr-roslaniec December 16, 2025 05:42

lrsaturnino enabled auto-merge December 16, 2025 05:54

piotr-roslaniec reviewed Dec 17, 2025

View reviewed changes

	providerShares[data.provider].keepWallets = data.walletCount;
	providerShares[data.provider].keepWallets += data.walletCount;

	providerShares[data.provider].disableWallets = data.walletCount;
	providerShares[data.provider].disableWallets += data.walletCount;

	for (const provider of unknownProviders) {
	for (const stakingProvider of unknownProviders) {

	const balanceBTCInt = Math.floor(balanceSats / 100000000);
	const balanceBTCInt = (balanceSats / 100000000).toFixed(8);

	summary.byProvider[provider].btc += wallet.btcBalance;
	summary.byProvider[provider].btc += wallet.btcBalance / providers.size

feat(scripts): add wallet-operator mapper for consolidation analysis #3840

Are you sure you want to change the base?

feat(scripts): add wallet-operator mapper for consolidation analysis #3840

Uh oh!

Conversation

lrsaturnino commented Oct 27, 2025

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!

jose-blockchain commented Nov 5, 2025

Uh oh!

piotr-roslaniec left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants