TSS-MPC Guide

Developer guide for using Dynamic’s TSS-MPC implementation

TSS-MPC Embedded Wallets

The TSS-MPC implementation is currently in beta testing. We may introduce significant changes that could impact wallet functionality. Do not store any assets you cannot afford to lose.

Overview

This version of Dynamic TSS-MPC supports 2/2 and 2/3 threshold signature schemes. This guide works for both React and React Native implementations. Server wallets are accessible through our node SDKs. Headless documentation will be provided in future updates.

Future releases will provide additional key share storage flexibility, including independent hosting of backup shares.

Supported Chains

• EVM
• Solana
• Sui

Breaking changes may occur in future updates.

Known Limitations

The following features are currently not supported but will be included in subsequent releases:

1. Low-Level Access to Signers for chains other than EVM and SVM and Sui
2. Pre-Generated wallets

Getting Started

1. Share Environment ID

Do not mix this environment with an existing environment containing V2 or V1 wallets.

2. Request Feature Access

Share your Environment ID with the Dynamic team to enable TSS-MPC via a feature flag.

3. Enable Embedded Wallets V3

Navigate to the Dynamic Dashboard > Developers, Enabled Embedded Wallets and set the default wallet version to V3.

4. Set up your SDK

You must be on react sdk v4.20.0 and later versions.

React Set Up

reference example: https://github.com/dynamic-labs/mpc-react-demo

1. Install React SDK

npm i @dynamic-labs/sdk-react-core

2. Install Wallet Connectors - install only chains you require

npm i @dynamic-labs/ethereum
npm i @dynamic-labs/solana
npm i @dynamic-labs/sui

3. Configure Your Provider

Include the connectors inside your provider settings:

import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
import { SolanaWalletConnectors } from '@dynamic-labs/solana';
import { SuiWalletConnectors } from '@dynamic-labs/sui';


const connectors: [
    EthereumWalletConnectors,
    SolanaWalletConnectors,
    SuiWalletConnectors
  ],

const settings = {
  ...existingSettings,
  walletConnectors: connectors,
};

return (
  <DynamicContextProvider
    theme={theme}
    settings={settings}
    enableInstrumentation
  >
    {/* Your app components */}
  </DynamicContextProvider>
);

4. Access the walletClient, and/or signer as you would with Dynamic previously

import { FC, useCallback, useState } from 'react';
import { encodeFunctionData, parseUnits } from 'viem';
import { baseSepolia } from 'viem/chains';
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isEthereumWallet } from '@dynamic-labs/ethereum-core';

  const { primaryWallet } = useDynamicContext();;

  const handleSubmit = useCallback(
    async (args: TransactionArgs & { action: 'send' | 'approve' }) => {
      if (!primaryWallet || !isEthereumWallet(primaryWallet) || isLoading) {
        return;
      }

      try {
        const provider = await primaryWallet.getWalletClient();

        // Check if we're on Base Sepolia
        const chain = await provider.getChainId();
        if (chain !== baseSepolia.id) {
          setErrorMessage(
            `Please switch to Base Sepolia network (Chain ID: ${baseSepolia.id}). Current chain ID: ${chain}`,
          );
          return;
        }

        const usdcAmount = parseUnits(args.amount, 6); // USDC has 6 decimal places

        const transaction = {
          chain: baseSepolia,
          data: await encodeFunctionData({
            abi: USDC_ABI,
            args: [args.toAddress, usdcAmount],
            functionName: args.action === 'send' ? 'transfer' : 'approve',
          }),
          to: USDC_CONTRACT_ADDRESS as `0x${string}`,
        };

        const hash = await provider.sendTransaction(transaction);
        setTxnHash(hash);
      }
      catch(e: any){
        console.log('error', e)
      }
    },
    [primaryWallet],
  );

Access create & import MPC functionality through useDynamicWaas hook

  const { createWalletAccount, importPrivateKey } = useDynamicWaas();

  const onCreate = async () => {
    const createWalletAccountResult = await createWalletAccount([
      'EVM',
    ]);
  };

  const onImport = async () => {
    const importPrivateKeyResult = await importPrivateKey({
      chainName: selectedChain,
      privateKey,
    });
  };

Access MPC functionality through the connector directly

import { DynamicWaasEVMConnector } from '@dynamic-labs/ethereum';

// Cast the connector to the appropriate type
const waasConnector = primaryWallet.connector as DynamicWaasEVMConnector;

// Create a new wallet account
const walletAccount = await waasConnector.createWalletAccount();

// Get a wallet client for a specific account address
const walletClient = await waasConnector.getWalletClientByAddress({
  accountAddress: walletAccount.accountAddress,
});

// Export the client keyshares, a txt file will be downloaded on the client
await waasConnector.exportClientKeyshares({
  accountAddress: walletAccount.accountAddress,
});

// Export the private key (requires a display container for security)
await waasConnector.exportPrivateKey({
  accountAddress: walletAccount.accountAddress,
  displayContainer: document.createElement('iframe'), // Replace with your secure container
});

