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 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 u64::MAX.

A pointer that must outlive its counter has to be migrated by an earlier update — one that retargets it at a fresh pointer while a successor counter still exists. A migration written at u64::MAX is not final: the counter is spent, so the only thing that still decides the merge is the target, and any record with smaller target bytes displaces it. A strictly larger counter is the one move nothing can answer, so migration must spend a counter it still has.

pub const fn is_terminal(&self) -> bool

Whether this pointer’s counter is spent.

true once the counter reaches u64::MAX. Note this does not mean the stored value can no longer change: a record at the same counter with smaller target bytes still wins. It means the counter can no longer answer such a record, which is why clients migrate before reaching this rather than on it.

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.