tape-core 0.4.4

A decentralized object store using Solana.
Documentation
use bytemuck::{Pod, Zeroable};
use crate::types::*;
use super::value::EpochValues;

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScheduleError {
    ScheduleFailed,
}

#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PoolSchedule<const N: usize> {
    /// The scheduled commission rate changes, scheduled for future epochs.
    pub commission_changes: EpochValues<N>,

    /// The scheduled stake additions, scheduled for future epochs.
    pub incoming_tokens: EpochValues<N>,

    /// The scheduled pre-active stake cancellations, scheduled for future epochs.
    pub outgoing_tokens: EpochValues<N>,

    /// The scheduled share withdrawals, scheduled for future epochs.
    pub outgoing_shares: EpochValues<N>,
}

impl<const N: usize> Default for PoolSchedule<N> {
    fn default() -> Self {
        Self::new()
    }
}

impl<const N: usize> PoolSchedule<N> {
    pub fn new() -> Self {
        Self {
            commission_changes: EpochValues::new(),
            incoming_tokens: EpochValues::new(),
            outgoing_tokens: EpochValues::new(),
            outgoing_shares: EpochValues::new(),
        }
    }

    #[inline]
    pub fn stake(
        &mut self,
        epoch: EpochNumber,
        amount: Coin<TAPE>,
    ) -> Result<(), ScheduleError> {
        self.incoming_tokens
            .add_at(epoch, amount.into())
            .map_err(|_| ScheduleError::ScheduleFailed)
    }

    #[inline]
    pub fn cancel(
        &mut self,
        epoch: EpochNumber,
        amount: Coin<TAPE>,
    ) -> Result<(), ScheduleError> {
        self.outgoing_tokens
            .add_at(epoch, amount.into())
            .map_err(|_| ScheduleError::ScheduleFailed)
    }

    #[inline]
    pub fn unstake(
        &mut self,
        epoch: EpochNumber,
        shares: ShareAmount,
    ) -> Result<(), ScheduleError> {
        self.outgoing_shares
            .add_at(epoch, shares.into())
            .map_err(|_| ScheduleError::ScheduleFailed)
    }

    #[inline]
    pub fn set_commission(
        &mut self,
        epoch: EpochNumber,
        new_rate: BasisPoints,
    ) -> Result<(), ScheduleError> {
        self.commission_changes
            .set_at(epoch, new_rate.into())
            .map_err(|_| ScheduleError::ScheduleFailed)
    }

    /// Get the commission rate change scheduled exactly at `epoch` (if any).
    #[inline]
    pub fn commission_at(&self, epoch: EpochNumber) -> Option<BasisPoints> {
        self.commission_changes.get_at(epoch).map(BasisPoints)
    }

    /// Sum of incoming stake scheduled at or before `epoch`.
    #[inline]
    pub fn stake_sum(&self, epoch: EpochNumber) -> Coin<TAPE> {
        self.incoming_tokens.sum_through(epoch).into()
    }

    /// Sum of pre-activation cancels scheduled at or before `epoch`.
    #[inline]
    pub fn cancel_sum(&self, epoch: EpochNumber) -> Coin<TAPE> {
        self.outgoing_tokens.sum_through(epoch).into()
    }

    /// Sum of share withdrawals scheduled at or before `epoch`.
    #[inline]
    pub fn unstake_sum(&self, epoch: EpochNumber) -> ShareAmount {
        self.outgoing_shares.sum_through(epoch).into()
    }

    /// If there is a commission rate change scheduled exactly at `epoch`,
    /// return it and clear all commission entries with e <= epoch.
    /// If there is no exact entry, do nothing and return None.
    #[inline]
    pub fn take_commission_change(&mut self, epoch: EpochNumber) -> Option<BasisPoints> {
        let exact = self.commission_changes.get_at(epoch);
        if exact.is_some() {
            // Clear all <= epoch to mirror previous semantics
            self.commission_changes.drain_through(epoch);
        }
        exact.map(BasisPoints)
    }

    /// Drain and sum all incoming stake with e <= epoch.
    #[inline]
    pub fn take_incoming(&mut self, epoch: EpochNumber) -> Coin<TAPE> {
        self.incoming_tokens.drain_through(epoch).into()
    }

    /// Drain and sum all cancels with e <= epoch.
    #[inline]
    pub fn take_outgoing(&mut self, epoch: EpochNumber) -> Coin<TAPE> {
        self.outgoing_tokens.drain_through(epoch).into()
    }

    /// Drain and sum all outgoing shares with e <= epoch.
    #[inline]
    pub fn take_outgoing_shares(&mut self, epoch: EpochNumber) -> ShareAmount {
        self.outgoing_shares.drain_through(epoch).into()
    }

    #[inline]
    pub fn commission_count(&self) -> usize { self.commission_changes.len() }

    #[inline]
    pub fn incoming_count(&self) -> usize { self.incoming_tokens.len() }

    #[inline]
    pub fn outgoing_count(&self) -> usize { self.outgoing_tokens.len() }

    #[inline]
    pub fn outgoing_shares_count(&self) -> usize { self.outgoing_shares.len() }

    /// Total incoming stake across all scheduled epochs.
    #[inline]
    pub fn total_incoming(&self) -> Coin<TAPE> {
        self.incoming_tokens.sum_through(EpochNumber(u64::MAX)).into()
    }

