Skip to main content

Safe (Gnosis)

Prompt users to connect to your app with their Safe wallet.

To connect to a safe wallet, a personal wallet must first be connected.

Usage​

import { CoinbaseWallet, SafeWallet } from "@thirdweb-dev/wallets";
import { Ethereum } from "@thirdweb-dev/chains";

// First, connect the personal wallet
const personalWallet = new CoinbaseWallet();
await personalWallet.connect();

// Then, connect the Safe wallet
const wallet = new SafeWallet();
await wallet.connect({
  personalWallet: personalWallet,
  chain: Ethereum,
  safeAddress: "{{contract_address}}",
});

Configuration​

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

chains

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 { SafeWallet } from "@thirdweb-dev/wallets";
import { Ethereum } from "@thirdweb-dev/chains";

const walletWithOptions = new SafeWallet(
  {
    chains: [Ethereum],
  },
);
dappMetadata

Information about your app that the wallet will display when your app tries to connect to it.

Must be an object containing name, url, description and logoUrl properties.

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

const walletWithOptions = new SafeWallet({
  dappMetadata: {
    name: "thirdweb powered dApp",
    url: "https://thirdweb.com",
    description: "thirdweb powered dApp",
    logoUrl: "https://thirdweb.com/favicon.ico",
  },
});
headlessMode

If true, the wallet will not open a QR Code modal, but instead, return a QR Code string.

Must be a boolean.

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

const walletWithOptions = new SafeWallet(
  {
    headlessMode: true,
  },
);
walletStorage

