Local Wallet

Allow users to connect to your app by generating a Local Wallet directly in your application.

A local wallet is a low-level wallet that allows you to create wallets within your application or project. It is a non-custodial solution that simplifies the onboarding process and improves the user experience for web3 apps in two ways:

1. It enables non-web3 native users to get started easily without having to create a wallet.
2. It hides transaction confirmations from users.

After generating wallets for your users, your can offer multiple persistance and backup options.

Usage

import { LocalWallet } from "@thirdweb-dev/wallets";

const wallet = new LocalWallet();

// generate a random wallet
await wallet.generate();
// connect the wallet to the application
await wallet.connect();

// at any point, you can save the wallet to persistent storage
await wallet.save(config);
// and load it back up
await wallet.load(config);

// you can also export the wallet out of the application
const exportedWallet = await wallet.export(config);
// and import it back in
await wallet.import(exportedWallet, config);

Configuration

Optionally, provide a configuration object when instantiating the LocalWallet class.

chain (optional)

The active chain to connect to.

Must be a Chain object, from the @thirdweb-dev/chains package. Defaults to Ethereum.

import { LocalWallet } from "@thirdweb-dev/wallets";
import { Goerli } from "@thirdweb-dev/chains";

const walletWithOptions = new LocalWallet(
  {
    chain: Goerli,
  },
);

chains (optional)

Provide an array of chains you want to support.

Must be an array of Chain objects, from the @thirdweb-dev/chains package.

Defaults to our default chains.

import { LocalWallet } from "@thirdweb-dev/wallets";
import { BaseGoerli, Goerli } from "@thirdweb-dev/chains";

const walletWithOptions = new LocalWallet(
  {
    chains: [BaseGoerli, Goerli],
  },
);

storage (optional)

This is the default storage for storing the private key, mnemonic or encrypted JSON. This can be implemented in any way you want, as long as it conforms to the AsyncStorage interface:

If omitted, defaults to browser storage.

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

import { LocalWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new LocalWallet(
  {
    storage: {
      getItem: (key) => {
        // Implement your own storage logic here
      },
      removeItem: (key) => {
        // Implement your own storage logic here
      },
      setItem: (key, value) => {
        // Implement your own storage logic here
      },
    },
  },
);

walletStorage (optional)

This storage is only used for state persistance, allowing for auto connect.

Must be an object conforming to the AsyncStorage interface:

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

import { LocalWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new LocalWallet(
  {
    walletStorage: {
      getItem: (key) => {
        // Implement your own storage logic here
      },
      removeItem: (key) => {
        // Implement your own storage logic here
      },
      setItem: (key, value) => {
        // Implement your own storage logic here
      },
    },
  },
);

walletId (optional)

An ID for the wallet used to store the wallet in the walletStorage.

import { LocalWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new LocalWallet(
  {
    walletId: "wallet-id",
  },
);

Methods

Inherhits all the public methods from the AbstractClientWallet class.

Also provides wallet specific public methods:

generate

Creates a new random wallet.

const address = await wallet.generate();

Configuration

Return Value

Returns a Promise which resolves to a string containing the wallet address.

Promise<string>;

save

Save the wallet data to storage

wallet.save({
  strategy: "encryptedJson",
  password: "password",
});

Configuration

options

Must be a SaveOptions object:

type SaveOptions =
  | {
      strategy: "encryptedJson",
      password: string,
      storage?: AsyncStorage,
    }
  | {
      strategy: "privateKey",
      encryption?: EncryptOptions,
      storage?: AsyncStorage,
    }
  | {
      strategy: "mnemonic",
      encryption: EncryptOptions,
      storage?: AsyncStorage,
    };

Example:

wallet.save({
  strategy: "encryptedJson",
  password: "your-password",
});

Return Value

Returns a Promise which resolves to a string containing the wallet address.

Promise<string>;

getSavedData

Get the saved wallet data from storage.

const wallet = wallet.getSaved();

Configuration

storage

Optional AsyncStorage object to get the data from instead of the default storage.

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

wallet.getSaved({
  getItem: (key) => {
    // Implement your own storage logic here
  },
  removeItem: (key) => {
    // Implement your own storage logic here
  },
  setItem: (key, value) => {
    // Implement your own storage logic here
  },
});

Return Value

Returns a Promise which resolves to a WalletData object containing the wallet data.

Promise<WalletData | null>;

isSaved

Get an array of the events for which the emitter has registered listeners.

const isSaved = wallet.isSaved();

Configuration

Return Value

Returns a Promise which resolves to a boolean - true if wallet data is saved in storage, false otherwise.

Promise<boolean>;

deleteSaved

Delete the saved wallet from storage. This action is irreversible, use with caution.

await wallet.deleteSaved();

load

Initialize the wallet from saved data on storage

await wallet.load({
  strategy: "encryptedJson",
  password: "your-password",
});

Configuration

options

Must be a LoadOptions object:

type LoadOptions =
  | {
      strategy: "encryptedJson";
      password: string;
      storage?: AsyncStorage;
    }
  | {
      strategy: "privateKey";
      storage?: AsyncStorage;
      encryption: DecryptOptions;
    }
  | {
      strategy: "mnemonic";
      storage?: AsyncStorage;
      encryption: DecryptOptions;
    };

Example:

wallet.load({
  strategy: "encryptedJson",
  password: "your-password",
});

Return Value

Returns a Promise which resolves to a string containing the wallet address.

Promise<string>;

loadOrCreate

Load the saved wallet data from storage, if it exists, or generate a new one and save it.

password = "your-password";
wallet.loadOrCreate({
  strategy: "encryptedJson",
  password: password,
});

Configuration

options

Must be a LoadOptions object:

type LoadOptions =
  | {
      strategy: "encryptedJson";
      password: string;
      storage?: AsyncStorage;
    }
  | {
      strategy: "privateKey";
      storage?: AsyncStorage;
      encryption: DecryptOptions;
    }
  | {
      strategy: "mnemonic";
      storage?: AsyncStorage;
      encryption: DecryptOptions;
    };

Example:

wallet.loadOrCreate({
  strategy: "encryptedJson",
  password: "password",
});

export

Encrypts the wallet with given password and returns the encrypted wallet.

await wallet.export({
  strategy: "encryptedJson",
  password: "password",
});

Configuration

options

Must be a ExportOptions object:

type ExportOptions =
  | {
      strategy: "encryptedJson";
      password: string;
    }
  | {
      strategy: "privateKey";
      encryption: EncryptOptions;
    }
  | {
      strategy: "mnemonic";
      encryption: EncryptOptions;
    };

Example:

wallet.export({
  strategy: "encryptedJson",
  password: "password",
});

Return Value

Returns a Promise which resolves to a string containing the encrypted wallet.

Promise<string>;

import

Create a local wallet from an "encryptedJson", "privateKey" or "mnemonic"

const address = await wallet.import({
  encryptedJson: "mnemonic",
  encryption: false,
});

Configuration

options

Must be a ImportOptions object:

type ImportOptions =
  | {
      privateKey: string;
      encryption: DecryptOptions;
    }
  | {
      mnemonic: string;
      encryption: DecryptOptions;
    }
  | {
      encryptedJson: string;
      password: string;
    };

Example:

wallet.import({
  strategy: "encryptedJson",
  password: "password",
});

Return Value

Returns a Promise which resolves to a string containing the wallet address.

Promise<string>;