pepper-sync 0.7.0

//! Sync configuration.

#[cfg(feature = "wallet_essentials")]
use std::io::{Read, Write};

#[cfg(feature = "wallet_essentials")]
use byteorder::{ReadBytesExt, WriteBytesExt};

/// Performance level.
///
/// The higher the performance level the higher the memory usage and storage.
// TODO: revisit after implementing nullifier refetching
#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
pub enum PerformanceLevel {
    /// - output budget per scan load is quartered
    /// - nullifier map only contains chain tip
    Low,
    /// - nullifier map has a small maximum size
    /// - nullifier map only contains chain tip
    Medium,
    /// - nullifier map has a large maximum size
    #[default]
    High,
    /// - output budget per scan load is quadrupled
    /// - nullifier map has no maximum size
    ///
    /// WARNING: this may cause the wallet to become less responsive on slower systems and may use a lot of memory for
    /// wallets with a lot of transactions.
    Maximum,
}

#[cfg(feature = "wallet_essentials")]
impl PerformanceLevel {
    fn serialized_version() -> u8 {
        0
    }

    /// Deserialize into `reader`
    pub fn read<R: Read>(mut reader: R) -> std::io::Result<Self> {
        crate::wallet::serialization::read_version(
            &mut reader,
            "PerformanceLevel",
            Self::serialized_version(),
        )?;

        Ok(match reader.read_u8()? {
            0 => Self::Low,
            1 => Self::Medium,
            2 => Self::High,
            3 => Self::Maximum,
            _ => {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::InvalidData,
                    "failed to read valid performance level",
                ));
            }
        })
    }

    /// Serialize into `writer`
    pub fn write<W: Write>(&mut self, mut writer: W) -> std::io::Result<()> {
        writer.write_u8(Self::serialized_version())?;

        writer.write_u8(match self {
            Self::Low => 0,
            Self::Medium => 1,
            Self::High => 2,
            Self::Maximum => 3,
        })?;

        Ok(())
    }
}

impl std::fmt::Display for PerformanceLevel {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Low => write!(f, "low"),
            Self::Medium => write!(f, "medium"),
            Self::High => write!(f, "high"),
            Self::Maximum => write!(f, "maximum"),
        }
    }
}

/// Sync configuration.
#[derive(Default, Debug, Clone, PartialEq, Eq)]
pub struct SyncConfig {
    /// Transparent address discovery configuration.
    pub transparent_address_discovery: TransparentAddressDiscovery,
    /// Performance level
    pub performance_level: PerformanceLevel,
    /// Shutdown on completion
    ///
    /// If not set, sync will not shutdown until the consumer sets the `SyncMode` to `Shutdown` variant.
    /// The sync engine will regularly check for new blocks mined so the wallet will always be updated to the state
    /// of the latest chain.
    ///
    /// If set, sync will still check for any newly mined blocks during scanning. But when the wallet is completely
    /// up-to-date with the latest chain, a running sync will shutdown. A sync the consumer has paused stays paused,
    /// and shuts down once it is resumed and completes again.
    pub shutdown_on_completion: bool,
}

#[cfg(feature = "wallet_essentials")]
impl SyncConfig {
    fn serialized_version() -> u8 {
        2
    }

    /// Deserialize into `reader`
    pub fn read<R: Read>(mut reader: R) -> std::io::Result<Self> {
        let version = crate::wallet::serialization::read_version(
            &mut reader,
            "SyncConfig",
            Self::serialized_version(),
        )?;

        let gap_limit = reader.read_u8()?;
        let scopes = reader.read_u8()?;
        let performance_level = if version >= 1 {
            PerformanceLevel::read(&mut reader)?
        } else {
            PerformanceLevel::High
        };
        let shutdown_on_completion = if version >= 2 {
            reader.read_u8()? != 0
        } else {
            false
        };

        Ok(Self {
            transparent_address_discovery: TransparentAddressDiscovery {
                gap_limit,
                scopes: TransparentAddressDiscoveryScopes {
                    external: scopes & 0b1 != 0,
                    internal: scopes & 0b10 != 0,
                    refund: scopes & 0b100 != 0,
                },
            },
            performance_level,
            shutdown_on_completion,
        })
    }

