delegatedSignMessage

Signs a message using delegated access on behalf of a user

Function Signature

delegatedSignMessage(
  client: DelegatedEvmWalletClient,
  params: {
    walletId: string;
    walletApiKey: string;
    keyShare: ServerKeyShare;
    message: string;
    context?: SignMessageContext;
    onError?: (error: Error) => void;
  }
): Promise<string>

Description

Signs a message on behalf of a user who has granted delegation permission. This function requires delegation credentials (wallet ID, wallet API key, and key share) that are provided to your webhook endpoint when a user approves delegation.

The message is automatically formatted for EVM signing and returns a serialized ECDSA signature.

Parameters

Required Parameters

• client (DelegatedEvmWalletClient) - The delegated client instance created with createDelegatedEvmWalletClient()
• walletId (string) - The wallet ID from the delegation webhook
• walletApiKey (string) - The wallet-specific API key from the delegation webhook
• keyShare (ServerKeyShare) - The server key share from the delegation webhook
• message (string) - The message to sign

Optional Parameters

• context (SignMessageContext) - Additional context for the signing operation. Defaults to { evmMessage: message }
• onError ((error: Error) => void) - Error callback function

Returns

Promise<string> - A hex-encoded ECDSA signature

Example

Basic Message Signing

import { 
  createDelegatedEvmWalletClient,
  delegatedSignMessage 
} from '@dynamic-labs-wallet/node-evm';

const delegatedClient = createDelegatedEvmWalletClient({
  environmentId: 'your-environment-id',
  apiKey: 'your-server-api-key',
});

const signature = await delegatedSignMessage(delegatedClient, {
  walletId: 'wallet-id-from-webhook',
  walletApiKey: 'wallet-api-key-from-webhook',
  keyShare: keyShareFromWebhook,
  message: 'Hello, World!',
});

console.log('Signature:', signature);

With Context

const signature = await delegatedSignMessage(delegatedClient, {
  walletId: 'wallet-id-from-webhook',
  walletApiKey: 'wallet-api-key-from-webhook',
  keyShare: keyShareFromWebhook,
  message: 'Sign this message to authenticate',
  context: {
    evmMessage: 'Sign this message to authenticate',
  },
});

With Error Handling

const signature = await delegatedSignMessage(delegatedClient, {
  walletId: 'wallet-id-from-webhook',
  walletApiKey: 'wallet-api-key-from-webhook',
  keyShare: keyShareFromWebhook,
  message: 'Hello, World!',
  onError: (error) => {
    console.error('Signing error:', error);
    // Implementation (important-comment)
  },
});

Complete Example with Try-Catch

try {
  const signature = await delegatedSignMessage(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    message: 'Sign this to prove ownership',
  });
  
  console.log('Message signed successfully');
  return signature;
} catch (error) {
  console.error('Failed to sign message:', error);
  throw error;
}

Type Definitions

type ServerKeyShare = {
  pubkey: {
    pubkey: Uint8Array;
  };
  secretShare: string;
};

type SignMessageContext = {
  evmMessage?: string;
  [key: string]: any;
};

Common Use Cases

Authentication

async function authenticateUser(userId: string): Promise<string> {
  const credentials = await getDelegationCredentials(userId);
  const nonce = generateNonce();
  const message = `Authenticate with nonce: ${nonce}`;
  
  return await delegatedSignMessage(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    message,
  });
}

Proof of Ownership

async function signOwnershipProof(
  userId: string,
  resourceId: string
): Promise<string> {
  const credentials = await getDelegationCredentials(userId);
  const timestamp = Date.now();
  const message = `I own resource ${resourceId} at ${timestamp}`;
  
  return await delegatedSignMessage(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    message,
  });
}

Error Handling

The function throws an error if:

• Any required parameter is missing or invalid
• The delegation credentials are expired or revoked
• The MPC signing operation fails
• Network communication with Dynamic services fails

try {
  const signature = await delegatedSignMessage(delegatedClient, params);
} catch (error) {
  if (error.message.includes('key share')) {
    console.error('Invalid or expired delegation credentials');
  } else if (error.message.includes('wallet')) {
    console.error('Wallet not found or access denied');
  } else {
    console.error('Signing failed:', error);
  }
}

Security Considerations

• Credential Validation: Always validate delegation credentials before using them
• Message Validation: Validate message content to prevent signing malicious data
• Credential Storage: Never log or expose wallet API keys or key shares

Related Functions

• createDelegatedEvmWalletClient() - Create the client for delegated operations
• delegatedSignTransaction() - Sign transactions instead of messages
• verifyMessageSignature() - Verify message signatures
• Delegated Access Guide - Complete guide on using delegated access