Struct Pointer 

pub struct Pointer { /* private fields */ }

A paid, mutable, owner-signed reference.

A value of this type has been through Pointer::from_bytes, so its signature covers exactly its body and its address derives from its owner.

Implementations

impl Pointer

pub fn sign( secret_key: &MlDsaSecretKey, owner: &MlDsaPublicKey, counter: u64, target: PointerTarget, ) -> Result<Self, PointerError>

Build and sign a pointer.

Errors

Returns PointerError::SigningFailed if signing fails, or a parse error if the resulting record does not parse, which would be a bug here rather than bad input.

pub fn create( secret_key: &MlDsaSecretKey, owner: &MlDsaPublicKey, target: PointerTarget, ) -> Result<Self, PointerError>

Create a pointer at counter 0.

Errors

As Self::sign.

pub fn update( &self, secret_key: &MlDsaSecretKey, target: PointerTarget, ) -> Result<Self, PointerError>

Sign the update that follows this one: counter + 1, new target.

One past this record is the smallest counter that replaces it, and so the natural next state. A larger one would replace it just as well.

Errors

Returns PointerError::CounterExhausted at u64::MAX, otherwise as Self::sign.

pub fn finalize( &self, secret_key: &MlDsaSecretKey, target: PointerTarget, ) -> Result<Self, PointerError>

Sign this pointer’s final state, pointing at target.

Signed at FINAL_COUNTER, so once a node holds it nothing replaces it — not a later update, which cannot exist, and not another final state, which does not replace. Use Self::transfer_to to hand the pointer to someone else; a final state pointing at a chunk freezes the pointer on that chunk at every node that holds it.

Signing a second final state is the one way to fork a pointer for good: each node keeps whichever of the two it saw first, and no later state heals it, where a fork at a lower counter is. So this refuses to sign past a record that is already final, and a caller must read the network’s state before finalizing rather than after. That refusal guards a caller against a mistake, not the network against the owner: an earlier record can be finalized again, and Self::sign signs any counter.

Errors

Returns PointerError::CounterExhausted if this record is already final, otherwise as Self::sign.

pub fn transfer_to( &self, secret_key: &MlDsaSecretKey, recipient: XorName, ) -> Result<Self, PointerError>

Sign the final state that hands this pointer’s address over to the pointer at recipient.

The owner key cannot change, but what the address resolves to can be handed over: the final state points at a pointer the new owner holds the key to, so a reader of this address is redirected there by every node that holds this state, and from there only the new owner moves it on. It is not exclusive: the former owner can still finalize an earlier record towards someone else, and a node that holds neither takes whichever reaches it first (see Self::finalize). The address readers use does not change.

recipient should be a pointer that exists, and one whose owner uses it only for this address: a pointer’s address derives from its owner key, so every address handed to the same recipient pointer resolves to the same place.

Errors

As Self::finalize.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, PointerError>

Parse and fully validate a record.

Checks, cheapest first: length, format version, structure, then the signature. A returned Pointer is structurally valid and correctly signed by the key it carries; it says nothing about payment, which is a separate external check.

Errors

Returns PointerError for a malformed record or one whose signature does not verify.

pub fn verify_parsed(parsed: ParsedPointer) -> Result<Self, PointerError>

Verify a record that has already been parsed.

Decoding an ML-DSA public key is not free, and the request path parses before it decides whether verification is worth doing at all. This lets it hand over what it already has instead of decoding a second time.

Errors

As Self::from_bytes.

pub fn to_bytes(&self) -> Vec<u8>

The canonical encoding of this record.

Re-encoded from the fields rather than cached. Every field is fixed-width with no optionality, so there is exactly one encoding and this is always byte-identical to what was signed.

pub const fn owner(&self) -> &MlDsaPublicKey

The owner’s public key. Fixed for the pointer’s life.

pub fn state(&self) -> PointerState

The signed state this record carries.

Derived, not stored: the identifiers are hashes of fields already here.

pub const fn counter(&self) -> u64

The update counter.

pub const fn target(&self) -> PointerTarget

What this pointer points at.

pub fn address(&self) -> XorName

The address this record belongs at, derived from the owner key.

pub fn state_id(&self) -> XorName

The authenticated-state identifier, derived from the signed body.

Names the state rather than the encoding, so two records carrying different valid signatures over one state share a state_id. This is what sync hints carry and what a quote is paid against.

pub fn next_counter(&self) -> Result<u64, PointerError>

The successor counter for an update to this pointer.

Errors

Returns PointerError::CounterExhausted at FINAL_COUNTER.

A record at the final counter is replaced by nothing, so there is no update to sign past it. Migrating a pointer to a fresh one is exactly that final update: see Self::transfer_to.

pub const fn is_terminal(&self) -> bool

Whether this record is final: signed at FINAL_COUNTER.

A node that holds a final record keeps it: neither a lower counter nor another final record replaces it. See PointerState::replaces.

pub const fn transferred_to(&self) -> Option<XorName>

The pointer this record hands its address over to, if it is a transfer.

As PointerState::transferred_to.

pub fn replaces(&self, other: &Self) -> bool

Whether self replaces other under the merge rule.

See PointerState::replaces, which is where the rule lives.

Trait Implementations

impl Clone for Pointer

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Pointer

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

Shows what identifies the record, not its 5 KB of key and signature.