Struct ProviderRecord 

pub struct ProviderRecord {
    pub content_key: String,
    pub provider_peer_id: String,
    pub addresses: Vec<CandidateAddr>,
    pub expires_at: u64,
    pub unverified_mirror_coin_id: Option<String>,
}

The DHT’s stored value: peer provider_peer_id holds the content whose key is content_key, reachable at addresses, until expires_at.

• content_key is the 64-hex Key the content id hashed to — the DHT stores by key, not by the (larger, granularity-tagged) content id, so a record is compact and the store is a pure key→providers map.
• provider_peer_id is the 64-hex peer_id of the holder; a finder builds a PeerTarget from it plus addresses and connects via dig-nat.
• expires_at is absolute Unix seconds; a record past its expiry is treated as absent and GC’d. The holder republishes (a fresh record with a new expires_at) before expiry to stay findable.

Fields

content_key: String

The content key (64-hex) this record provides for — the Key a content id hashed to.

provider_peer_id: String

The holder’s peer_id (64-hex).

addresses: Vec<CandidateAddr>

Candidate addresses to reach the holder, ordered IPv6-first then most-direct-first by AddressKind::rank and bounded to MAX_ADDRESSES_PER_RECORD — held by BOTH ProviderRecord::new and deserialization ([deserialize_capped_addresses]), so a record off the wire carries the same guarantee as a constructed one.

expires_at: u64

Absolute expiry (Unix seconds). A record at/after this time is stale.

unverified_mirror_coin_id: Option<String>

UNTRUSTED POINTER, NOT EVIDENCE — an optional 64-hex mirror-coin id the publisher claims bonds this (store, root) claim, carried so a verifier can fetch ONE coin instead of searching for it.

Holding this proves nothing whatsoever. Any peer can publish any 32 bytes, and a hostile or merely stale publisher can supply a real, well-formed, fully-collateralised coin id that bonds a different store, a different root, a different epoch, or a different owner — every property checks out except the one that matters. A consumer MUST, against its own chain source:

1. fetch the coin and verify it sits at dig_mirror_coin::mirror_coin_puzzle_hash(),
2. verify it is $DIG with the asset id re-derived from the creating spend,
3. verify it carries the full collateral, and
4. confirm the coin’s DECLARED bond matches the claim — advertises(store, root, epoch) is an exact equality on the declared triple, and the owner is checked against the four-term dig_mirror_coin::mirror_hint(store, root, owner_puzzle_hash, epoch).

Step 4 is what binds the coin to the claim; 1-3 alone prove only that a valid mirror coin exists somewhere. No verification happens in this crate — the DHT has no chain source.

Absence is normal and must never degrade discovery. Old publishers, publishers that have not created the coin yet, and publishers mid-epoch-rollover all legitimately omit it; a republished record can also carry a pointer that has since gone stale across an epoch boundary. A store-granularity record can never carry one at all, since a mirror coin bonds (store, root, owner, epoch) and a store-granularity claim names no root. Treating a missing pointer as “uncollateralised” is a defect.

There is no equally cheap fallback, and none is required. dig_mirror_coin::discover cannot serve as one: it takes owner_puzzle_hash as a required parameter, because the hint is morphed from the owner, and a provider record carries no owner. An owner-less scan of the shared mirror puzzle hash is not merely slower — it is truncated at MAX_CANDIDATES on a list anyone may extend for the price of a dust coin, so its “not found” is not a negative a verifier may act on, and it turns one free inbound record into an unbounded outbound read. A consumer that cannot fetch a pointer therefore withholds credit and leaves the holder’s ranking unchanged; it does not demote.

A wrong pointer costs the publisher, not the verifier. One chain read, no retry loop: a lookup that misses or fails the bond check yields no credit for that holder. A mismatch is not grounds for blocklisting — it is indistinguishable from an epoch rollover.

Malformed values normalize to None at the wire boundary and again at admission, so on an ADMITTED or STORED record this is either a canonical lowercase 64-hex string or absent. That guarantee belongs to those records only: the field is pub, so a value that has not yet passed either normalization can hold arbitrary attacker-shaped bytes of arbitrary length. A consumer holding a record from any other source must normalize it itself.

Implementations

impl ProviderRecord

pub fn new( content_key: &Key, provider: &PeerId, addresses: Vec<CandidateAddr>, expires_at: u64, ) -> Self

Build a record: peer provider holds content_key, reachable at addresses, until expires_at (absolute Unix seconds).

pub fn with_unverified_mirror_coin_id(self, coin_id: [u8; 32]) -> Self

Attach the publisher’s claimed mirror-coin id — see unverified_mirror_coin_id for why holding it proves nothing. Stored canonically (lowercase 64-hex) so two records naming the same coin are byte-identical.

Kept off new deliberately: the pointer is per-CONTENT rather than per-node, because a mirror coin bonds a (store, root, owner, epoch) tuple, so only the caller that knows which content it is announcing can supply it.

pub fn unverified_mirror_coin_id_bytes(&self) -> Option<[u8; 32]>

The claimed mirror-coin id as 32 bytes, or None when absent (the normal fallback case).

The bytes are a lookup key, never a fact. Returning Some means a publisher said something, not that a collateral coin exists.

pub fn provider_peer_id(&self) -> Option<PeerId>

The provider’s peer_id decoded from the 64-hex field, or None if malformed.

pub fn is_expired(&self, now: u64) -> bool

Whether this record is expired at now (Unix seconds) — stale records are dropped on read.

pub fn best_address(&self) -> Option<&CandidateAddr>

The FIRST candidate only — the IPv6-preferred, most-direct dialable address, if any.

Prefer dial_candidates for dialing. This returns one address, so a caller that dials it and stops has made a single attempt and cannot fall back: an unusable IPv6 candidate then masks a working IPv4 one, violating the IPv4-fallback half of §5.2 (exactly the #836 read-leg failure). Use this only where a single representative address is genuinely what is wanted — a log line, a display string, a metric label.

pub fn dial_candidates(&self) -> Vec<&CandidateAddr>

This provider’s dialable candidates in §5.2 dial order — see dial_candidates for the ordering contract. Dial these in order, falling through on failure, before concluding the holder is unreachable.

Trait Implementations

impl Clone for ProviderRecord

fn clone(&self) -> ProviderRecord

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProviderRecord

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ProviderRecord

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ProviderRecord

impl PartialEq for ProviderRecord

fn eq(&self, other: &ProviderRecord) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ProviderRecord

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ProviderRecord