Struct fuels_signers::wallet::WalletUnlocked

pub struct WalletUnlocked { /* private fields */ }

A WalletUnlocked is equivalent to a Wallet whose private key is known and stored alongside in-memory. Knowing the private key allows a WalletUlocked to sign operations, send transactions, and more.

Examples

Signing and Verifying a message

The wallet can be used to produce ECDSA Signature objects, which can be then verified.

use fuel_crypto::Message;
use fuels::prelude::*;

async fn foo() -> Result<(), Error> {
  // Setup local test node
  let (provider, _) = setup_test_provider(vec![], vec![], None, None).await;

  // Create a new local wallet with the newly generated key
  let wallet = WalletUnlocked::new_random(Some(provider));

  let message = "my message";
  let signature = wallet.sign_message(message.as_bytes()).await?;

  // Lock the wallet when we're done, dropping the private key from memory.
  let wallet = wallet.lock();

  // Recover address that signed the message
  let message = Message::new(message);
  let recovered_address = signature.recover(&message).expect("Failed to recover address");

  assert_eq!(wallet.address().hash(), recovered_address.hash());

  // Verify signature
  signature.verify(&recovered_address, &message).unwrap();
  Ok(())
}

Implementations

impl WalletUnlocked

pub fn lock(self) -> Wallet

Lock the wallet by dropping the private key from memory.

pub fn set_provider(&mut self, provider: Provider)

pub fn new_random(provider: Option<Provider>) -> Self

Creates a new wallet with a random private key.

pub fn new_from_private_key(
    private_key: SecretKey,
    provider: Option<Provider>
) -> Self

Creates a new wallet from the given private key.

pub fn new_from_mnemonic_phrase(
    phrase: &str,
    provider: Option<Provider>
) -> Result<Self, WalletError>

Creates a new wallet from a mnemonic phrase. The default derivation path is used.

pub fn new_from_mnemonic_phrase_with_path(
    phrase: &str,
    provider: Option<Provider>,
    path: &str
) -> Result<Self, WalletError>

Creates a new wallet from a mnemonic phrase. It takes a path to a BIP32 derivation path.

pub fn new_from_keystore<P, R, S>(
    dir: P,
    rng: &mut R,
    password: S,
    provider: Option<Provider>
) -> Result<(Self, String), WalletError>where
    P: AsRef<Path>,
    R: Rng + CryptoRng + CryptoRng,
    S: AsRef<[u8]>,

Creates a new wallet and stores its encrypted version in the given path.

pub fn encrypt<P, S>(&self, dir: P, password: S) -> Result<String, WalletError>where
    P: AsRef<Path>,
    S: AsRef<[u8]>,

Encrypts the wallet’s private key with the given password and saves it to the given path.

pub fn load_keystore<P, S>(
    keypath: P,
    password: S,
    provider: Option<Provider>
) -> Result<Self, WalletError>where
    P: AsRef<Path>,
    S: AsRef<[u8]>,

Recreates a wallet from an encrypted JSON wallet given the provided path and password.

pub async fn add_fee_coins<Tx: Chargeable + Inputs + Outputs>(
    &self,
    tx: &mut Tx,
    previous_base_amount: u64,
    witness_index: u8
) -> Result<(), Error>

Add base asset inputs to the transaction to cover the estimated fee. The original base asset amount cannot be calculated reliably from the existing transaction inputs because the selected resources may exceed the required amount to avoid dust. Therefore we require it as an argument.

Requires contract inputs to be at the start of the transactions inputs vec so that their indexes are retained

pub async fn transfer(
    &self,
    to: &Bech32Address,
    amount: u64,
    asset_id: AssetId,
    tx_parameters: TxParameters
) -> Result<(String, Vec<Receipt>), Error>

Transfer funds from this wallet to another Address. Fails if amount for asset ID is larger than address’s spendable coins. Returns the transaction ID that was sent and the list of receipts.

Examples

use fuels::prelude::*;
use fuels::test_helpers::setup_single_asset_coins;
use fuels::tx::{Bytes32, AssetId, Input, Output, UtxoId};
use std::str::FromStr;
#[cfg(feature = "fuel-core-lib")]
use fuels_test_helpers::Config;

async fn foo() -> Result<(), Box<dyn std::error::Error>> {
 // Create the actual wallets/signers
 let mut wallet_1 = WalletUnlocked::new_random(None);
 let mut wallet_2 = WalletUnlocked::new_random(None).lock();

  // Setup a coin for each wallet
  let mut coins_1 = setup_single_asset_coins(wallet_1.address(),BASE_ASSET_ID, 1, 1);
  let coins_2 = setup_single_asset_coins(wallet_2.address(),BASE_ASSET_ID, 1, 1);
  coins_1.extend(coins_2);

  // Setup a provider and node with both set of coins
  let (provider, _) = setup_test_provider(coins_1, vec![], None, None).await;

  // Set provider for wallets
  wallet_1.set_provider(provider.clone());
  wallet_2.set_provider(provider);

  // Transfer 1 from wallet 1 to wallet 2
  let _receipts = wallet_1
       .transfer(&wallet_2.address(), 1, Default::default(), TxParameters::default())
       .await
       .unwrap();

  let wallet_2_final_coins = wallet_2.get_coins(BASE_ASSET_ID).await.unwrap();

  // Check that wallet two now has two coins
  assert_eq!(wallet_2_final_coins.len(), 2);
  Ok(())
}

