Struct TestState 

pub struct TestState<Cache, DataStore: WalletTest, Network> { /* private fields */ }

Available on crate features test-dependencies only.

Implementations

impl<Cache, DataStore: WalletTest, Network> TestState<Cache, DataStore, Network>

pub fn clock(&self) -> &FixedClock

Exposes the fixed clock that this test state passes to wallet operations.

pub fn wallet(&self) -> &DataStore

Exposes an immutable reference to the test’s DataStore.

pub fn wallet_mut(&mut self) -> &mut DataStore

Exposes a mutable reference to the test’s DataStore.

pub fn rng_mut(&mut self) -> &mut ChaChaRng

Exposes the test framework’s source of randomness.

pub fn network(&self) -> &Network

Exposes the network in use.

impl<Cache, DataStore: WalletTest, Network: Parameters> TestState<Cache, DataStore, Network>

pub fn sapling_activation_height(&self) -> BlockHeight

Convenience method for obtaining the Sapling activation height for the network under test.

pub fn nu5_activation_height(&self) -> BlockHeight

Convenience method for obtaining the NU5 activation height for the network under test.

pub fn test_seed(&self) -> Option<&SecretVec<u8>>

Exposes the seed for the test wallet.

pub fn test_account( &self, ) -> Option<&TestAccount<<DataStore as WalletRead>::Account>>

Returns a reference to the test account, if one was configured.

pub fn test_account_sapling(&self) -> Option<&DiversifiableFullViewingKey>

Returns the test account’s Sapling DFVK, if one was configured.

pub fn test_account_orchard(&self) -> Option<&FullViewingKey>

Available on crate feature orchard only.

Returns the test account’s Orchard FVK, if one was configured.

impl<Cache, DataStore, Network> TestState<Cache, DataStore, Network>

where DataStore: WalletTest + WalletWrite, Network: Parameters,

pub fn create_account_from_test_seed( &mut self, account_name: &str, ) -> (<DataStore as WalletRead>::AccountId, UnifiedSpendingKey)

Creates a FURTHER account under the test seed, at the test account’s birthday, and returns its id and spending key.

The wallet assigns the next unused ZIP 32 account index, so this is a sibling of the account TestBuilder configured — the shape a test needs to check that some answer is scoped to the account it was asked of, rather than to the wallet.

Create every account a test needs BEFORE scanning anything: account creation adjusts the scan queue, which clears the wallet’s fully-scanned height.

impl<Cache: TestCache, DataStore, Network> TestState<Cache, DataStore, Network>

where Network: Parameters, DataStore: WalletTest + WalletWrite, <Cache::BlockSource as BlockSource>::Error: Debug,

pub fn cache(&self) -> &Cache::BlockSource

Available on crate feature unstable only.

Exposes an immutable reference to the test’s BlockSource.

pub fn latest_cached_block(&self) -> Option<&CachedBlock>

Returns the cached chain state corresponding to the latest block generated by this TestState.

pub fn generate_next_block<Fvk: TestFvk>( &mut self, recipient_fvk: &Fvk, recipient_address_type: AddressType, value: Zatoshis, ) -> (BlockHeight, Cache::InsertResult, Fvk::Nullifier)

Creates a fake block at the expected next height containing a single output of the given value, and inserts it into the cache.

This is a proxy for generate_next_block_multi.

pub fn generate_next_block_multi<Fvk: TestFvk>( &mut self, outputs: &[FakeCompactOutput<Fvk>], ) -> (BlockHeight, Cache::InsertResult, Vec<Fvk::Nullifier>)

Creates a fake block at the expected next height containing multiple outputs and inserts it into the cache.

pub fn generate_next_block_transparent( &mut self, vin: &[OutPoint], vout: &[(TransparentAddress, Zatoshis)], ) -> (BlockHeight, Cache::InsertResult, TxId)

Available on crate feature transparent-inputs only.