// Import a private key to create a new wallet
const importedWallet = await waasConnector.importPrivateKey({
  privateKey: 'your-private-key-here', // Replace with actual private key
});

React Native Set Up

The wallet connectors come bundled with the webview for React Native, so no extra setup is needed on the client, simply ensure it’s enabled in the dashboard (as described in steps above) and when a user signs up, they will receive an MPC wallet on all enabled chains.

You can then use the wallets as you usually would, using Viem for example.

Please note that manually creating wallets, headless key export and Google Drive backup are not supported in React Native today, but will be in the near future.

You must also whitelist the dynamic auth URL for the iframe connection to work. Here’s how:

1. In an HTTP header (e.g., Express.js):

res.setHeader("Content-Security-Policy", "frame-src https://app.dynamicauth.com 'self';");

⚠️ If you’re already setting CSP, append https://app.dynamicauth.com to the existing frame-src list rather than replacing it.

---

2. In an HTML <meta> tag:

<meta http-equiv="Content-Security-Policy" content="frame-src https://app.dynamicauth.com 'self';">

---

3. In NGINX config:

add_header Content-Security-Policy "frame-src https://app.dynamicauth.com 'self';";

---

4. In Vercel or Netlify (via headers file):

vercel.json:

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Content-Security-Policy",
          "value": "frame-src https://app.dynamicauth.com 'self';"
        }
      ]
    }
  ]
}

_headers (Netlify):

/*
  Content-Security-Policy: frame-src https://app.dynamicauth.com 'self';

Key Wallet Functions

Creating and Importing Wallets

createWalletAccount()

Creates a new TSS-MPC wallet account.

importPrivateKey(options)

Imports a private key.

Parameters:

• privateKey: string - The private key to import
• thresholdSignatureScheme: string - Defaults to ‘TWO_OF_TWO’

Export Functions

exportPrivateKey(options)

Exports the private key for a specific account.

Parameters:

• accountAddress: string - The address of the account to export
• displayContainer: HTMLIFrameElement - The container to display the private key in

exportClientKeyshares(options)

Exports client keyshares for a specific account.

Parameters:

• accountAddress: string - The address of the account to export keyshares for

Server Wallets

Dynamic Server Wallets let you spin up wallets, sign nd run complex flows using your backend.

Server Wallets with node SDK

Reference example: https://github.com/dynamic-labs/mpc-node-server-demo

1. Retrieve your auth token

Navigate to the Dynamic Dashboard and create a new API token.

2. Install desired Node SDKs

npm i @dynamic-labs-wallet/node-evm
npm i @dynamic-labs-wallet/node-svm

3. Create client with authenticateApiToken call. Separate clients are needed for each chain.

const BASE_API_URL = 'https://app.dynamicauth.com';
const MPC_RELAY_URL = 'https://relay.dynamicauth.com';


export const authenticatedEvmClient = async ({
      authToken,
      environmentId,
      baseApiUrl,
      baseMPCRelayApiUrl,
    }: {
      authToken: string;
      environmentId: string;
      baseApiUrl?: string;
      baseMPCRelayApiUrl?: string;
    }) => {
      const client = new DynamicEvmWalletClient({
        authToken,
        environmentId,
        baseApiUrl: BASE_API_URL,
        baseMPCRelayApiUrl: MPC_RELAY_URL,
      });
      await client.authenticateApiToken(authToken);
      return client;
  };

4. Access MPC functionality by creating a new wallet account

  const AUTH_TOKEN = 'your-auth-token';
  const ENVIRONMENT_ID = 'your-environment-id';

  const evmClient = await authenticatedEvmClient({
    authToken: AUTH_TOKEN,
    environmentId: ENVIRONMENT_ID,
  });

  const thresholdSignatureScheme = 'TWO_OF_TWO'; // or 'TWO_OF_THREE'
  const password = 'your-optional-password';
  const onError = (error: Error) => {
    // handle error
    console.error(error);
  };

  const {
    accountAddress,
    rawPublicKey,
    publicKeyHex,
    externalServerKeyShares,
      } = await evmClient.createWalletAccount({
        thresholdSignatureScheme,
        password,
        onError,
      });

You can now use the accountAddress to sign messages, create transactions, and more. You can also back up your externalServerKeyShares to a secure location.

5. Example: Sign a message with the MPC wallet account

  const AUTH_TOKEN = 'your-auth-token';
  const ENVIRONMENT_ID = 'your-environment-id';

  const evmClient = await authenticatedEvmClient({
    authToken: AUTH_TOKEN,
    environmentId: ENVIRONMENT_ID,
  });

  const message = 'Hello, world!';
  const accountAddress = '0x1234567890123456789012345678901234567890';
  const password = 'your-optional-password';

  const serializedSignature = await evmClient.signMessage({
    message,
    accountAddress,
    password,
  });