diff --git a/docs/plans/mission-item-12-peer-directory.md b/docs/plans/mission-item-12-peer-directory.md index b9dea896..ae36b7ae 100644 --- a/docs/plans/mission-item-12-peer-directory.md +++ b/docs/plans/mission-item-12-peer-directory.md @@ -19,17 +19,18 @@ makes the list useless: this lane reports, it does not decide. | fork `components/addressmanager/src/lib.rs` `add_address`, `iterate_prioritized_random_addresses` (weighted by failure count and prefix bucket) | the store a dialled address lives in | directory addresses enter it like seeder answers; the weight decides which enter, the store's own rule decides the order | | fork `consensus/core/src/config/params.rs` `consensus_digest` (a switch at never is outside the digest; set, it is in) | the activation pattern every 0.3.16 switch follows | `peer_directory_activation_daa`, never on every network | -## 2. Design (prototype) +## 2. Design, as built (prototype; fork branch peer-directory-node on release-0.3.20-node dc141409, commit 0cad5106; repo branch peer-directory on master 819d536b, commit 9a64d18c) | Item | Rule | |---|---| -| Wire | `FinalityItem::Address(AddressItem { daa: u64, ip: [u8; 16], port: u16, pubkey: [u8; 48], signature: [u8; 96] })`, tag 5, signed by the vote key over `(chain_id, "IGNEUM_ADDR_V1", daa, ip, port)`; at most one per block; carried last | -| Who lists | a node with `--announce-address ` (or `--externalip`) and a vote key of its own puts its item in its own templates once per `pow_day` or when the address changes; opt-in, off by default (NAT) | -| Directory | per key hash the newest address by carrier DAA, kept for one weight window past its carrier; keys under dust at the latest checkpoint are not drawn | -| Draw | when outbound connections are missing and the address store has nothing left, up to 2 x missing addresses are drawn without replacement with probability proportional to the key's weight in the latest weight table, newest first on ties; each drawn address is added to the address manager and dialled; the DNS seeders are asked after, as today | -| Switch | `peer_directory_activation_daa` (never on every network; in the digest once set); below it no template carries the item and no node reads one | -| RPC | `igneum_getPeerDirectory` lists entries with key, address, carrier DAA and weight (the harness and the simulation read it) | -| Bytes | 1 + 8 + 16 + 2 + 48 + 96 = 171 B per item; at one item per key per day and 10,000 keys, 1.7 MB a day per node (approximate, from the shape) | +| Wire | `AddressAnnounce { daa, ip: [u8; 16], port, pubkey, signature }` (core `finality.rs`), 171 B, signed by the vote key the header names under `IGNEUM_ADDR_V1` over `"igneum-addr-v1/" || chain_id || 0 || daa || ip || port` | +| Carriage | in the MINER's extra data as `IGNP || hex(body)`, the key reveal's form (`IGNA` is already the EVM payout tag), never in the finality section: no switch for carriage, a node without the tag never meets it; `igneum-miner mine --announce ` puts one in every template of every identity (`announced`, dated at the sink's DAA score when the run began) | +| Reading | `FinalityManager::on_block_body` at or above `peer_directory_activation_daa`: the announcement must be by the block's own key, verify, and name a routable-in-form address; one node-local entry per key, the newest carrier wins (not persisted: a restarted node refills it from the blocks it sees; a prototype's gap) | +| Report | `ConsensusApi::peer_directory()` rows with each key's weight at the latest determined checkpoint (0 under dust); entries older than a weight window dropped on the way | +| Draw | `ConsensusApi::peer_directory_draw(n, exclude)`: without replacement, proportional to weight, keys under dust never drawn | +| Dialling | `ConnectionManager::handle_outbound_connections`: after the address store's own iterator and before the DNS seeders, when connections are still missing, 2 x missing addresses from the draw enter the address store and are dialled at once (`DirectoryDraw` closure wired in `protocol/flows/src/service.rs` through the consensus's blocking session) | +| Switch | `peer_directory_activation_daa`, never on every network (the four network constants), in the digest once set, in `OverrideParams` and the 60x file | +| Not done | the RPC that lists the directory (the harness reads `getConnectedPeerInfo` and the node log instead); persistence across restarts; Ember and the phone's use of the list (invent.md 7.1's third hour) | ## 3. Gate plan