Struct Mailbox 

pub struct Mailbox<S: Scheme, V: Variant> { /* private fields */ }

A mailbox for sending messages to the marshal Actor.

Implementations

impl<S: Scheme, V: Variant> Mailbox<S, V>

pub async fn get_info( &self, identifier: impl Into<Identifier<<V::Block as Digestible>::Digest>>, ) -> Option<(Height, <V::Block as Digestible>::Digest)>

Retrieve (height, digest) for a finalized block by height, digest, or latest.

pub async fn get_block( &self, identifier: impl Into<Identifier<<V::Block as Digestible>::Digest>>, ) -> Option<V::Block>

A best-effort attempt to retrieve a given block from local storage. It is not an indication to go fetch the block from the network.

pub async fn get_finalization( &self, height: Height, ) -> Option<Finalization<S, V::Commitment>>

A best-effort attempt to retrieve a given Finalization from local storage. It is not an indication to go fetch the Finalization from the network.

pub async fn get_processed_height(&self) -> Option<Height>

Retrieve the latest processed height.

pub fn hint_finalized(&self, height: Height, targets: NonEmptyVec<S::PublicKey>)

Hints that a finalized block may be available at the given height.

This method will request the finalization from the network via the resolver if it is not available locally.

Targets are required because this is typically called when a peer claims to be ahead. By targeting only those peers, we limit who we ask. If a target returns invalid data, they will be blocked by the resolver. If targets don’t respond or return “no data”, they effectively rate-limit themselves.

Calling this multiple times for the same height with different targets will add to the target set if there is an ongoing fetch, allowing more peers to be tried.

This is fire-and-forget: the finalization will be stored in marshal and delivered via the normal finalization flow when available.

The height must be covered by both the epocher and the provider. If the epocher cannot map the height to an epoch, or the provider cannot supply a scheme for that epoch, the hint is silently dropped.

pub fn subscribe_by_digest( &self, digest: <V::Block as Digestible>::Digest, fallback: DigestFallback, ) -> Receiver<Arc<V::Block>>

Subscribe to a block by its digest.

If the block is found available locally, the block will be returned immediately.

If the block is not available locally, the subscription will be registered and the caller will be notified when the block is available. If the block is not finalized, it’s possible that it may never become available.

The fallback parameter controls whether marshal also asks peers for the missing block. Digest-keyed subscriptions only support waiting locally or fetching by round.

Delivery makes no durability promise. A delivered block may not have been persisted by marshal, so it may not be retrievable after an unclean shutdown. Consumers that need durable height-ordered delivery should rely on application dispatch instead.

The oneshot receiver should be dropped to cancel the subscription.

pub fn subscribe_by_commitment( &self, commitment: V::Commitment, fallback: CommitmentFallback, ) -> Receiver<Arc<V::Block>>

Subscribe to a block by its commitment.

If the block is found available locally, the block will be returned immediately.

If the block is not available locally, the subscription will be registered and the caller will be notified when the block is available. If the block is not finalized, it’s possible that it may never become available.

The fallback parameter controls whether marshal also asks peers for the missing block.

Delivery makes no durability promise. A delivered block may not have been persisted by marshal, so it may not be retrievable after an unclean shutdown. Consumers that need durable height-ordered delivery should rely on application dispatch instead.

The oneshot receiver should be dropped to cancel the subscription.

pub fn hint_notarized(&self, round: Round, commitment: V::Commitment)

Hint that peers may have the block notarized at round.

This issues a round-bound resolver request without registering a new block subscriber. The commitment is only used to skip the request when the block is already available locally.

This is useful when a local-only waiter already exists and later certification makes a network fetch by notarized round valid.

pub async fn ancestry<C>( &self, clock: Arc<C>, __arg2: (DigestFallback, <V::Block as Digestible>::Digest), fetch_duration: Timed, ) -> Option<impl Ancestry<V::ApplicationBlock> + use<S, V, C>>

where Self: BlockProvider<Block = V::ApplicationBlock>, C: Clock,

Returns a stream over the ancestry of a given block, leading up to genesis.