Adds a block at the next height containing a single transparent-only transaction that spends vin and creates an output of each (address, value) in vout, and inserts it into the cache.

The transaction is placed at index 1 within the block, behind a placeholder occupying the coinbase position, so that the outputs it creates are not subject to the coinbase maturity rule. Returns the height of the block and the id of the transparent transaction.

pub fn generate_empty_block(&mut self) -> (BlockHeight, Cache::InsertResult)

Adds an empty block to the cache, advancing the simulated chain height.

pub fn generate_block_at<Fvk: TestFvk>( &mut self, height: BlockHeight, prev_hash: BlockHash, outputs: &[FakeCompactOutput<Fvk>], initial_sapling_tree_size: u32, initial_orchard_tree_size: u32, initial_ironwood_tree_size: u32, allow_broken_hash_chain: bool, ) -> (Cache::InsertResult, Vec<Fvk::Nullifier>)

Creates a fake block with the given height and hash containing the requested outputs, and inserts it into the cache.

This generated block will be treated as the latest block, and subsequent calls to Self::generate_next_block will build on it.

pub fn generate_next_block_spending<Fvk: TestFvk>( &mut self, sender_fvk: &Fvk, note: (Fvk::Nullifier, Zatoshis), to: impl Into<Address>, value: Zatoshis, ) -> (BlockHeight, Cache::InsertResult)

Creates a fake block at the expected next height spending the given note, and inserts it into the cache.

pub fn generate_next_block_including( &mut self, txid: TxId, ) -> (BlockHeight, Cache::InsertResult)

Creates a fake block at the expected next height containing only the wallet transaction with the given txid, and inserts it into the cache.

This generated block will be treated as the latest block, and subsequent calls to Self::generate_next_block (or similar) will build on it.

pub fn generate_next_block_from_tx( &mut self, tx_index: usize, tx: &Transaction, ) -> (BlockHeight, Cache::InsertResult)

Creates a fake block at the expected next height containing only the given transaction, and inserts it into the cache.

This generated block will be treated as the latest block, and subsequent calls to Self::generate_next_block will build on it.

pub fn truncate_to_height(&mut self, height: BlockHeight)

Truncates the test wallet and block cache to the specified height, discarding all data from blocks at heights greater than the specified height, excluding transaction data that may not be recoverable from the chain.

pub fn truncate_to_height_retaining_cache(&mut self, height: BlockHeight)

Truncates the test wallet to the specified height, and resets the cache’s latest block height but does not truncate the block cache. This is useful for circumstances when you want to re-scan a set of cached blocks.

impl<Cache, DbT, ParamsT> TestState<Cache, DbT, ParamsT>

where Cache: TestCache, <Cache::BlockSource as BlockSource>::Error: Debug, ParamsT: Parameters + Send + 'static, DbT: InputSource + WalletTest + WalletWrite + WalletCommitmentTrees, <DbT as WalletRead>::AccountId: Debug + ConditionallySelectable + Default + Send + Sync + 'static,

pub fn scan_cached_blocks( &mut self, from_height: BlockHeight, limit: usize, ) -> ScanSummary

Invokes scan_cached_blocks with the given arguments, expecting success.

pub fn try_scan_cached_blocks( &mut self, from_height: BlockHeight, limit: usize, ) -> Result<ScanSummary, Error<<DbT as WalletRead>::Error, <Cache::BlockSource as BlockSource>::Error>>

Invokes scan_cached_blocks with the given arguments.

pub fn try_scan_cached_blocks_with_state( &mut self, from_height: BlockHeight, from_state: &ChainState, limit: usize, ) -> Result<ScanSummary, Error<<DbT as WalletRead>::Error, <Cache::BlockSource as BlockSource>::Error>>

Invokes scan_cached_blocks with a caller-supplied from_state instead of deriving it from the block cache.

