Health Check: Algorithm, General Description

[adamantmm]

The goal is to make ADAMANT the most reliable crypto wallet.

See also:

• Health Check: Connection statuses
• Health Check: Endpoints
• Health Check: General updating spinner

Health Check Algorithm

Scope

• Works for all nodes, including ADM and coin nodes
• Works for services such as info-service and IPFS

Considerations

• Use Node height (~timestamp of update for services)
• Check Minimum supported version
• Use the most informative endpoint that provides all this info (e.g., /api/node/status for ADM)
• Do not request nodes disabled by the user
• Store the node list locally, including enabled/disabled status
  • Independent of the “Stay logged in” option

Node Statuses

• Disabled by user
• Not supported
  • Doesn’t fit minimum supported version
  • HTTP node via PWA-HTTPS
• Unavailable:
  • Request timeout: 10 sec
  • Check domain first
  • If unavailable, check alt_ip
  • Once domain is available, never check alt_ip again (to avoid extra requests). Logic:
    • Domain available → always use domain.
    • Domain unavailable & alt_ip available → use alt_ip.
    • Both unavailable → retry the algorithm on next request.

Available / In-Sync Detection

Rules:

• The only responsive node → Available
• A group of nodes within HEIGHT_EPSILON → Active
• Nodes outside threshold → In-sync (or “cheater”)

Thresholds:

• ADM: 10
• BTC: 2
• ETH: 5
• DOGE: 3
• DASH: 3
• LSK: 5

See adamant-wallets.

Examples:

• BTC nodes at 815,000 and 815,001 → both active
• BTC nodes at 815,000 and 815,002 → second active, first in-sync
• BTC nodes at 815,000, 815,001, 815,002 → last two active, first in-sync
• BTC nodes at 815,000, 815,001, 815,010 → first two active, third in-sync (cheater)
• BTC nodes at 815,000, 815,005, 815,010 → last one active, first two in-sync

Issues and Solutions

Issue 1 — Initial Health Check

At the very first health check (or after a connection drop):

• First node reply may be marked Active, though it could be In-sync
• Waiting for full check (10 sec) would freeze the app

Solution:

• Update to Active/In-sync only after 30% of nodes responded
• Before that, keep statuses as previous (Undefined/Unavailable/etc)
• Mark such check as Initial

Issue 2 — Subsequent Health Checks

In later checks:

• Some nodes already report heights
• Others still pending, but may have old data
• Pending ones may be mistakenly considered In-sync

Solution:

• Update to Active/In-sync only after 100% of nodes responded
• Until then, keep previous statuses
• Mark such check as Subsequent

Updating (Meta-status)

To avoid confusing users, show some nodes as Updating… (visual status only).

• Replaces real statuses when:
  • Health check is Initial and not 100% finished (in progress)
  • Only for nodes in Undefined or Unavailable real statuses
• UI: Grey dot (like Disabled) with muted text color:

Ping and Fastest Node

• Each health check request gives Ping
• Node with the smallest Ping = fastest node
• Prefer fastest node setting:
  • ADM: default No
  • Coin nodes: default Yes
• Works separately for coin node and coin indexer

Health Check Intervals

Param normalUpdateInterval is defined in adamant-wallets:

• adm-node: 5 min
• eth-node: 5 min
• eth-indexer: 7 min
• btc-node: 6 min
• btc-indexer: 8 min
• doge-node: 6.5 min
• doge-indexer: 8.5 min
• dash-node: 3.5 min
• lsk-node: 4.5 min
• lsk-indexer: 5.5 min
• rates-info: 3 min

Connectivity

• Run health checks independently of Internet connection status
  • Rationale: “No internet connection” status is not reliable, we can’t trust it
  • If no connection, the result will be “no available nodes” anyway.

Node Availability State

Update hasEnabledNodes and hasAvailableNodes (including Available/In-sync/Cheater) when:

• At least three nodes are responsive
• A health check is fully completed (even with <3 nodes)

Important for startup UX: avoids 10-sec freeze while waiting for timeouts.

Avoid Overlapping Checks

• Do not run a new health check if the previous one is still running
• Example: Bug in PWA #700:
  • setInterval() used instead of setTimeout()
  • When app restored from background, multiple intervals fired at once
  • Caused massive request storm and app hang

When to Run a Health Check

Event	ADM	Coin	Service
On app start (all groups)	Yes	Yes	Yes
On connection restore	Yes	Yes	Yes
Regularly when the app is in foreground (all groups, different intervals)	Every normalUpdateInterval	EverynormalUpdateInterval	Every normalUpdateInterval
(It may be omitted to reduce CPU load in the background) Regularly during background app work (all groups, different intervals)	When last check time < normalUpdateInterval	When last check time < normalUpdateInterval	When last check time < normalUpdateInterval
On restore from background	Yes, if last check time < normalUpdateInterval / 3	Yes, if last check time < normalUpdateInterval / 3	Yes, if last check time < normalUpdateInterval / 3
On a node screen just opened (all groups)	Yes	Yes	Yes
When a node screen is active (to see heights raising)	Every onScreenUpdateInterval	Every onScreenUpdateInterval	Every onScreenUpdateInterval
When a list of nodes is updated (iOS, Electron, specific group)	Yes	Yes	Yes
When a requests to all active nodes failed (see How to Send HTTP Requests to Nodes/Services, specific group)	Yes	Yes	Yes
When no active nodes (crucialUpdateInterval, specific group)	Every crucialUpdateInterval	Every crucialUpdateInterval	Every crucialUpdateInterval

