Add design doc for address book node account ID changes

[SimiHunjan]

Problem

Create a Hiero SDK design document for the planned Node Account ID changes, following the Hiero SDK Design Doc Template.

This design doc should outline all SDK-related updates, including new APIs, updated APIs, internal changes, and testing requirements.

A HIP will be released soon with the proposed requirements for node account ID changes in the address book to reference for this task.

Solution

Create a Hiero SDK design doc.

Alternatives

No response

[SimiHunjan]

HIP reference: hiero-ledger/hiero-improvement-proposals#1299

[Reccetech]

Regarding the design doc for Node Account ID Changes.
Here is my understanding based on the default settings in the JS SDK on how the SDK would react to a Node's Account ID being changed and lets say that change does not propagate to the SDK for 24hrs:

• minNodeReadmitTime = 8 seconds
• maxNodeReadmitTime = 10 minutes
• maxNodeAttempts = 1 per node per execution
• maxAttempts = some finite number (e.g. 10)
• backoff settings start from ~250 ms, up to a max (e.g. 8 seconds)

So, given that one node keeps returning INVALID_NODE_ACCOUNT for 24 hours continuously:

First time the SDK uses that node

• It gets INVALID_NODE_ACCOUNT.
• The SDK marks the node unhealthy.
• It will not try that node again for at least minNodeReadmitTime = 8 seconds (assuming that is the default).

After 8 seconds (the readmit window)

• The SDK may “re-admit” the node into the candidate pool for some subsequent transaction execution.
• The SDK will again try it (if selected) at some point, get INVALID_NODE_ACCOUNT, mark unhealthy again, and re-exclude it again for another 8 seconds.

Over full 24 hours

• The node will cycle between “excluded for 8 sec → briefly eligible → fail → excluded again for 8 sec” repeatedly, whenever the SDK re-tests it.
• Every time it fails, that transaction attempt instantly errors for that node, then SDK routes to a healthy node.
• Because 24 hours is >> the readmit window, that node will be tested many times (if the SDK ever picks it in the list) and fail each time.

Implication

• That node will essentially never be trusted for ongoing traffic — it will always be unhealthy or failing fast when rechecked.
• The cost is occasional retries and backoffs if it’s chosen.
• But for almost all transactions, the SDK will avoid using it as soon as it sees the pattern.

This being said if we run a model the impact of the error looks minor:

Model: 32-node Hedera Network with 1 node returning "INVALID_NODE_ACCOUNT"

Assumptions

• Network size: 32 nodes
• One node always returns INVALID_NODE_ACCOUNT
• Client transaction rate: 100 TPS
• SDK defaults:
  • Nodes per transaction (at freeze): 3
  • Per-node attempts per execution: 1
  • Global max attempts per execution: 10
  • Minimum backoff: 250 ms
  • Maximum backoff: 8 s
  • Minimum node readmit time: 8 s
  • Maximum node readmit time: 10 min

Probability of Hitting the Bad Node

Each transaction randomly selects 3 nodes from 32:

$$ p = \frac{3}{32} = 0.09375 $$

At 100 TPS, expected time until the bad node is included:

$$ \mathbb{E}[T] = \frac{1}{100 \cdot p} = \frac{1}{9.375} \approx 0.1067 \ \text{s} $$

Cycle Behavior

1. Node returns INVALID_NODE_ACCOUNT and is marked unhealthy.
2. Node is excluded for 8 seconds (minimum readmit time).
3. After 8 seconds, node is eligible again. It is retried, fails, and excluded again.

Cycle length:

$$ 8.000 \ \text{s (exclusion)} + 0.1067 \ \text{s (expected hit delay)} \approx 8.1067 \ \text{s} $$

Transactions per Cycle

At 100 TPS:

$$ 100 \times 8.1067 \approx 810.7 \ \text{transactions/cycle} $$

Exactly 1 transaction per cycle is affected.

Fraction affected:

$$ \frac{1}{810.7} \approx 0.123% $$

Hourly Impact

Cycles per hour:

$$ \frac{3600}{8.1067} \approx 444 $$

Affected transactions per hour:

$$ 444 \ \text{out of} \ 360{,}000 \ \approx 0.123% $$

[0xivanov]

@Reccetech If we encounter INVALID_NODE_ACCOUNT we could do address book query to get the new node account id before the 24 hour mark. What do you think?