zingolib 0.0.1

Zingo backend library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

//! Sync implementations for [crate::lightclient::LightClient] and related types.

use std::borrow::BorrowMut;
use std::sync::atomic;
use std::time::Duration;

use futures::FutureExt;
use pepper_sync::error::SyncError;
use pepper_sync::error::SyncModeError;
use pepper_sync::wallet::SyncMode;

use crate::data::PollReport;
use crate::wallet::error::WalletError;

use super::LightClient;
use super::SyncResult;
use super::error::LightClientError;

impl LightClient {
    /// Launches a task for syncing the wallet to the latest state of the block chain, storing the handle in the
    /// `sync_handle` field.
    // TODO: add realtime sync updates to zingo-cli when it can handle printing during user input
    pub async fn sync(&mut self) -> Result<(), LightClientError> {
        if self.sync_mode() != SyncMode::NotRunning {
            return Err(LightClientError::SyncModeError(
                SyncModeError::SyncAlreadyRunning,
            ));
        }

        let client = zingo_netutils::GrpcConnector::new(self.config.get_lightwalletd_uri())
            .get_client()
            .await?;
        let wallet_guard = self.wallet.lock().await;
        let network = wallet_guard.network;
        let sync_config = wallet_guard.wallet_settings.sync_config.clone();
        drop(wallet_guard);
        let wallet = self.wallet.clone();
        let sync_mode = self.sync_mode.clone();
        let sync_handle = tokio::spawn(async move {
            pepper_sync::sync(client, &network, wallet, sync_mode, sync_config).await
        });
        self.sync_handle = Some(sync_handle);

        Ok(())
    }

    /// Clear the wallet data obtained from the blockchain and launch sync from wallet birthday.
    ///
    /// If sync is already running, stops sync and waits for it to shutdown before clearing the wallet and rescanning.
    pub async fn rescan(&mut self) -> Result<(), LightClientError> {
        if self.sync_mode() != SyncMode::NotRunning {
            self.stop_sync().expect("infallible in this scope");

            let mut interval = tokio::time::interval(Duration::from_millis(500));
            interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
            interval.tick().await;
            while matches!(self.poll_sync(), PollReport::NotReady) {
                interval.tick().await;
            }
        }
        self.wallet.lock().await.clear_all();
        self.sync().await
    }

    /// Returns the lightclient's sync mode in non-atomic (enum) form.
    pub fn sync_mode(&self) -> SyncMode {
        SyncMode::from_atomic_u8(self.sync_mode.clone())
            .expect("this library does not allow setting of non-valid sync mode variants")
    }

    /// Pause the sync engine, releasing the wallet lock until [`crate::lightclient::LightClient::resume_sync`] is called.
    ///
    /// Returns an error if sync is not running or paused.
    pub fn pause_sync(&self) -> Result<(), SyncModeError> {
        if self.sync_mode() != SyncMode::Running {
            return Err(SyncModeError::SyncNotRunning);
        }
        self.sync_mode
            .store(SyncMode::Paused as u8, atomic::Ordering::Release);

        Ok(())
    }

    /// Stop the sync engine after the next batch is scanned.
    ///
    /// Returns an error if sync is not running.
    pub fn stop_sync(&self) -> Result<(), SyncModeError> {
        if self.sync_mode() == SyncMode::NotRunning {
            return Err(SyncModeError::SyncNotRunning);
        }
        self.sync_mode
            .store(SyncMode::Shutdown as u8, atomic::Ordering::Release);

        Ok(())
    }

    /// Resume scanning after [`crate::lightclient::LightClient::pause_sync`] has been called.
    ///
    /// Returns an error if sync is not paused.
    pub fn resume_sync(&self) -> Result<(), SyncModeError> {
        if self.sync_mode() != SyncMode::Paused {
            return Err(SyncModeError::SyncNotPaused);
        }
        self.sync_mode
            .store(SyncMode::Running as u8, atomic::Ordering::Release);

        Ok(())
    }