This is primarily useful for tests that need to drive WalletWrite::put_blocks with a from_state that is deliberately inconsistent with the wallet’s stored note commitment tree state, in order to exercise the resulting error paths.

pub fn put_subtree_roots( &mut self, sapling_start_index: u64, sapling_roots: &[CommitmentTreeRoot<Node>], orchard_start_index: u64, orchard_roots: &[CommitmentTreeRoot<MerkleHashOrchard>], ) -> Result<(), ShardTreeError<<DbT as WalletCommitmentTrees>::Error>>

Insert shard roots for both trees.

pub fn generate_and_scan_empty_blocks(&mut self, n: usize) -> BlockHeight

Generates n empty blocks, scans each, and returns the wallet’s resulting fully-scanned height.

This is the “let the chain advance” step of a test that needs the scanned region to reach a chosen depth above some earlier height — an anchor boundary a fixed number of blocks below the tip, say — with none of the intervening blocks carrying wallet-relevant data.

pub fn orchard_anchor_at( &mut self, height: BlockHeight, ) -> Result<Option<Anchor>, ShardTreeError<<DbT as WalletCommitmentTrees>::Error>>

Available on crate feature orchard only.

The root of the wallet’s own Orchard note commitment tree at the checkpoint height, as an anchor: the value a transaction proved against that height would have installed.

None when the tree holds no checkpoint there; the tree’s own error when it holds one but cannot complete a root over the shard data it retains.

impl<Cache, DbT, ParamsT, AccountIdT, ErrT> TestState<Cache, DbT, ParamsT>

where ParamsT: Parameters + Send + 'static, AccountIdT: Debug + Eq + Hash, ErrT: Debug, DbT: InputSource<AccountId = AccountIdT, Error = ErrT> + WalletTest + WalletRead<AccountId = AccountIdT, Error = ErrT> + WalletWrite + WalletCommitmentTrees, <DbT as WalletRead>::AccountId: ConditionallySelectable + Default + Send + 'static,

pub fn create_standard_transaction( &mut self, from_account: &TestAccount<DbT::Account>, to: ZcashAddress, value: Zatoshis, ) -> Result<NonEmpty<TxId>, TransferErrT<DbT, GreedyInputSelector<DbT>, MultiOutputChangeStrategy<DbT>>>

pub fn spend<InputsT, ChangeT>( &mut self, input_selector: &InputsT, change_strategy: &ChangeT, usk: &UnifiedSpendingKey, request: TransactionRequest, ovk_policy: OvkPolicy, confirmations_policy: ConfirmationsPolicy, ) -> Result<NonEmpty<TxId>, TransferErrT<DbT, InputsT, ChangeT>>

where InputsT: InputSelector<InputSource = DbT>, ChangeT: ChangeStrategy<MetaSource = DbT>,

Prepares and executes the given zip321::TransactionRequest in a single step.

pub fn propose_transfer<InputsT, ChangeT>( &mut self, spend_from_account: <DbT as InputSource>::AccountId, input_selector: &InputsT, change_strategy: &ChangeT, request: TransactionRequest, confirmations_policy: ConfirmationsPolicy, ) -> Result<Proposal<ChangeT::FeeRule, <DbT as InputSource>::NoteRef>, ProposeTransferErrT<DbT, Infallible, InputsT, ChangeT>>

where InputsT: InputSelector<InputSource = DbT>, ChangeT: ChangeStrategy<MetaSource = DbT>,

Invokes propose_transfer with the given arguments.

pub fn propose_transfer_with_policy<InputsT, ChangeT>( &mut self, spend_from_account: <DbT as InputSource>::AccountId, input_selector: &InputsT, change_strategy: &ChangeT, request: TransactionRequest, confirmations_policy: ConfirmationsPolicy, spend_policy: &SpendPolicy, ) -> Result<Proposal<ChangeT::FeeRule, <DbT as InputSource>::NoteRef>, ProposeTransferErrT<DbT, Infallible, InputsT, ChangeT>>

