useDynamicWaas

Summary

A React hook that provides functionality for managing Dynamic WaaS (Wallet as a Service) 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;
}

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
//   }
// ]

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>
  );
}