Icon LinkWallet Access

The kinds of operations we can perform with a Wallet instance depend on whether or not we have access to the wallet's private key.

In order to differentiate between Wallet instances that know their private key and those that do not, we use the WalletUnlocked and WalletLocked types respectively.

Icon LinkWallet States

The WalletUnlocked type represents a wallet whose private key is known and stored internally in memory. A wallet must be of type WalletUnlocked in order to perform operations that involve signing messages or transactions .

The WalletLocked type represents a wallet whose private key is not known or stored in memory. Instead, WalletLocked only knows its public address. A WalletLocked cannot be used to sign transactions, however it may still perform a whole suite of useful operations including listing transactions, assets, querying balances, and so on.

Note that the WalletUnlocked type implements most methods available on the WalletLocked type. In other words, WalletUnlocked can be thought of as a thin wrapper around WalletLocked that provides greater access via its private key.

Icon LinkBasic Example

	import { Wallet, WalletLocked, WalletUnlocked } from 'fuels';
 
	// use the `generate` helper to make an Unlocked Wallet
	const myWallet: WalletUnlocked = Wallet.generate({
provider,
	});
 
	// or use an Address to create a wallet
	const someWallet: WalletLocked = Wallet.fromAddress(myWallet.address, provider);

Icon LinkTransitioning States

A WalletLocked instance can be unlocked by providing the private key:

	const lockedWallet: WalletLocked = Wallet.fromAddress(myWallet.address, provider);
	// unlock an existing wallet
	let unlockedWallet: WalletUnlocked = lockedWallet.unlock(PRIVATE_KEY);
	// or directly from a private key
	unlockedWallet = Wallet.fromPrivateKey(PRIVATE_KEY, provider);

A WalletUnlocked instance can be locked using the lock method:

	const newlyLockedWallet = unlockedWallet.lock();

Most wallet constructors that create or generate a new wallet are provided on the WalletUnlocked type. Consider locking the wallet after the new private key has been handled in order to reduce the scope in which the wallet's private key is stored in memory.

Icon LinkDesign Guidelines

When designing APIs that accept a wallet as an input, we should think carefully about the kind of access that we require. API developers should aim to minimise their usage of WalletUnlocked in order to ensure private keys are stored in memory no longer than necessary to reduce the surface area for attacks and vulnerabilities in downstream libraries and applications.