Module address 

Swarm address implementation

This module provides the SwarmAddress type, which is a 32-byte identifier used for addressing chunks in the swarm network. It includes functionality for calculating distances between addresses and determining their proximity.

Proximity Order (PO)

Proximity order is a key concept in Kademlia-based routing. It measures how “close” two addresses are in the XOR metric space by counting the number of leading matching bits.

Standard vs Extended Proximity

• Standard PO (MAX_PO = 31): Used for most routing operations. Returns a value 0-31, giving 32 Kademlia bins. The algorithm counts leading matching bits up to 32 bits (4 bytes) and caps at 31.

• Extended PO (EXTENDED_PO = 36): Used for Kademlia bin balancing. When balancing bins, the algorithm needs finer granularity: po + BitSuffixLength + 1 where BitSuffixLength = 4. For bin 31, this yields 31 + 4 + 1 = 36, hence ExtendedPO = MaxPO + 5.

Compatibility

This implementation matches the Swarm reference implementation exactly:

• MaxPO = 31 and ExtendedPO = 36
• Counts leading matching BITS (not bytes)
• Caps at the respective maximum values

Distance vs Proximity

• Distance (distance()): Returns the full 256-bit XOR distance as U256.
• Proximity (proximity()): Returns a small integer (0-31) representing the count of leading matching bits, capped at MAX_PO.

Higher proximity = closer addresses = smaller XOR distance.

Example Usage

use nectar_primitives::SwarmAddress;
use alloy_primitives::B256;

// Create addresses
let addr1 = SwarmAddress::from(B256::random());
let addr2 = SwarmAddress::from(B256::random());

// Calculate proximity
let po = addr1.proximity(&addr2);
println!("Proximity order: {}", po);

// Calculate distance
let distance = addr1.distance(&addr2);
println!("Distance: {}", distance);

// Compare distances
let addr3 = SwarmAddress::from(B256::random());
if addr1.closer(&addr2, &addr3) {
    println!("addr1 is closer to addr2 than addr3");
}

Structs

SwarmAddress

A 256-bit address for a chunk in the Swarm network

Constants

EXTENDED_PO

Extended proximity order for Kademlia bin balancing.

MAX_PO

Maximum proximity order for standard routing operations.