    /// Polls the sync task, returning [`self::PollReport`].
    pub fn poll_sync(&mut self) -> PollReport<SyncResult, SyncError<WalletError>> {
        if let Some(mut sync_handle) = self.sync_handle.take() {
            if let Some(sync_result) = sync_handle.borrow_mut().now_or_never() {
                self.sync_mode
                    .store(SyncMode::NotRunning as u8, atomic::Ordering::Release);
                PollReport::Ready(sync_result.expect("task panicked"))
            } else {
                self.sync_handle = Some(sync_handle);
                PollReport::NotReady
            }
        } else {
            PollReport::NoHandle
        }
    }

    /// Awaits until sync has successfully completed or failed.
    /// Returns [`pepper_sync::sync::SyncResult`] if successful.
    /// Returns [`crate::lightclient::error::LightClientError`] on failure.
    pub async fn await_sync(&mut self) -> Result<SyncResult, LightClientError> {
        let mut interval = tokio::time::interval(Duration::from_millis(500));
        interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
        loop {
            interval.tick().await;
            match self.poll_sync() {
                PollReport::NoHandle => return Err(LightClientError::SyncNotRunning),
                PollReport::NotReady => (),
                PollReport::Ready(result) => return result.map_err(LightClientError::SyncError),
            }
        }
    }

    /// Calls [`crate::lightclient::LightClient::sync`] and then [`crate::lightclient::LightClient::await_sync`].
    pub async fn sync_and_await(&mut self) -> Result<SyncResult, LightClientError> {
        self.sync().await?;
        self.await_sync().await
    }

    /// Calls [`crate::lightclient::LightClient::rescan`] and then [`crate::lightclient::LightClient::await_sync`].
    pub async fn rescan_and_await(&mut self) -> Result<SyncResult, LightClientError> {
        self.rescan().await?;
        self.await_sync().await
    }
}

#[cfg(test)]
pub mod test {
    use crate::{lightclient::LightClient, wallet::disk::testing::examples};

    /// loads a wallet from example data
    /// turns on the internet tube
    /// and syncs to the present blockchain moment
    pub(crate) async fn sync_example_wallet(
        wallet_case: examples::NetworkSeedVersion,
    ) -> LightClient {
        // install default crypto provider (ring)
        if let Err(e) = rustls::crypto::ring::default_provider().install_default() {
            log::error!("Error installing crypto provider: {:?}", e)
        };

        let mut lc = wallet_case.load_example_wallet_with_client().await;

        let sync_result = lc.sync_and_await().await.unwrap();
        println!("{}", sync_result);
        println!("{:?}", lc.do_balance().await);
        lc
    }

    mod testnet {
        use super::{examples, sync_example_wallet};
        /// this is a live sync test. its execution time scales linearly since last updated
        #[ignore = "live chain experiment"]
        #[tokio::test]
        async fn testnet_sync_mskmgdbhotbpetcjwcspgopp() {
            sync_example_wallet(examples::NetworkSeedVersion::Testnet(
                examples::TestnetSeedVersion::MobileShuffle(examples::MobileShuffleVersion::Latest),
            ))
            .await;
        }
        /// this is a live sync test. its execution time scales linearly since last updated
        #[ignore = "live chain experiment"]
        #[tokio::test]
        async fn testnet_sync_cbbhrwiilgbrababsshsmtpr() {
            sync_example_wallet(examples::NetworkSeedVersion::Testnet(
                examples::TestnetSeedVersion::ChimneyBetter(examples::ChimneyBetterVersion::Latest),
            ))
            .await;
        }
    }
    /// this is a live sync test. its execution time scales linearly since last updated
    #[tokio::test]
    #[ignore = "testnet and mainnet tests should be ignored due to increasingly large execution times"]
    async fn mainnet_sync() {
        sync_example_wallet(examples::NetworkSeedVersion::Mainnet(
            examples::MainnetSeedVersion::HotelHumor(examples::HotelHumorVersion::Gf0aaf9347),
        ))
        .await;
    }
}