where InputsT: InputSelector<InputSource = DbT>, ChangeT: ChangeStrategy<MetaSource = DbT>,

Invokes propose_transfer with the given arguments and an explicit SpendPolicy.

Unlike Self::propose_transfer, which always uses the default spend policy (every shielded pool, no transparent), this allows tests to opt in to spending the account’s transparent UTXOs or to restrict the shielded pools notes may be drawn from.

pub fn propose_send_max_transfer<FeeRuleT>( &mut self, spend_from_account: <DbT as InputSource>::AccountId, fee_rule: &FeeRuleT, to: ZcashAddress, memo: Option<MemoBytes>, mode: MaxSpendMode, confirmations_policy: ConfirmationsPolicy, ) -> Result<Proposal<FeeRuleT, <DbT as InputSource>::NoteRef>, ProposeSendMaxErrT<DbT, Infallible, FeeRuleT>>

where FeeRuleT: FeeRule + Clone,

Invokes propose_transfer with the given arguments.

pub fn propose_standard_transfer<CommitmentTreeErrT>( &mut self, spend_from_account: <DbT as InputSource>::AccountId, fee_rule: StandardFeeRule, confirmations_policy: ConfirmationsPolicy, to: &Address, amount: Zatoshis, memo: Option<MemoBytes>, change_memo: Option<MemoBytes>, fallback_change_pool: ShieldedPool, ) -> Result<Proposal<StandardFeeRule, <DbT as InputSource>::NoteRef>, ProposeTransferErrT<DbT, CommitmentTreeErrT, GreedyInputSelector<DbT>, SingleOutputChangeStrategy<DbT>>>

Invokes propose_standard_transfer_to_address with the given arguments.

pub fn propose_shielding<InputsT, ChangeT>( &mut self, input_selector: &InputsT, change_strategy: &ChangeT, shielding_threshold: Zatoshis, from_addrs: &[TransparentAddress], to_account: <InputsT::InputSource as InputSource>::AccountId, confirmations_policy: ConfirmationsPolicy, output_filter: CoinbaseFilter, ) -> Result<Proposal<ChangeT::FeeRule, Infallible>, ProposeShieldingErrT<DbT, Infallible, InputsT, ChangeT>>

where InputsT: ShieldingSelector<InputSource = DbT>, ChangeT: ChangeStrategy<MetaSource = DbT>,

Available on crate feature transparent-inputs only.

Invokes propose_shielding with the given arguments.

pub fn propose_shielding_coinbase<InputsT, FeeRuleT>( &mut self, input_selector: &InputsT, fee_rule: &FeeRuleT, shielding_threshold: Zatoshis, from_addrs: &[TransparentAddress], to_address: ZcashAddress, memo: Option<MemoBytes>, limit: Option<usize>, ) -> Result<Proposal<FeeRuleT, Infallible>, ProposeShieldingCoinbaseErrT<DbT, Infallible, InputsT, FeeRuleT>>

where InputsT: ShieldingSelector<InputSource = DbT>, FeeRuleT: FeeRule + Clone,

Available on crate feature transparent-inputs only.

Invokes propose_shielding_coinbase with the given arguments.

pub fn create_proposed_transactions<InputsErrT, FeeRuleT, ChangeErrT, N>( &mut self, usk: &UnifiedSpendingKey, ovk_policy: OvkPolicy, proposal: &Proposal<FeeRuleT, N>, ) -> Result<NonEmpty<TxId>, CreateErrT<DbT, InputsErrT, FeeRuleT, ChangeErrT, N>>

where FeeRuleT: FeeRule,

Invokes create_proposed_transactions with the given arguments.

