Struct WithdrawQueue

pub struct WithdrawQueue {
    pub next_withdraw_to_execute: u64,
    pub next_pending_withdrawal_id: u64,
    /* private fields */
}

Withdrawal queue storage with FIFO ordering.

Maintains pending withdrawals keyed by monotonic IDs with escrow parity. The queue uses a sorted Vec for efficient iteration and predictable serialization, with two pointers to track the FIFO head and next ID to allocate.

Invariants

• pending_withdrawals.len() <= max_pending_withdrawals <= MAX_PENDING
• next_withdraw_to_execute <= next_pending_withdrawal_id
• If pending_withdrawals.len() > 0, then pending_withdrawals contains next_withdraw_to_execute
• FIFO withdrawal ordering; no skipping head
• cached_total_escrow == sum(pending_withdrawals.values().map(|w| w.escrow_shares))
• cached_total_expected == sum(pending_withdrawals.values().map(|w| w.expected_assets))

Fields

next_withdraw_to_execute: u64

ID of the next withdrawal to execute (queue head).

next_pending_withdrawal_id: u64

Next ID to allocate for new withdrawals (monotonic, never decremented).

Implementations

impl WithdrawQueue

pub fn new() -> Self

Create a new empty withdrawal queue.

pub fn with_state<I>( pending_withdrawals: I, next_withdraw_to_execute: u64, next_pending_withdrawal_id: u64, ) -> Self

where I: IntoIterator<Item = (u64, PendingWithdrawal)>,

Create a queue with initial state (for testing or recovery).

pub fn len(&self) -> usize

Returns the current queue length.

pub fn pending_withdrawals(&self) -> &PendingWithdrawals

pub fn is_empty(&self) -> bool

Returns true if the queue is empty.

pub fn can_enqueue(&self, max_pending: u32) -> bool

Check if the queue can accept a new withdrawal given the max limit.

Arguments

• max_pending - Maximum allowed pending withdrawals.

Returns

true if the queue has room for another withdrawal.

pub fn enqueue( &mut self, owner: Address, receiver: Address, escrow_shares: u128, expected_assets: u128, requested_at_ns: TimestampNs, max_pending: u32, ) -> Result<u64, QueueError>

Enqueue a new pending withdrawal.

Convenience wrapper that constructs a PendingWithdrawal and delegates to enqueue_withdrawal.

pub fn enqueue_withdrawal( &mut self, withdrawal: PendingWithdrawal, max_pending: u32, ) -> Result<u64, QueueError>

Enqueue a pre-constructed pending withdrawal.

Allocates a new monotonic ID and inserts the withdrawal at the tail.

Returns

Ok(id) with the allocated withdrawal ID, or Err(QueueError) if full.

pub fn head(&self) -> Option<(u64, &PendingWithdrawal)>

Get the head of the queue without removing it.

Returns

Some((id, &withdrawal)) if non-empty, None if empty.

pub fn dequeue(&mut self) -> Option<(u64, PendingWithdrawal)>

Dequeue and return the head of the queue (FIFO).

Removes the head and advances next_withdraw_to_execute to the next available ID in the queue (or to next_pending_withdrawal_id if empty).

Returns

Some((id, withdrawal)) if non-empty, None if empty.

pub fn get(&self, id: u64) -> Option<&PendingWithdrawal>

Get a pending withdrawal by ID.

Arguments

• id - The withdrawal ID to look up.

Returns

Some(&withdrawal) if found, None otherwise.

pub fn contains(&self, id: u64) -> bool

Check if a withdrawal ID exists in the queue.

Arguments

• id - The withdrawal ID to check.

Returns

true if the withdrawal exists.

pub fn iter(&self) -> impl Iterator<Item = (u64, &PendingWithdrawal)>

Iterate over all pending withdrawals in FIFO order.

Returns

Iterator yielding (id, &withdrawal) pairs in order.

pub fn check_invariants(&self) -> bool

Check invariants for the withdrawal queue.

Validates:

• next_withdraw_to_execute <= next_pending_withdrawal_id
• If non-empty, head ID exists in the map
• Cached totals match computed totals

Returns

true if all invariants hold.

pub fn check_invariants_with_max(&self, max_pending: u32) -> bool

Check invariants including the max pending limit.

Arguments

• max_pending - Maximum allowed pending withdrawals.

Returns

true if all invariants hold including queue length bounds.

pub fn status(&self) -> QueueStatus

Compute aggregate queue statistics.

Returns

QueueStatus with totals.

pub fn total_escrow_shares(&self) -> u128

Get total escrowed shares across all pending withdrawals.

Returns cached value in O(1) time.

Returns

Total escrow shares.

pub fn total_expected_assets(&self) -> u128

Get total expected assets across all pending withdrawals.

Returns cached value in O(1) time.

Returns

Total expected assets.

Trait Implementations

impl BorshDeserialize for WithdrawQueue

fn deserialize_reader<__R: Read>(reader: &mut __R) -> Result<Self, Error>

fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>

Deserializes this instance from a given slice of bytes. Updates the buffer to point at the remaining bytes.

fn try_from_slice(v: &[u8]) -> Result<Self, Error>

Deserialize this instance from a slice of bytes.

fn try_from_reader<R>(reader: &mut R) -> Result<Self, Error>

where R: Read,

impl BorshSchema for WithdrawQueue

fn declaration() -> Declaration

Get the name of the type without brackets.

fn add_definitions_recursively( definitions: &mut BTreeMap<Declaration, Definition>, )

Recursively, using DFS, add type definitions required for this type. Type definition partially explains how to serialize/deserialize a type.

impl BorshSerialize for WithdrawQueue

fn serialize<__W: Write>(&self, writer: &mut __W) -> Result<(), Error>

impl Clone for WithdrawQueue

fn clone(&self) -> WithdrawQueue

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WithdrawQueue

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

Formats the value using the given formatter.

impl Default for WithdrawQueue

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for WithdrawQueue

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for WithdrawQueue

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for WithdrawQueue

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for WithdrawQueue

impl StructuralPartialEq for WithdrawQueue