useDynamicWaas

Summary

A React hook that provides functionality for managing Dynamic MPC wallets. This hook enables wallet creation, management, and interaction with Dynamic’s embedded wallet system.

Return Value

{
  createWalletAccount: (
    chainNames?: ChainEnum[],
    password?: string
  ) => Promise<Array<WalletAccount | undefined>>;
  dynamicWaasIsEnabled: boolean;
  getWaasWallets: () => Array<Wallet>;
  getWalletConnector: (chainName: string) => IDynamicWaasConnector | undefined;
  importPrivateKey: (params: { chainName: string; privateKey: string }) =>
    Promise<void>;
  shouldAutoCreateDynamicWaasWallet: boolean;
  upgradeToDynamicWaas: (params: { privateKey: string, wallet: Wallet }) => Promise<void>;
}

Functions

createWalletAccount

Creates wallet accounts for enabled chains in the project settings. This function can create wallets for one or more specified chains. Optionally accepts a password (passcode) to create a passcode-protected wallet.

import { ChainEnum } from "@dynamic-labs/sdk-api-core";
const { createWalletAccount } = useDynamicWaas();

// Create wallets for all enabled chains
const wallets = await createWalletAccount();

// Create wallet for a specific chain
const evmWallet = await createWalletAccount([ChainEnum.Evm]);

// Create wallets for multiple chains
const wallets = await createWalletAccount([ChainEnum.Evm, ChainEnum.Sol]);

// Create a password-protected wallet for a specific chain
const secureEvmWallet = await createWalletAccount(
  [ChainEnum.Evm],
  'your-strong-passcode'
);

Parameters:

• chainNames?: ChainEnum[] - Optional. When omitted, creates wallets for all enabled chains.
• password?: string - Optional passcode to protect the wallet.

Returns: Promise resolving to an array of created wallet accounts. Each wallet account in the array will have the following structure:

{
  id: string;
  chainName: string;
  provider: WalletProviderEnum.EmbeddedWallet;
  accountAddress?: string;
}

Behavior:

• Creates wallet accounts for the specified chains in parallel
• After creation, it will:
  1. Find the primary wallet account (based on the chain marked as primary in settings)
  2. Refresh the user data to get the latest wallet information
  3. Update the primary wallet to the newly created wallet
  4. Close any open auth flow modals

Throws:

• NO_ENABLED_CHAINS_ERROR if no chains are enabled in the project settings
• DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR if a wallet connector is not found for an enabled chain
• Any errors from the underlying wallet creation process

Example:

try {
  // Create wallets for all enabled chains
  const wallets = await createWalletAccount();
  // Example return value:
  // [
  //   {
  //     id: "wallet-1",
  //     chainName: "EVM",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x123..."
  //   },
  //   {
  //     id: "wallet-2",
  //     chainName: "SOL",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x456..."
  //   }
  // ]

  // Create wallet for EVM chain only
  const evmWallet = await createWalletAccount([ChainEnum.Evm]);
  // Example return value:
  // [
  //   {
  //     id: "wallet-1",
  //     chainName: "EVM",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x123..."
  //   }
  // ]
} catch (error) {
  if (error.message === NO_ENABLED_CHAINS_ERROR) {
    // Handle no enabled chains error
  } else if (error.message === DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR) {
    // Handle missing wallet connector error
  } else {
    // Handle other errors
  }
}

getWalletConnector

Retrieves a configured wallet connector for a specific chain.

const { getWalletConnector } = useDynamicWaas();
const connector = getWalletConnector('EVM');

Parameters:

• chainName: string - The name of the chain to get the connector for.

Returns: A configured IDynamicWaasConnector or undefined if:

• Cookie auth is disabled and no auth token is present
• No wallet connector options are available
• The environment ID is not set

Throws:

• DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR if the wallet connector is not found.

importPrivateKey

Imports a private key for a specific chain.

const { importPrivateKey } = useDynamicWaas();
await importPrivateKey({
  chainName: 'EVM',
  privateKey: '0x123...',
});

Parameters:

• chainName: string - The name of the chain to import the private key for.
• privateKey: string - The private key to import.

Behavior:

• Imports the private key for the specified chain
• Refreshes the user data after successful import
• Returns undefined if the wallet connector is not found

getWaasWallets

Finds all Dynamic WaaS wallets associated with the user.

const { getWaasWallets } = useDynamicWaas();
const waasWallets = getWaasWallets();

Returns: Array of Dynamic WaaS wallets. Each wallet in the array will have the following structure:

{
  key: 'dynamicwaas';
  address: string;
  chain: string;
  isAuthenticated: boolean;
  // ... other wallet properties
}

Behavior:

• Filters the user’s wallets to only return those with key === 'dynamicwaas'
• Returns an empty array if no Dynamic WaaS wallets are found
• The returned wallets can be used for chain-specific operations (e.g., transactions)

Example:

const waasWallets = getWaasWallets();
// Example return value:
// [
//   {
//     key: 'dynamicwaas',
//     address: '0x123...',
//     chain: 'EVM',
//     isAuthenticated: true
//   },
//   {
//     key: 'dynamicwaas',
//     address: '0x456...',
//     chain: 'SOL',
//     isAuthenticated: true
//   }
// ]

upgradeToDynamicWaas

Upgrades the users current primary wallet (assuming it’s legacy) to a Dynamic WaaS wallet.

const { upgradeToDynamicWaas } = useDynamicWaas();
await upgradeToDynamicWaas({
  privateKey: '0x123...',
  wallet: Wallet
});

Parameters:

• privateKey: string - The private key of the legacy embedded wallet to upgrade, must be associated with the user’s current primary wallet.
• wallet: Wallet - The wallet to upgrade.

Throws:

• Primary wallet not found if the primary wallet is not found
• Wallet connector not found if the wallet connector is not found
• Upgrade failed if there are any errors from the underlying wallet upgrade process

Behavior:

• Upgrades the legacy embedded wallet associated with the private key to a Dynamic MPC wallet
• Removes access to the previous legacy embedded wallet and replaces it with a new Dynamic embedded wallet

Notes:

• This is a one-way upgrade. Once a user has upgraded to v3 and received a new v3 wallet, they will lose access to their v1 or v2 embedded wallet.
• We recommend that you prompt your user to confirm they do not have any funds in their wallet before making this switch.
• The user must be logged in, and the private key must be associated with the user’s current primary wallet.

Properties

dynamicWaasIsEnabled

Indicates whether Dynamic WaaS is enabled in the project settings.

const { dynamicWaasIsEnabled } = useDynamicWaas();
if (dynamicWaasIsEnabled) {
  // Dynamic WaaS is available
}

shouldAutoCreateDynamicWaasWallet

Indicates whether a Dynamic WaaS wallet should be automatically created.

const { shouldAutoCreateDynamicWaasWallet } = useDynamicWaas();
if (shouldAutoCreateDynamicWaasWallet) {
  // Auto-create wallet logic
}

Important Notes

1. Authentication Requirements:

   • The hook requires either cookie authentication or a valid auth token to function properly.
   • Wallet connector operations will return undefined if authentication is not available.

2. Chain Configuration:

   • Wallet creation and operations require properly configured chains in the project settings.
   • At least one chain must be enabled for wallet creation to work.

3. Version Compatibility:

   • Dynamic WaaS is only enabled when using EmbeddedWalletVersionEnum.V3.
   • The hook will not function with older wallet versions (V1 or V2).

4. Auto-Creation Behavior:

   • Auto-creation of wallets is controlled by project settings.
   • Separate settings exist for external wallet users.
   • Auto-creation will not occur if the user already has a Dynamic WaaS wallet.

5. Relay Configuration:

   • The hook uses a relay URL for wallet operations, which can be configured in project settings.
   • If not specified, it defaults to ‘relay.dynamic-preprod.xyz’.

Example Usage

import { useDynamicWaas } from '@dynamic-labs/sdk-react-core';

function WalletManager() {
  const {
    createWalletAccount,
    dynamicWaasIsEnabled,
    getWaasWallets,
    importPrivateKey,
    shouldAutoCreateDynamicWaasWallet,
  } = useDynamicWaas();

  const handleCreateWallet = async () => {
    if (dynamicWaasIsEnabled) {
      // Create wallets for all enabled chains
      const wallets = await createWalletAccount();
      console.log('Created wallets:', wallets);

      // Or create wallet for a specific chain
      const evmWallet = await createWalletAccount([ChainEnum.Evm]);
      console.log('Created EVM wallet:', evmWallet);
    }
  };

  const handleImportKey = async () => {
    await importPrivateKey({
      chainName: 'EVM',
      privateKey: '0x123...',
    });
  };

  // Example of using getWaasWallets
  const waasWallets = getWaasWallets();
  const evmWallets = waasWallets.filter((wallet) => wallet.chain === 'EVM');

  return (
    <div>
      {shouldAutoCreateDynamicWaasWallet && (
        <button onClick={handleCreateWallet}>Create Wallet</button>
      )}
      <button onClick={handleImportKey}>Import Private Key</button>
      {evmWallets.length > 0 && (
        <div>
          <h3>Your EVM Wallets:</h3>
          {evmWallets.map((wallet) => (
            <div key={wallet.address}>Address: {wallet.address}</div>
          ))}
        </div>
      )}
    </div>
  );
}