This stream may fetch missing parents because callers should only request ancestry for data they already have locally and are willing to build on, verify, certify, or repair from. It is not a candidate fetch path.

If the starting block is not found, None is returned.

pub async fn get_verified(&self, round: Round) -> Option<V::Block>

Returns the verified block previously persisted for round, if any.

Multiple candidates can exist for one round (an equivocating leader can land one before a crash and another after), and this returns the first stored. Callers must not assume it is the most recently verified candidate: check context/digest before reuse, or look up by digest.

pub fn proposed( &self, round: Round, block: impl Into<Arc<V::Block>>, recipients: Recipients<S::PublicKey>, ack: Sender<Handle<()>>, ) -> Feedback

Requests the broadcast of a locally proposed block, persisting it after the send.

The actor hands the block to the network before ingesting and persisting it, so the storage write never delays propagation. ack receives the durable-sync handle once the write’s sync has started. The propose path stages the block (and ack) at propose time and calls this when consensus requests the broadcast via crate::Relay::broadcast, awaiting durability only at certification so the sync overlaps consensus voting.

A dropped ack (the mailbox is closed) abandons the handshake.

pub fn verified_deferred( &self, round: Round, block: impl Into<Arc<V::Block>>, ack: Sender<Handle<()>>, )

Notifies the actor that a block should be durably persisted at round, delivering its durable-sync handle through ack without awaiting it.

Takes a sender rather than returning a receiver so certification can deliver the handle into a handshake staged at propose time. A dropped ack (the mailbox is closed) abandons the handshake.

pub async fn verified( &self, round: Round, block: impl Into<Arc<V::Block>>, ) -> bool

Notifies the actor that a block has been verified.

Returns after the block is durably persisted. Mirrors Self::certified: the durable sync is awaited on the caller’s task (off the actor), so the actor never blocks on fsync.

pub async fn certified( &self, round: Round, block: impl Into<Arc<V::Block>>, ) -> bool

Notifies the actor that a block has been certified.

Returns after the block is durably persisted.

pub fn set_floor(&self, finalization: Finalization<S, V::Commitment>)

Attempts to set the sync starting point from a finalized commitment.

If the verified finalization advances marshal’s current floor, marshal anchors on its block, prunes below it, then syncs and delivers blocks starting at the floor height. Stale or superseded floors may be ignored.

To prune data without changing the sync starting point, use Self::prune instead. Use crate::marshal::Config::start to provide the startup anchor.

pub fn prune(&self, height: Height)

Requests pruning finalized blocks and certificates below the given height.

Unlike Self::set_floor, this does not affect the sync starting point. Requests above marshal’s current floor are ignored.

pub fn forward( &self, round: Round, commitment: V::Commitment, recipients: Recipients<S::PublicKey>, ) -> Feedback

Forward a locally stored block to a set of recipients.

Trait Implementations

impl<S, B> BlockProvider for Mailbox<S, Standard<B>>

where S: Scheme, B: Block,

type Block = B

The block type the provider walks.

fn subscribe_parent( &self, block: &Self::Block, ) -> impl Future<Output = Option<Arc<Self::Block>>> + Send + 'static

Subscribe to the parent of a known block.

impl<S, B, C, H, P> BlockProvider for Mailbox<S, Coding<B, C, H, P>>

where S: Scheme, B: CertifiableBlock<Context = Context<Commitment, P>>, C: CodingScheme, H: Hasher, P: PublicKey,

type Block = B

The block type the provider walks.

fn subscribe_parent( &self, block: &Self::Block, ) -> impl Future<Output = Option<Arc<Self::Block>>> + Send + 'static

Subscribe to the parent of a known block.

impl<S: Clone + Scheme, V: Clone + Variant> Clone for Mailbox<S, V>

fn clone(&self) -> Mailbox<S, V>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Scheme, V: Variant> Reporter for Mailbox<S, V>

type Activity = Activity<S, <V as Variant>::Commitment>

Activity is specified by the underlying consensus implementation and can be interpreted if desired.

fn report(&mut self, activity: Self::Activity) -> Feedback

Report some activity observed by the consensus implementation.