Note: It’s important to update all nodes in a group simultaneously, not one at a time. Updating a single node separately may cause it to reach the highest height while leaving the others outdated.

Wallets

No Responses Case

• If there are no responses for 5 minutes, show balances as …

All Coin Nodes are Disabled by user

• On the Balance line, show: No active nodes
• On tap on Balance → navigate to the Coin node list
• On Pull down, show a popup: No active {COIN} nodes. Review the Coin node list.

Send coins Flow

• Send button: go to the Send screen as usual
• During coin send, show an error: No active {COIN} nodes. Review the Coin node list.

How to Send HTTP Requests to Nodes/Services

Request Algorithm

1. Do not start a new request if connection statuses are:

   • No active/available nodes
   • No enabled nodes

2. Ignore No internet connection status

   • Reason: it is unreliable (may be fake reported by OS)
   • Health check runs anyway, independently of internet connection
   • If there is indeed no connection, there will be no available nodes, so no request will be made
   • Health-check responsibility to provide connection statuses: healthCheck.hasInternet(), healthCheck.hasEnabledNodes('eth-indexer'), healthCheck.hasAvailableNodes('eth-indexer')

3. Do not wait for full health check to perform a request

   • hasEnabledNodes and hasAvailableNodes (including Available / In-sync / Cheater) are updated:
     • once there are at least 3 responsive nodes;
     • when health check completes (even if fewer than 3 nodes).
   • Purpose: improves startup UX, avoids waiting up to 10 seconds for timeouts

4. Choosing a node to request:

   • If Fastest node mode = ON → choose the fastest allowed node
   • If Fastest node mode = OFF → choose a random active node
   • Health-check responsibility to provide appropriate node: healthCheck.getNode('eth-indexer')

5. If the request fails:

   • Try the next active node
   • In Fastest mode → choose the next fastest
   • In Random mode → choose another random allowed node
   • Mark the failed node as Unavailable (except when status is No internet connection)
   • Health-check responsibility to mark a node as unavailable and provide another, e.g.,: healthCheck.getAnotherNode('eth-indexer', failedNode)

6. Repeat until the active node list is exhausted.

7. If all requests fail:

   • Perform an extra health check if connection status ≠ No internet connection.
   • On connection restore and at intervals, regular health checks are triggered (see When to Run a Health Check).

Notes

• A “failed” request means the node did not reply at all (timeout). Errors like HTTP 404 ≠ failed → the node should not be marked unavailable
• Always complete pending requests after connection restore. Example: saving the contact list in KVS must not be interrupted. Example scenario:
  • The app requests a delegate list on screen and shows a spinner, or it saves the contact list
  • The request to node A failed, and also to nodes B, C… X — no live nodes remain
  • The request will wait until the connection/nodes are restored, then complete — the contact list will be saved, and the app will display the delegate list.

[adamant-al]

Hi!

That’s an impressive level of detail — thanks for putting together such a structured health-check specification.

From my perspective, two things stand out:

1. User confidence
   The entire logic with Initial vs. Subsequent checks, updating meta-status, and avoiding “false Active” states is crucial. Users often don’t notice subtle differences between “syncing” and “cheating,” but they do notice freezes or missing chats. Clear UX indicators (“Updating…”, grey dots) prevent confusion and build trust.

2. Resilience across environments
   Treating connectivity status as unreliable and relying only on node responses is a solid choice. It matches the philosophy of decentralization: don’t assume the device knows the truth — verify it via multiple independent nodes.

Some additional considerations worth discussing:

Mobile data conditions. Health checks on flaky connections might trigger unnecessary fallbacks to alt_ip. Maybe caching the last good response per node could smoothen this.
Security edge cases. “Cheater” detection is a nice safeguard, but should we also log/report when nodes repeatedly fall outside thresholds? Could be a sign of malicious or misconfigured nodes.
Extensibility. Since ADM integrates not only its own blockchain but also BTC, ETH, DOGE, etc., this health-check framework could evolve into a general “multi-chain reliability layer” — something very few wallets handle well.

This kind of reliability work is exactly what makes ADAMANT stand out from “yet another crypto wallet.” Reliability isn’t flashy, but it’s the foundation users feel every time they open the app.

[adamant-al]

See
[Task, Enhancement] Verify Health-check algorithm and How we send HTTP requests to nodes/services
Adamant-im/adamant-im#868

[metalisk]

Amazing

[dev-adamant-im]

Hey,

Thanks for the comprehensive reference.
Many parts of this guide is already implemented in bot PWA and iOS apps, and we continue improvements.

[al-onyxprotocol]

Lgtm, nothing to add.