SafeAuthPack
SafeAuth is a pluggable authentication infrastructure for web3 wallets and applications. It simplifies onboarding for mainstream and crypto native users, offering experiences tailored to their preferences. It supports all social logins, web and mobile native platforms, wallets, and other key management methods, creating a cryptographic key provider specific to the user and application.
The SafeAuthPack
enables using the Web3Auth infrastructure (opens in a new tab) with added Safe capabilities, such as retrieving the related Safe addresses for a given externally-owned account created using SafeAuth services.
The pack helps onboard web2 users and provides an Ethereum signer address that can be used across any dapp using the different Ethereum chains.
Install dependencies
To use the SafeAuthPack
, you must install the @safe-global/auth-kit
package and the corresponding Web3Auth one.
_10yarn add @safe-global/auth-kit @web3auth/safeauth-embed
Reference
The SafeAuthPack
class makes SafeAuth modal and Safe accounts work together. Create an instance of the pack and initialize it to start the interaction.
_10const safeAuthPack = new SafeAuthPack({_10 txServiceUrl: 'https://safe-transaction-mainnet.safe.global',_10});_10await safeAuthPack.init(safeAuthInitOptions);
new SafeAuthPack(safeAuthConfig)
Parameters
safeAuthConfig?
- TheSafeAuthPack
class instantiation accepts the following options in its configuration:
_10SafeAuthConfig {_10 txServiceUrl?: string_10}
txServiceUrl?
- The URL of the Safe Transaction Service. It's mandatory in chains where Safe doesn't provide a Transaction Service. It retrieves the Safe addresses for an EOA created using SafeAuth services.
Caveats
You should always call the init()
method afterward before interacting with the pack.
init(safeAuthInitOptions)
The init method initializes the provided Web3Auth SDK and Safe services. It creates an embedded browser wallet within an iframe, establishing communication through the internally generated EIP-1193 provider.
Parameters
safeAuthInitOptions
- The options to initialize the SDK instance.
_19safeAuthInitOptions {_19 enableLogging?: boolean_19 showWidgetButton?: boolean_19 buttonPosition?: "bottom-left" | "top-left" | "bottom-right" | "top-right"_19 buildEnv?: "production" | "development" | "testing"_19 chainConfig?: {_19 blockExplorerUrl: string_19 logo: string_19 tickerName: string_19 ticker: string_19 rpcTarget: string_19 wcTarget?: string_19 chainId: string_19 displayName: string_19 isTestnet?: boolean_19 isErc20?: boolean_19 tokenAddress?: string_19 }_19}
enableLogging
- Enable logging for the SDK. Defaults tofalse
.buildEnv
- The build environment.production
andtesting
usehttps://safe.web3auth.com
.development
useshttp://localhost:4050
. Defaults toproduction
.showWidgetButton
- Show the widget button. Defaults totrue
.buttonPosition
- IfshowWidgetButton
is true then this prop represent the position of the widget button. Defaults tobottom-left
.chainConfig
- The chain configuration. Defaults toethereum
if no configuration is provided.blockExplorerUrl
- Block explorer URL of the chain (e.ghttps://etherscan.io
).logo
- Logo URL of the base token of the chain (e.ghttps://eth.svg
).tickerName
- Name for ticker (e.g Ethereum).ticker
- Symbol for ticker (e.g ETH).rpcTarget
- The RPC URL to be used.wcTarget?
- The WebSocket URL to be used. Use this orrpcTarget
.chainId
- The chain ID to be used. Should be an hex with 0x prefix (e.g 0x1 for Mainnet).displayName
- The display name for the network.isTestnet?
- Whether the network is Testnet or not.isErc20?
- Whether the token is an ERC20 token or not.tokenAddress?
- The token address for the chain. Should be an hex with 0x prefix (e.g 0x6b175474e89094c44da98b954eedeac495271d0f for DAI).
Caveats
- The list of supported chains is:
- Production: Ethereum, Polygon, BSC, Avalanche, Optimism, Celo, Arbitrum, Gnosis chain.
- Test: Sepolia, Polygon Mumbai, BSC Testnet, Avalanche Testnet, Arbitrum Testnet, Optimism Testnet.
- Call always the
init()
method before interacting with the other methods in the pack. - The
init()
method creates an iframe and establishes a connection with the embedded wallet domain. To remove the iframe and disconnect the connection, use thesignOut()
method. If you want to sign out and sign in again in a single-page application (SPA) fashion, avoid usingsignOut({ reset: true })
as it will clean up the session, iframe, and connection. Instead, you will need to re-instantiate the pack.
signIn(safeAuthSignInOptions?)
signIn(safeAuthSignInOptions)
starts the authentication flow. It displays a popup that enables users to select a social authentication method (OAuth) or an email to generate the web3 wallet address. It returns the EOA and the associated Safe addresses.
Parameters
_10SafeAuthSignInOptions = {_10 loginProvider?: "google" | "facebook" | "reddit" | "discord" | "twitch" | "apple" | "line" | "github" | "kakao" | "linkedin" | "twitter" | "weibo" | "wechat" | "email_passwordless"_10 login_hint?: string_10}
-
loginProvider
- If specified, instead of showing the popup to choose the OAuth or email, a direct attempt to login with the specified provider will be made. -
login_hint
- Used to provide default mail given aloginProvider
:
_10safeAuthPack.signIn({_10 loginProvider: 'google',_10 login_hint: 'my-mail@safe.global',_10});
Returns
An object with the derived externally-owned account address and the associated Safe addresses.
_10AuthKitSignInData {_10 eoa: string_10 safes?: string[]_10}
Caveats
- To get the Safe addresses, instantiate the
authKit
with thetxServiceUrl
property in the config object. Otherwise, only the EOA will be returned. - ⚠️ This method currently returns the Safe addresses where the EOA is an owner. It doesn't create a Safe. We are investigating ways to enhance the Auth Kit and the associated flows.
signOut(safeAuthSignOutOptions?)
Call this method to sign out the user and clean the session.
_10SafeAuthSignOutOptions {_10 reset: boolean;_10}
Parameters
reset
- If true, the user will be logged out from the provider, and the widget will be destroyed. Don't use this parameter if you want to log out and log in again without refreshing the browser or re-initializing theSafeAuthPack
instance.
getUserInfo()
Using getUserInfo()
, you will receive the user information derived from the pack you are using. It varies depending on the provider.
Returns
The UserInfo
object's properties vary depending on the provider.
getProvider()
By using getProvider()
, you will receive a standard web3 provider compatible with the EIP-1193 standard.
Returns
A EIP-1193 compatible provider.
Caveats
- You can wrap the provider using your favorite library (ethers, web3, etc.).
destroy()
This method removes the iframe. It's useful when you need to re-instantiate the pack, for example, when changing the connected chain.
subscribe(event, handler)
Allow to subscribe to authentication state changes.
Parameters
event
- The event you want to subscribe to. Currently, you can subscribe toaccountsChanged
orchainChanged
.handler
- When the event is triggered, the function will be called.
unsubscribe(event, handler)
Allow to unsubscribe to authentication state changes.
Caveats
The accountsChanged
event helps detect whether the user has previously signed in. This allows you to reauthenticate when the browser is refreshed by calling the signIn
method, preventing the user from clicking the sign-in button again.
Parameters
event
- The event you want to unsubscribe to.handler
- The function will be called when the event is triggered.
Usage
Calling init()
when your page loads or component renders is all it takes to use the Auth Kit with the SafeAuthPack
. To start the authentication process, call signIn()
afterward. This method returns the EOA and associated Safe addresses.
_15// Instantiate and initialize the pack_15const safeAuthPack = new SafeAuthPack(safeAuthConfig);_15await safeAuthPack.init(safeAuthInitOptions);_15_15const { eoa, safes } = await safeAuthPack.signIn();_15const userInfo = await safeAuthPack.getUserInfo();_15const web3Provider = safeAuthPack.getProvider();_15_15// Subscribe to events_15const handler = (event) => {};_15safeAuthPack.subscribe(packEvent, handler);_15safeAuthPack.unsubscribe(packEvent, handler);_15_15// Sign out_15await safeAuthPack.signOut();