    /// Serialize into `writer`
    pub fn write<W: Write>(&mut self, mut writer: W) -> std::io::Result<()> {
        writer.write_u8(Self::serialized_version())?;
        writer.write_u8(self.transparent_address_discovery.gap_limit)?;
        let mut scopes = 0;
        if self.transparent_address_discovery.scopes.external {
            scopes |= 0b1;
        }
        if self.transparent_address_discovery.scopes.internal {
            scopes |= 0b10;
        }
        if self.transparent_address_discovery.scopes.refund {
            scopes |= 0b100;
        }
        writer.write_u8(scopes)?;
        self.performance_level.write(&mut writer)?;
        writer.write_u8(self.shutdown_on_completion as u8)?;

        Ok(())
    }
}

/// Transparent address configuration.
///
/// Sets which `scopes` will be searched for addresses in use, scanning relevant transactions, up to a given `gap_limit`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransparentAddressDiscovery {
    /// Sets the gap limit for transparent address discovery.
    pub gap_limit: u8,
    /// Sets the scopes for transparent address discovery.
    pub scopes: TransparentAddressDiscoveryScopes,
}

impl Default for TransparentAddressDiscovery {
    fn default() -> Self {
        Self {
            gap_limit: 10,
            scopes: TransparentAddressDiscoveryScopes::default(),
        }
    }
}

impl TransparentAddressDiscovery {
    /// Constructs a transparent address discovery config with a gap limit of 1 and ignoring the internal scope.
    #[must_use]
    pub fn minimal() -> Self {
        Self {
            gap_limit: 1,
            scopes: TransparentAddressDiscoveryScopes::default(),
        }
    }

    /// Constructs a transparent address discovery config with a gap limit of 20 for all scopes.
    #[must_use]
    pub fn recovery() -> Self {
        Self {
            gap_limit: 20,
            scopes: TransparentAddressDiscoveryScopes::recovery(),
        }
    }

    /// Disables transparent address discovery. Sync will only scan transparent outputs for addresses already in the
    /// wallet in transactions that also contain shielded inputs or outputs relevant to the wallet.
    #[must_use]
    pub fn disabled() -> Self {
        Self {
            gap_limit: 0,
            scopes: TransparentAddressDiscoveryScopes {
                external: false,
                internal: false,
                refund: false,
            },
        }
    }
}

/// Sets the active scopes for transparent address recovery.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransparentAddressDiscoveryScopes {
    /// External.
    pub external: bool,
    /// Internal.
    pub internal: bool,
    /// Refund.
    pub refund: bool,
}

impl Default for TransparentAddressDiscoveryScopes {
    fn default() -> Self {
        Self {
            external: true,
            internal: false,
            refund: true,
        }
    }
}

impl TransparentAddressDiscoveryScopes {
    /// Constructor with all all scopes active.
    #[must_use]
    pub fn recovery() -> Self {
        Self {
            external: true,
            internal: true,
            refund: true,
        }
    }
}

#[cfg(all(test, feature = "wallet_essentials"))]
mod tests {
    use super::*;

    /// Each reader is given only a serialized version above the one its type writes. A reader that refuses the
    /// version returns invalid data. A reader that read on would report the end of the input.
    #[test]
    fn readers_refuse_serialized_versions_above_their_own() {
        let newer_sync_config = [SyncConfig::serialized_version() + 1];
        let newer_performance_level = [PerformanceLevel::serialized_version() + 1];

        for (type_name, read) in [
            (
                "SyncConfig",
                SyncConfig::read(newer_sync_config.as_slice()).map(drop),
            ),
            (
                "PerformanceLevel",
                PerformanceLevel::read(newer_performance_level.as_slice()).map(drop),
            ),
        ] {
            assert_eq!(
                read.expect_err(type_name).kind(),
                std::io::ErrorKind::InvalidData,
                "{type_name}"
            );
        }
    }
}