    /// Total pre-activation cancellations across all scheduled epochs.
    #[inline]
    pub fn total_outgoing(&self) -> Coin<TAPE> {
        self.outgoing_tokens.sum_through(EpochNumber(u64::MAX)).into()
    }
}

unsafe impl<const N: usize> Zeroable for PoolSchedule<N> {}
unsafe impl<const N: usize> Pod for PoolSchedule<N> {}

#[cfg(test)]
mod tests {
    use super::*;

    fn epoch(n: u64) -> EpochNumber { EpochNumber(n) }
    fn tape(v: u64) -> Coin<TAPE> { TAPE(v) }
    fn shares(v: u64) -> ShareAmount { ShareAmount(v) }

    #[test]
    fn new_ok() {
        let s = PoolSchedule::<4>::new();

        assert_eq!(s.commission_count(), 0);
        assert_eq!(s.incoming_count(), 0);
        assert_eq!(s.outgoing_count(), 0);
        assert_eq!(s.outgoing_shares_count(), 0);
    }

    #[test]
    fn schedule_commission() {
        let mut s = PoolSchedule::<4>::new();
        s.set_commission(epoch(5), BasisPoints(1000)).unwrap();
        s.set_commission(epoch(7), BasisPoints(1500)).unwrap();

        assert_eq!(s.commission_at(epoch(5)), Some(BasisPoints(1000)));
        assert_eq!(s.commission_at(epoch(6)), None);
        assert_eq!(s.commission_at(epoch(7)), Some(BasisPoints(1500)));

        // Taking at 5 clears entries <= 5 but keeps later ones
        let taken = s.take_commission_change(epoch(5));
        assert_eq!(taken, Some(BasisPoints(1000)));
        assert_eq!(s.commission_at(epoch(5)), None);
        assert_eq!(s.commission_at(epoch(7)), Some(BasisPoints(1500)));
    }

    #[test]
    fn schedule_and_drain() {
        let mut s = PoolSchedule::<8>::new();

        s.stake(epoch(4), tape(100)).unwrap();
        s.stake(epoch(6), tape(50)).unwrap();
        s.cancel(epoch(6), tape(20)).unwrap();

        assert_eq!(s.stake_sum(epoch(3)), tape(0));
        assert_eq!(s.stake_sum(epoch(4)), tape(100));
        assert_eq!(s.stake_sum(epoch(6)), tape(150));
        assert_eq!(s.cancel_sum(epoch(6)), tape(20));

        // drain incoming up to 5 keeps epoch 6
        let res = s.take_incoming(epoch(5));

        assert_eq!(res, tape(100));
        assert_eq!(s.stake_sum(epoch(4)), tape(0));
        assert_eq!(s.stake_sum(epoch(6)), tape(50));

        // drain cancels up to 6 clears that entry
        let res = s.take_outgoing(epoch(6));
        assert_eq!(res, tape(20));
        assert_eq!(s.cancel_sum(epoch(6)), tape(0));
    }

    #[test]
    fn schedule_capacity() {
        // With capacity 1, two distinct epochs should exceed capacity
        let mut s = PoolSchedule::<1>::new();

        s.unstake(epoch(10), shares(123)).unwrap();
        let err = s.unstake(epoch(11), shares(1)).unwrap_err();
        assert!(matches!(err, ScheduleError::ScheduleFailed));
    }

    #[test]
    fn drain_outgoing_shares() {
        let mut s = PoolSchedule::<8>::new();

        s.unstake(epoch(3), shares(50)).unwrap();
        s.unstake(epoch(5), shares(30)).unwrap();
        s.unstake(epoch(7), shares(20)).unwrap();

        // Before drain
        assert_eq!(s.unstake_sum(epoch(2)), shares(0));
        assert_eq!(s.unstake_sum(epoch(5)), shares(80));

        // Drain shares with e <= 5
        let drained = s.take_outgoing_shares(epoch(5));
        assert_eq!(drained, shares(80));

        // Entries <= 5 cleared; only epoch 7 remains
        assert_eq!(s.unstake_sum(epoch(5)), shares(0));
        assert_eq!(s.unstake_sum(epoch(7)), shares(20));
    }

    #[test]
    fn total_incoming_outgoing() {
        let mut s = PoolSchedule::<8>::new();

        // Add incoming stake across multiple epochs
        s.stake(epoch(3), tape(100)).unwrap();
        s.stake(epoch(5), tape(200)).unwrap();
        s.stake(epoch(7), tape(300)).unwrap();

        assert_eq!(s.total_incoming(), tape(600));

        // Add outgoing (cancel) across multiple epochs
        s.cancel(epoch(3), tape(50)).unwrap();
        s.cancel(epoch(5), tape(100)).unwrap();

        assert_eq!(s.total_outgoing(), tape(150));

        // Take some - should reduce totals
        let _ = s.take_incoming(epoch(3));
        assert_eq!(s.total_incoming(), tape(500)); // 200 + 300

        let _ = s.take_outgoing(epoch(3));
        assert_eq!(s.total_outgoing(), tape(100)); // 100
    }

    #[test]
    fn total_incoming_empty() {
        let s = PoolSchedule::<4>::new();

        assert_eq!(s.total_incoming(), tape(0));
        assert_eq!(s.total_outgoing(), tape(0));
    }
}