Only available from v4.51.2 onwards.
Summary
The useWalletBackup hook provides methods to manage wallet backup functionality for Dynamic embedded wallets, allowing users to back up their wallet key shares to Google Drive.
For more information on wallet backup, see the Google Drive backup documentation.
The hook needs to be initialized within a child of DynamicContextProvider.
Functions
initBackupProcess
Initiates the wallet backup flow by opening the Dynamic modal and displaying the backup progress view to the user.
This method uses Dynamic’s UI.
void
Errors:
- Throws
"user_not_logged_in" if the user is not authenticated
Example:
const { initBackupProcess } = useWalletBackup();
try {
initBackupProcess();
} catch (error) {
console.error('Failed to start backup:', error);
}
ensureGoogleLinked
Ensures that the user has linked their Google account. If not already linked, prompts the user to link their Google account via popup.
This method uses Dynamic’s UI.
Promise<boolean> - true if Google account is linked (or successfully linked), false if linking failed.
Example:
const { ensureGoogleLinked } = useWalletBackup();
const isLinked = await ensureGoogleLinked();
if (isLinked) {
console.log('Google account is linked');
} else {
console.error('Failed to link Google account');
}
backupWallet
Backs up a single wallet’s key shares to Google Drive.
Parameters:
walletToBackup: Object containing wallet information
address: string - The wallet addresschain: ChainEnum - The chain the wallet is associated with
Returns: Promise<boolean> - true if backup was successful, false otherwise.
Example:
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { backupWallet } = useWalletBackup();
const success = await backupWallet({
address: '0x123...',
chain: ChainEnum.Evm,
});
if (success) {
console.log('Wallet backed up successfully');
}
backupAllWallets
Backs up all wallets (or a specified list of wallets) to Google Drive.
Parameters:
wallets (optional): Array of wallet objects to back up. If not provided, backs up all wallets that need backup.
Returns: Promise<void> - Resolves when all backups complete. Automatically refreshes user data after completion.
Example:
const { backupAllWallets } = useWalletBackup();
// Back up all pending wallets
await backupAllWallets();
// Back up specific wallets
await backupAllWallets([
{ address: '0x123...', chain: ChainEnum.Evm },
{ address: '0x456...', chain: ChainEnum.Evm },
]);
startBackup
Starts the backup process with progress tracking and error handling. This function backs up wallets sequentially and updates the backupState as it progresses.
Parameters:
onComplete (optional): Callback function to execute when backup completes successfullyfromIndex (optional): Index to start backup from (useful for retrying after failure). Default is 0.
Returns: Promise<void> - Resolves when backup completes or fails.
Example:
const { startBackup, backupState } = useWalletBackup();
await startBackup(() => {
console.log('All wallets backed up!');
});
// Retry from failed index
if (backupState.hasError && backupState.failedIndex !== null) {
await startBackup(undefined, backupState.failedIndex);
}
getWalletsBackupStatus
Returns the backup status for all WaaS wallets.
Returns: WalletWithBackupStatus[] - Array of wallets with their backup status.
Example:
const { getWalletsBackupStatus } = useWalletBackup();
const wallets = getWalletsBackupStatus();
wallets.forEach(wallet => {
console.log(`${wallet.address}: ${wallet.status}`);
});
getWalletsToBackup
Returns only the wallets that still need to be backed up (status is ‘pending’).
Returns: WalletToBackup[] - Array of wallets that need backup.
Example:
const { getWalletsToBackup } = useWalletBackup();
const pendingWallets = getWalletsToBackup();
console.log(`${pendingWallets.length} wallets need backup`);
Properties
areAllWalletsBackedUp
A boolean value indicating whether all WaaS wallets have been backed up to Google Drive.
Type: boolean
Example:
const { areAllWalletsBackedUp } = useWalletBackup();
if (areAllWalletsBackedUp) {
console.log('All wallets are safely backed up');
}
isGoogleLinked
A boolean value indicating whether the user has linked their Google account.
Type: boolean
Example:
const { isGoogleLinked } = useWalletBackup();
if (!isGoogleLinked) {
console.log('User needs to link Google account for backup');
}
backupState
An object containing the current state of the backup operation, including progress and error information.
Type: WalletOperationState
Example:
const { backupState } = useWalletBackup();
console.log(`Progress: ${backupState.currentIndex}/${backupState.totalWallets}`);
if (backupState.hasError) {
console.error(`Backup failed at index ${backupState.failedIndex}`);
}
Usage
import { useWalletBackup } from '@dynamic-labs/sdk-react-core';
const MyComponent = () => {
const {
initBackupProcess,
areAllWalletsBackedUp,
isGoogleLinked,
backupState
} = useWalletBackup();
const handleBackup = () => {
initBackupProcess();
};
return (
<div>
{!areAllWalletsBackedUp && (
<div>
<p>Your wallets are not backed up</p>
{!isGoogleLinked && (
<p>You'll need to link your Google account</p>
)}
<button onClick={handleBackup}>
Back Up Wallets
</button>
</div>
)}
{backupState.isProcessing && (
<p>Backing up wallet {backupState.currentIndex} of {backupState.totalWallets}</p>
)}
{backupState.isComplete && (
<p>All wallets backed up successfully!</p>
)}
{backupState.hasError && (
<p>Backup failed. Please try again.</p>
)}
</div>
);
};
Advanced Usage
Monitor backup progress and handle errors:
import { useWalletBackup } from '@dynamic-labs/sdk-react-core';
import { useEffect } from 'react';
const BackupMonitor = () => {
const {
startBackup,
backupState,
getWalletsToBackup
} = useWalletBackup();
const handleBackupWithRetry = async () => {
const walletsToBackup = getWalletsToBackup();
if (walletsToBackup.length === 0) {
console.log('No wallets need backup');
return;
}
await startBackup(() => {
console.log('Backup completed successfully');
});
};
const handleRetry = async () => {
if (backupState.failedIndex !== null) {
await startBackup(
() => console.log('Retry successful'),
backupState.failedIndex
);
}
};
useEffect(() => {
if (backupState.hasError) {
console.error(`Backup failed at wallet ${backupState.failedIndex}`);
}
}, [backupState.hasError]);
return (
<div>
<button onClick={handleBackupWithRetry}>
Start Backup
</button>
{backupState.hasError && (
<button onClick={handleRetry}>
Retry Failed Backup
</button>
)}
{backupState.isProcessing && (
<div>
<progress
value={backupState.currentIndex}
max={backupState.totalWallets}
/>
<p>
Backing up wallet {backupState.currentIndex} of {backupState.totalWallets}
</p>
</div>
)}
</div>
);
};
Important Notes
- The user must be authenticated to use backup functionality
- Google account linking is required before backing up wallets
- Backup operations are performed sequentially, one wallet at a time
- The backup modal is part of the Dynamic UI and handles user interactions
- Failed backups can be retried from the point of failure using the
failedIndex
Learn More
Return Value
The hook returns an object with the following properties:
{
areAllWalletsBackedUp: boolean;
backupAllWallets: (wallets?: WalletToBackup[]) => Promise<void>;
backupState: WalletOperationState;
backupWallet: (walletToBackup: WalletToBackup) => Promise<boolean>;
ensureGoogleLinked: () => Promise<boolean>;
getWalletsBackupStatus: () => WalletWithBackupStatus[];
getWalletsToBackup: () => WalletToBackup[];
initBackupProcess: () => void;
isGoogleLinked: boolean;
startBackup: (onComplete?: () => void, fromIndex?: number) => Promise<void>;
}
Types
type WalletBackupStatus = 'backed-up' | 'pending';
interface WalletToBackup {
address: string;
chain: ChainEnum;
}
interface WalletWithBackupStatus extends WalletToBackup {
status: WalletBackupStatus;
}
interface WalletOperationState {
currentIndex: number;
failedIndex: number | null;
hasError: boolean;
isComplete: boolean;
isProcessing: boolean;
totalWallets: number;
}