pub async fn withdraw_to_base_layer(
    &self,
    to: &Bech32Address,
    amount: u64,
    tx_parameters: TxParameters
) -> Result<(String, String, Vec<Receipt>), Error>

Withdraws an amount of the base asset to an address on the base chain. Returns the transaction ID, message ID and the list of receipts.

pub async fn spend_predicate(
    &self,
    predicate_address: &Bech32Address,
    code: Vec<u8>,
    amount: u64,
    asset_id: AssetId,
    to: &Bech32Address,
    data: Option<Vec<u8>>,
    tx_parameters: TxParameters
) -> Result<Vec<Receipt>, Error>

pub async fn receive_from_predicate(
    &self,
    predicate_address: &Bech32Address,
    predicate_code: Vec<u8>,
    amount: u64,
    asset_id: AssetId,
    predicate_data: Option<Vec<u8>>,
    tx_parameters: TxParameters
) -> Result<Vec<Receipt>, Error>

pub async fn force_transfer_to_contract(
    &self,
    to: &Bech32ContractId,
    balance: u64,
    asset_id: AssetId,
    tx_parameters: TxParameters
) -> Result<(String, Vec<Receipt>), Error>

Unconditionally transfers balance of type asset_id to the contract at to. Fails if balance for asset_id is larger than this wallet’s spendable balance. Returns the corresponding transaction ID and the list of receipts.

CAUTION !!!

This will transfer coins to a contract, possibly leading to the PERMANENT LOSS OF COINS if not used with care.

Methods from Deref<Target = Wallet>

pub fn get_provider(&self) -> Result<&Provider, WalletError>

pub fn address(&self) -> &Bech32Address

pub async fn get_transactions(
    &self,
    request: PaginationRequest<String>
) -> Result<PaginatedResult<TransactionResponse, String>, Error>

pub async fn get_asset_inputs_for_amount(
    &self,
    asset_id: AssetId,
    amount: u64,
    witness_index: u8
) -> Result<Vec<Input>, Error>

Returns a proper vector of Input::Coins for the given asset ID, amount, and witness index. The witness_index is the position of the witness (signature) in the transaction’s list of witnesses. Meaning that, in the validation process, the node will use the witness at this index to validate the coins returned by this method.

pub fn get_asset_outputs_for_amount(
    &self,
    to: &Bech32Address,
    asset_id: AssetId,
    amount: u64
) -> Vec<Output>

Returns a vector containing the output coin and change output given an asset and amount

pub async fn get_coins(&self, asset_id: AssetId) -> Result<Vec<Coin>, Error>

Gets all coins of asset asset_id owned by the wallet, even spent ones (this is useful for some particular cases, but in general, you should use get_spendable_coins). This returns actual coins (UTXOs).

pub async fn get_spendable_resources(
    &self,
    asset_id: AssetId,
    amount: u64
) -> Result<Vec<Resource>, Error>

Get some spendable resources (coins and messages) of asset asset_id owned by the wallet that add up at least to amount amount. The returned coins (UTXOs) are actual coins that can be spent. The number of UXTOs is optimized to prevent dust accumulation.

pub async fn get_asset_balance(&self, asset_id: &AssetId) -> Result<u64, Error>

Get the balance of all spendable coins asset_id for address address. This is different from getting coins because we are just returning a number (the sum of UTXOs amount) instead of the UTXOs.

pub async fn get_balances(&self) -> Result<HashMap<String, u64>, Error>

Get all the spendable balances of all assets for the wallet. This is different from getting the coins because we are only returning the sum of UTXOs coins amount and not the UTXOs coins themselves.

pub async fn get_messages(&self) -> Result<Vec<InputMessage>, Error>

Trait Implementations

impl Clone for WalletUnlocked

fn clone(&self) -> WalletUnlocked

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WalletUnlocked

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

Formats the value using the given formatter.

impl Deref for WalletUnlocked

type Target = Wallet

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Signer for WalletUnlocked

type Error = WalletError

fn sign_message<'life0, 'async_trait, S>(
    &'life0 self,
    message: S
) -> Pin<Box<dyn Future<Output = Result<Signature, Self::Error>> + Send + 'async_trait>>where
    S: 'async_trait + Send + Sync + AsRef<[u8]>,
    Self: 'async_trait,
    'life0: 'async_trait,

Signs the hash of the provided message

fn sign_transaction<'life0, 'life1, 'async_trait, Tx>(
    &'life0 self,
    tx: &'life1 mut Tx
) -> Pin<Box<dyn Future<Output = Result<Signature, Self::Error>> + Send + 'async_trait>>where
    Tx: 'async_trait + Cacheable + UniqueIdentifier + Witnesses + Send,
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Signs the transaction

fn address(&self) -> &Bech32Address

Returns the signer’s Fuel Address