useWalletPassword

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Only available from v4.61.0 onwards.

Summary

The useWalletPassword hook provides methods to manage wallet password functionality for Dynamic WaaS embedded wallets, allowing users to update passwords, unlock wallets, and check wallet lock states.

To create a wallet with a password, use the createWalletAccount function with the password parameter.

The hook needs to be initialized within a child of DynamicContextProvider.

Functions

updatePassword

Updates the password for an embedded wallet. Can be used to set an initial password or change an existing one.

Parameters:

• params: Object containing:
  • accountAddress: string - The wallet address
  • chainName: ChainEnum - The chain the wallet is associated with
  • newPassword: string - The new password to set
  • existingPassword (optional): string - The current password (required when changing an existing password)

Returns: Promise<boolean> - true if password update was successful, false otherwise.

Example:

import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { updatePassword } = useWalletPassword();

// Set initial password
const success = await updatePassword({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  newPassword: 'mySecurePassword123',
});

// Change existing password
const changed = await updatePassword({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  newPassword: 'newSecurePassword456',
  existingPassword: 'mySecurePassword123',
});

if (success) {
  console.log('Password updated successfully');
}

unlockWallet

Unlocks a wallet using the provided password. Once unlocked, the wallet remains unlocked for the rest of the user session.

Parameters:

• params: Object containing:
  • accountAddress: string - The wallet address
  • chainName: ChainEnum - The chain the wallet is associated with
  • password: string - The password to unlock the wallet

Returns: Promise<boolean> - true if wallet was unlocked successfully, false otherwise.

Example:

import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { unlockWallet } = useWalletPassword();

const success = await unlockWallet({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  password: 'mySecurePassword123',
});

if (success) {
  console.log('Wallet unlocked successfully');
}

checkWalletLockState

Checks the current lock/recovery state of a wallet.

Parameters:

• params: Object containing:
  • accountAddress: string - The wallet address
  • chainName: ChainEnum - The chain the wallet is associated with

Returns: Promise<WalletRecoveryState | null> - The wallet’s recovery state, or null if the check failed.

Example:

import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { checkWalletLockState } = useWalletPassword();

const recoveryState = await checkWalletLockState({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
});

if (recoveryState) {
  console.log('Wallet recovery state:', recoveryState);
}

resetState

Resets the hook’s state back to its initial values, clearing any errors and loading states.

Returns: void

Example:

const { resetState } = useWalletPassword();

// Clear any previous errors or state
resetState();

Properties

state

An object containing the current state of wallet password operations.

Type: WalletPasswordState

interface WalletPasswordState {
  isLoading: boolean;
  error: string | null;
  recoveryState: WalletRecoveryState | null;
}

Example:

const { state } = useWalletPassword();

if (state.isLoading) {
  console.log('Operation in progress...');
}

if (state.error) {
  console.error('Error:', state.error);
}

if (state.recoveryState) {
  console.log('Recovery state:', state.recoveryState);
}

Usage

import { useWalletPassword } from '@dynamic-labs/sdk-react-core';
import { ChainEnum } from '@dynamic-labs/sdk-api-core';

const MyComponent = () => {
  const { 
    updatePassword,
    unlockWallet,
    checkWalletLockState,
    state,
    resetState
  } = useWalletPassword();

  const handleSetPassword = async () => {
    const success = await updatePassword({
      accountAddress: '0x123...',
      chainName: ChainEnum.Evm,
      newPassword: 'mySecurePassword',
    });

    if (success) {
      console.log('Password set successfully');
    }
  };

  const handleUnlock = async () => {
    const success = await unlockWallet({
      accountAddress: '0x123...',
      chainName: ChainEnum.Evm,
      password: 'mySecurePassword',
    });

    if (success) {
      console.log('Wallet unlocked');
    }
  };

  return (
    <div>
      <button onClick={handleSetPassword} disabled={state.isLoading}>
        Set Password
      </button>
      
      <button onClick={handleUnlock} disabled={state.isLoading}>
        Unlock Wallet
      </button>
      
      {state.isLoading && <p>Processing...</p>}
      
      {state.error && (
        <div>
          <p>Error: {state.error}</p>
          <button onClick={resetState}>Clear Error</button>
        </div>
      )}
    </div>
  );
};

Return Value

The hook returns an object with the following properties:

{
  updatePassword: (params: UpdatePasswordParams) => Promise<boolean>;
  unlockWallet: (params: UnlockWalletParams) => Promise<boolean>;
  checkWalletLockState: (params: CheckWalletLockStateParams) => Promise<WalletRecoveryState | null>;
  state: WalletPasswordState;
  resetState: () => void;
}

Types

type UpdatePasswordParams = {
  accountAddress: string;
  chainName: ChainEnum;
  newPassword: string;
  existingPassword?: string;
};

type UnlockWalletParams = {
  accountAddress: string;
  chainName: ChainEnum;
  password: string;
};

type CheckWalletLockStateParams = {
  accountAddress: string;
  chainName: ChainEnum;
};

type WalletPasswordState = {
  isLoading: boolean;
  error: string | null;
  recoveryState: WalletRecoveryState | null;
};