pub fn create_pczt_from_proposal<InputsErrT, FeeRuleT, ChangeErrT>( &mut self, spend_from_account: <DbT as InputSource>::AccountId, ovk_policy: OvkPolicy, proposal: &Proposal<FeeRuleT, <DbT as InputSource>::NoteRef>, expiry_height: Option<BlockHeight>, ) -> Result<Pczt, CreateErrT<DbT, InputsErrT, FeeRuleT, ChangeErrT, DbT::NoteRef>>

where <DbT as WalletRead>::AccountId: Serialize, FeeRuleT: FeeRule,

Available on crate feature pczt only.

Invokes create_pczt_from_proposal with the given arguments.

pub fn extract_and_store_transaction_from_pczt( &mut self, pczt: Pczt, ) -> Result<TxId, ExtractErrT<DbT, DbT::NoteRef>>

where <DbT as WalletRead>::AccountId: DeserializeOwned,

Available on crate feature pczt only.

Invokes extract_and_store_transaction_from_pczt with the given arguments.

pub fn shield_transparent_funds<InputsT, ChangeT>( &mut self, input_selector: &InputsT, change_strategy: &ChangeT, shielding_threshold: Zatoshis, usk: &UnifiedSpendingKey, from_addrs: &[TransparentAddress], to_account: <DbT as InputSource>::AccountId, confirmations_policy: ConfirmationsPolicy, ) -> Result<NonEmpty<TxId>, ShieldErrT<DbT, InputsT, ChangeT>>

where InputsT: ShieldingSelector<InputSource = DbT>, ChangeT: ChangeStrategy<MetaSource = DbT>,

Available on crate feature transparent-inputs only.

Invokes shield_transparent_funds with the given arguments.

pub fn get_total_balance(&self, account: AccountIdT) -> Zatoshis

Returns the total balance in the given account at this point in the test.

pub fn get_locked_balance(&self, account: AccountIdT) -> Zatoshis

Returns the locked balance in the given account at this point in the test.

pub fn get_spendable_balance( &self, account: AccountIdT, confirmations_policy: ConfirmationsPolicy, ) -> Zatoshis

Returns the balance in the given account that is spendable with the given number of confirmations at this point in the test.

pub fn get_pending_shielded_balance( &self, account: AccountIdT, confirmations_policy: ConfirmationsPolicy, ) -> Zatoshis

Returns the balance in the given account that is detected but not yet spendable with the given number of confirmations at this point in the test.

pub fn get_pending_change( &self, account: AccountIdT, confirmations_policy: ConfirmationsPolicy, ) -> Zatoshis

Returns the amount of change in the given account that is not yet spendable with the given number of confirmations at this point in the test.

pub fn get_wallet_summary( &self, confirmations_policy: ConfirmationsPolicy, ) -> Option<WalletSummary<AccountIdT>>

Returns a summary of the wallet at this point in the test.

impl<Cache, DbT, ParamsT, AccountIdT, ErrT> TestState<Cache, DbT, ParamsT>

where ParamsT: Parameters + Send + 'static, AccountIdT: Eq + Hash, ErrT: Debug, DbT: InputSource<AccountId = AccountIdT, Error = ErrT> + WalletTest + WalletRead<AccountId = AccountIdT, Error = ErrT> + WalletWrite + WalletCommitmentTrees, <DbT as WalletRead>::AccountId: ConditionallySelectable + Default + Send + 'static,

pub fn get_tx_from_history( &self, txid: TxId, ) -> Result<Option<TransactionSummary<AccountIdT>>, ErrT>

Returns a transaction from the history.

impl<Cache, DbT: WalletRead + Reset> TestState<Cache, DbT, LocalNetwork>

pub fn reset(&mut self) -> DbT::Handle

Resets the wallet using a new wallet database but with the same cache of blocks, and returns the old wallet database file.

This does not recreate accounts, nor does it rescan the cached blocks. The resulting wallet has no test account. Before using any generate_* method on the reset state, call reset_latest_cached_block().

Trait Implementations

impl<Cache, DataStore: WalletTest, Network> Drop for TestState<Cache, DataStore, Network>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.