Some wallets need to store data in persistent storage. This is the storage that will be used for that.

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 { SafeWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new SafeWallet(
  {
    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

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

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

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

Methods​

Once instantiated, utilize the following methods to interact with the wallet.

addListener​

Add a listener for a specific event, and run a callback whenever that event is emitted.

wallet.addListener("connect", (data) => console.log(data));
Configuration

eventName​

The name of the event to listen for. Each event returns a different data object, or no data object at all.

Possible options:

change​

User changes the wallet they are connected with, or the chain they are connected to.

Data available:

{
  address: string;
  chainId: number;
}
connect​

User connects their wallet to your app.

Data available:

{
  address: string;
  chainId: number;
}
disconnect​

User disconnects their wallet from your app.

No data is available.

error​

An error occurs in the wallet.

Data available:

{
  cause: unknown;
  message: string;
  name: string;
  stack: string | undefined;
}
message​

Wallet receives some message that the consumer should be notified of. The kind of message is identified by the type field.

Data available:

{
  type: string;
  data: unknown;
}
open_wallet​

User opens the wallet app.

data is a string | undefined.

request​

Wallet receives some request that the consumer should be notified of. The kind of request is identified by the type field.

No data is available.

callback​

The function to run when the event is emitted.

autoConnect​

Attempts to connect to the wallet without asking the user’ explicitly; possible if the user has already connected to the wallet to your app before.

const address = await wallet.autoConnect();
Configuration

Return Value​

Returns a string containing the wallet address, or undefined if the connection failed.

string | undefined;

connect​

Prompt the user to connect their wallet to your app.

Note: A personal wallet must be connected before connecting to a Safe wallet.

import { CoinbaseWallet, SafeWallet } from "@thirdweb-dev/wallets";
import { Ethereum } from "@thirdweb-dev/chains";

// First, connect the personal wallet
const personalWallet = new CoinbaseWallet();
await personalWallet.connect();

// Then, connect the Safe wallet
const wallet = new SafeWallet();
await wallet.connect({
  personalWallet: personalWallet, // Wallet that can sign transactions on the Safe
  chain: Ethereum, // Chain that the Safe is on
  safeAddress: "{{contract_address}}", // Smart contract address of the Safe
});
Configuration

personalWallet​

The instance of a personal wallet that can sign transactions on the Safe.

Must be an AbstractBrowserWallet such as CoinbaseWallet or MetamaskWallet.

chain​

The chain that the Safe smart contract is deployed to.

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

safeAddress​

Smart contract address of the Safe wallet.

Must be a string.

Return Value​

Returns a string containing the wallet address, or undefined if the connection failed.

string | undefined;

disconnect​

Disconnect the currently connected wallet from your app.

await wallet.disconnect();

emit​

Emit an event, with some optional data.

wallet.emit("connect", {});
Configuration

eventName​

The name of the event to emit.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

data​

Optional data to send with the event. Must be an object with information relevant to the event.

See addListener configuration for more information on the different events.

eventNames​

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

const eventNames = wallet.eventNames();
Configuration

Return Value​

Returns an array of strings containing the event names.

(`change` | `connect` | `disconnect` | `error` | `message` | `open_wallet` | `request`)[];

getAddress​

Get the address of the currently connected wallet.

const address = await wallet.getAddress();
Configuration

Return Value​

Returns a string containing the wallet address, or undefined if the connection failed.

string | undefined;

getChainId​

Get the chain ID of the network the wallet is currently connected to.

const chainId = await wallet.getChainId();
Configuration

Return Value​

Returns a number containing the chain ID, or undefined if there is no connected wallet.

number | undefined;

getMeta​

Get metadata about the wallet, such as the name and iconURL.

const metadata = wallet.getMeta();
Configuration

Return Value​

{
  name: string;
  iconURL: string;
}

getPersonalWallet​

Get the connected personal wallet.

const connectedPersonalWallet = wallet.getPersonalWallet();
Configuration

Return Value​

Returns an AbstractBrowserWallet or `undefined if there is no connected wallet.

AbstractBrowserWallet | undefined;

getQrUrl​

Get a URL that can be used to generate a QR code for the wallet.

const qrUrl = await wallet.getQrUrl();
Configuration

Return Value​

Returns a string containing the URL, or null if there is no connected wallet.

string | null;

getSigner​

Get the signer for the currently connected wallet.

const signer = await wallet.getSigner();
Configuration

Return Value​

Returns a Signer.

Signer;

listenerCount​

Get the number of listeners for a given event.

const listenerCount = wallet.listenerCount("connect");
Configuration

eventName​

The name of the event to get the listener count for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

Return Value​

Returns a number containing the number of listeners for the event.

number;

listeners​

Get an array of the listeners for a given event.

const listeners = wallet.listeners("connect");
Configuration

eventName​

The name of the event to get the listeners for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

Return Value​

Returns an array of functions containing the listeners for the event.

((data: WalletData) => void)[]

removeAllListeners​

Remove all event listeners for either all events, or a specific event.

wallet.removeAllListeners();
Configuration

eventName​

Optionally, provide the name of the event to remove all listeners for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

wallet.removeAllListeners("connect");

removeListener​

Remove a specific event listener for a given event.

Provide the event name and the listener function to remove.

wallet.removeListener("connect", (data) => console.log(data));
Configuration

eventName​

The name of the event to remove the listener for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

listener​

The listener function to remove. i.e. provide the same function that was used to add the listener.

signMessage​

Sign a message with the currently connected wallet.

const signature = await wallet.signMessage("Hello world!");
Configuration

message​

The message to sign.

Must be a string.

Return Value​

Returns a string containing the signature.

string;

switchChain​

Switch the currently connected wallet to a different chain.

await wallet.switchChain(1);
Configuration

chainId​

The chain ID to switch to.

Must be a number.

verifySignature​

Verify a signature is valid.

const isValid = await wallet.verifySignature(
  "Message",
  "Signature",
  "wallet_address",
);
Configuration

message​

The message that was signed.

Must be a string.

signature​

The signature to verify.

Must be a string.

address​

The address of the wallet that signed the message.

Must be a string.

chainId​

The chain ID to check the signature on.

Optional, must be a number.