Skip to content

Commit 157fbae

Browse files
jsync-swirldsjsync-swirlds
committed
Create new HIP for account_id updates for Address Book Node Entries.
Signed-off-by: Joseph S <121976561+jsync-swirlds@users.noreply.github.com>
1 parent f0a43db commit 157fbae

1 file changed

Lines changed: 205 additions & 0 deletions

File tree

‎HIP/hip-1299.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
hip: 1299
3+
title: Node Account ID Refinements for Dynamic Address Book
4+
author: Richard Bair (@rbair23), Joseph Sinclair (@jsync-swirlds)
5+
type: Standards Track
6+
category: Service
7+
needs-hiero-approval: Yes
8+
needs-hedera-review: Yes
9+
status: Draft
10+
created: 2025-09-29
11+
updated: 2025-09-29
12+
requires: HIP-869
13+
---
14+
15+
## Abstract
16+
This proposal refines the rules for managing the account ID associated with
17+
Node entries in the Dynamic Address Book (DAB). The DAB is a feature that
18+
stores information about network nodes, such as their identifiers and associated
19+
accounts, directly in the network's state instead of in Hedera File Service (
20+
HFS) files. This makes updates more secure and consistent.
21+
22+
The refinements focus on how account IDs can be updated, removed, or set, with
23+
an emphasis on security through required signatures, preventing reuse of the
24+
same account ID across multiple nodes, and handling cases where accounts lack
25+
sufficient funds. These changes provide flexibility for node operators while
26+
protecting the network from disruptions.
27+
28+
## Motivation
29+
HIP-869 introduced the DAB, allowing node information to be stored and updated
30+
dynamically. Each node entry includes an immutable unique node ID and an account
31+
ID, which is used for receiving fees and rewards and paying penalties.
32+
33+
As we enable rotations of the account ID—meaning changing the account linked to
34+
a node—we've identified new scenarios that need clear rules. For example, we
35+
need to ensure changes are authorized, prevent one low-balance account from
36+
affecting multiple nodes, and handle what happens if an account can't receive
37+
rewards or pay penalties. These updates make the system more robust without
38+
complicating day-to-day operations.
39+
40+
## Rationale
41+
This design is based on a few straightforward principles:
42+
- Changes to a node's account ID must be approved by the right parties to
43+
prevent unauthorized access or mistakes.
44+
- Updates take effect immediately. Rewards and penalties use the account ID in
45+
effect at the time of calculation.
46+
- The system checks for issues like low account balances and prevents account
47+
deletions if they're still linked to nodes.
48+
- No single account ID can be used for more than one node, so problems with one
49+
account don't spread.
50+
- If rewards can't be delivered to an account (for example, if it's invalid),
51+
they're sent to a special system account (`0.0.801`) instead of causing
52+
errors.
53+
54+
These rules balance flexibility for operators with network stability and
55+
security.
56+
57+
## Specification
58+
59+
### Overview
60+
This proposal does not change the NodeUpdateTransactionBody, which already
61+
supports changes to the `account_id` field. Here's the relevant part of the
62+
existing protocol buffer definition, with additional clarity added to the
63+
specification text.
64+
65+
```protobuf
66+
/**
67+
* An account identifier.
68+
* <p>
69+
* To remove, send a transaction setting it to 0.0.0 signed by the current
70+
* account owner or the node admin key.
71+
* <p>
72+
* To set or swap, send a transaction setting it to the new account_id value
73+
* signed by (the current account owner or the node admin key) AND the new
74+
* account owner.
75+
* <p>
76+
* The new account number MUST be a valid, existing account if not 0.0.0.
77+
* <p>
78+
* The same account_id cannot be used across multiple nodes.
79+
* <p>
80+
* While an account is assigned to the `account_id` for a Node, that account
81+
* cannot be deleted.
82+
*/
83+
proto.AccountID account_id = 2;
84+
```
85+
To protect accounts, you can't delete an account if it's linked to any node in
86+
the DAB. You must first remove the link, and then delete.
87+
88+
When the network has rules for account "rent" (a small fee to keep accounts
89+
active), accounts with too little balance (insufficient to pay rent) are
90+
automatically unlinked from their node(s) (the node `account_id` is set to
91+
`0.0.0`) in the Node Store. The account itself is only deleted after that node
92+
is no longer listed in the active roster, or a new value (other than `0.0.0`) is
93+
assigned as the `account_id` for that node.
94+
95+
Rewards and penalties use the account ID that's active at the time. If a reward
96+
can't be delivered, it's forfeited to account `0.0.801`. The system ignores
97+
any "receiver signature required" settings and doesn't trigger extra actions (
98+
hooks).
99+
100+
If a penalty can't be paid because the account has zero balance, or if the
101+
account lacks funds for rent, the node is removed from the roster at the next
102+
roster update, following rules from other proposals on roster updates.
103+
104+
No changes are made to NodeCreateTransactionBody, so new nodes still need an
105+
initial account ID, signed by both the node admin and the account owner.
106+
107+
No changes are made to NodeDeleteTransactionBody, which removes the entire node
108+
entry.
109+
110+
### Implementation Details
111+
- **Validation**: For setting a new account ID, the system checks that the
112+
account exists and the transaction is signed by its key. If the node admin key
113+
isn't signing, it also needs the current account's signature. For removal (
114+
setting to `0.0.0`), it's signed by either the current account or the node
115+
admin. Repeating the same account ID is allowed (idempotent). Invalid accounts
116+
are rejected. The system ensures no other node uses the same account ID.
117+
- **Effective Timing**: Changes apply immediately.
118+
- **Roster Construction**: Nodes without a valid account ID when a new roster is
119+
adopted are excluded from that new roster.
120+
- **Reward Distribution**: Rewards go to the active account ID. If it fails,
121+
they go to `0.0.801`. Receiver signatures are ignored, and no hooks run.
122+
- **Penalties**: Penalties deduct from the active account ID. If balance is too
123+
low to pay current penalties, the node is removed from the roster at the next
124+
roster update.
125+
- **Account Deletion Interlock**: Deletion fails if the account is in any Node
126+
entry. The Node operator must remove the account from that Node first, and
127+
then delete the node.
128+
- **Auto-Removal for Rent**: If balance drops below a minimum amount required to
129+
pay rent, the network will unlink the account from the Node in the DAB (by
130+
setting the `account_id` to `0.0.0`). The system may then delete the account
131+
only after that node is no longer in the active roster (at the next Roster
132+
update) or a new `account_id` is assigned by the Node operator.
133+
- **Queries**: Mirror nodes (which provide network data) show the current Node
134+
state from the DAB and can show pending changes if asked.
135+
- **In-Flight Transactions**: Transactions accepted before a node update to
136+
change an account ID are processed based on the node state at consensus time.
137+
If the account ID has changed by then, the transaction may fail or be
138+
redirected appropriately, but clients should retry on different nodes using
139+
up-to-date information.
140+
## Backward Compatibility
141+
These changes add new options without breaking existing setups. Current nodes
142+
keep their account IDs. Tools that use account IDs for identification continue
143+
working.
144+
145+
Older clients might encounter issues if they hard-code node details and an
146+
account ID changes. To avoid this, use software development kits (SDKs) that
147+
automatically fetch the latest node list from mirror nodes and retry
148+
transactions on different nodes if needed. These clients will also need to
149+
ensure that no node account values are hardcoded or provided to the SDK without
150+
first querying the current state of the node or nodes involved.
151+
152+
## Record File Effects
153+
The Record File uploader processes will continue to use the old Account ID when
154+
calculating file path information until the next network upgrade. This is
155+
intended to provide stability for mirror node and other record file clients.
156+
This *only* impacts the *path* in the cloud bucket, and does not have any
157+
interaction with the content of record files or the signature keys (which is
158+
determined by Roster data).
159+
160+
Mirror Nodes and other users of the record files will need to keep track of the
161+
current Account ID until the next network upgrade in order to continue reading
162+
files from the correct path.
163+
164+
## Security Implications
165+
Required signatures prevent unauthorized changes: removals need the current
166+
account or node admin, additions need the new account, and swaps need
167+
combinations to protect everyone.
168+
169+
Operators should watch account balances to avoid auto-removal or penalties.
170+
Forbidding shared account IDs limits the impact of one bad account.
171+
172+
Undeliverable rewards are handled cleanly by forfeiture. All changes are logged
173+
in transaction records for auditing. The extra checks add little performance
174+
cost.
175+
176+
## How to Teach This
177+
1. **For Node Operators**: You can now change your node's account ID with a
178+
signed transaction, giving you more control over finances. Changes take
179+
effect immediately and rewards are paid at 00:00 UTC, so plan ahead. Keep
180+
enough balance to avoid automatic removal.
181+
2. **For Developers**: Workflows change little. Check mirror nodes for updated
182+
DAB entries. SDKs will handle new fields for updates. Applications that do
183+
not use an SDK may consider pre-signing transactions for multiple nodes in
184+
case the first node attempted rejects the transaction due to an account ID
185+
change.
186+
3. **Examples**:
187+
- **Removing an Account ID**: Submit a NodeUpdateTransactionBody setting
188+
`account_id` to `0.0.0`, signed by the current account or node admin. The
189+
node is excluded from the next roster and transactions can no longer be
190+
submitted to that node immediately after the transaction is executed.
191+
- **Setting a New Account ID**: Set account_id to the new value, signed by
192+
the node admin and the new account. If the node has no admin key, sign with
193+
the old and new accounts.
194+
- **Swapping Account IDs**: Similar to setting, with signatures from (old
195+
account or admin) and new account.
196+
Document this in guides for the Hedera API (HAPI) and DAB, including tips on
197+
balances and rent.
198+
199+
## References
200+
- [HIP-869: Dynamic Address Book](https://hips.hedera.com/hip/hip-869)
201+
202+
## Copyright
203+
This document is licensed under the Apache License, Version 2.0 —
204+
see[LICENSE](https://hips.hedera.com/LICENSE)
205+
or https://www.apache.org/licenses/LICENSE-2.0.

0 commit comments

Comments
 (0)