Message Signing

Learn how to sign messages with EVM wallets using the Dynamic Flutter SDK.

Overview

Message signing allows users to prove ownership of their wallet by signing arbitrary messages. This is commonly used for authentication and verification.

Prerequisites

• Dynamic SDK initialized (see Installation Guide)
• User authenticated (see Authentication Guide)
• EVM wallet available (see Wallet Creation)
• dynamic_sdk_web3dart package installed

Sign a Message

import 'package:dynamic_sdk/dynamic_sdk.dart';

final sdk = DynamicSDK.instance;

Future<String> signMessage({
  required BaseWallet wallet,
  required String message,
}) async {
  try {
    final signature = await sdk.wallets.signMessage(
      wallet: wallet,
      message: message,
    );
    print('Message signed successfully!');
    print('Signature: $signature');
    return signature;
  } catch (e) {
    print('Failed to sign message: $e');
    rethrow;
  }
}

// Usage
final wallet = sdk.wallets.userWallets.first;
final signature = await signMessage(
  wallet: wallet,
  message: 'Hello, Dynamic!',
);

Sign a raw (pre-hashed) message

Use signRawMessage to sign an already-hashed 32-byte digest directly, without the EIP-191 prefix or any additional hashing. This gives you full control over the hashing and serialization, which is what secp256k1-derived chains (Cosmos, Tron, XRP) rely on. To EIP-191 personal-sign raw bytes instead, use signMessageBytes.

Unlike signMessage, signRawMessage is a WaaS (embedded wallet) operation, so it takes the wallet’s walletId and accountAddress rather than a BaseWallet. The message is the pre-hashed digest as a hex string without the 0x prefix.

import 'package:dynamic_sdk/dynamic_sdk.dart';

final sdk = DynamicSDK.instance;

Future<String> signDigest(Uint8List digest32) async {
  final wallet = sdk.wallets.userWallets.firstWhere((w) => w.chain == 'EVM');

  try {
    final signature = await sdk.wallets.signRawMessage(
      walletId: wallet.id,
      accountAddress: wallet.address,
      message: bytesToHex(digest32), // 32-byte digest as hex, no "0x"
    );
    print('Raw message signed successfully!');
    print('Signature: $signature');
    return signature;
  } catch (e) {
    print('Failed to sign raw message: $e');
    rethrow;
  }
}

Method signature

Future<String> signRawMessage({
  required String walletId,
  required String accountAddress,
  required String message,
  String? password,
  SignMessageContext? context,
});

Parameter	Type	Description
walletId	String	Unique identifier of the embedded wallet to sign with.
accountAddress	String	Address of the wallet performing the signature.
message	String	Pre-hashed message as a hex string, without the 0x prefix.
password	String?	Optional WaaS wallet password, if the wallet requires one.
context	SignMessageContext?	Optional sign context forwarded to the MPC relay policy engine.

Sign context (SignMessageContext)

Signing a raw digest hides what the bytes actually represent, so some environments configure a signing policy that rejects context-less raw signs. For those, pass a typed SignMessageContext describing what the digest was derived from. The MPC relay policy engine cryptographically validates the context against the digest, so the payload must be the exact source of the digest — a mismatched context is rejected just like a missing one.

SignMessageContext is exported from package:dynamic_sdk/dynamic_sdk.dart and provides named factories for the common variants:

import 'package:dynamic_sdk/dynamic_sdk.dart';

final sdk = DynamicSDK.instance;
final wallet = sdk.wallets.userWallets.firstWhere((w) => w.chain == 'EVM');

// EIP-7702 authorization: digest is keccak256(0x05 ‖ rlp(chainId, address, nonce))
final signature = await sdk.wallets.signRawMessage(
  walletId: wallet.id,
  accountAddress: wallet.address,
  message: authorizationDigestHex, // hex, no "0x"
  context: SignMessageContext.eip7702Auth(
    address: wallet.address,
    chainId: 1,
    nonce: 0,
  ),
);

For an EVM personal message, use the evmMessage factory with the 0x-prefixed hex of the bytes behind the digest:

final signature = await sdk.wallets.signRawMessage(
  walletId: wallet.id,
  accountAddress: wallet.address,
  message: messageDigestHex,
  context: SignMessageContext.evmMessage(raw: '0x48656c6c6f'),
);

For any variant without a named factory, build one directly with a SignMessageContextType and its payload:

final context = SignMessageContext(
  type: SignMessageContextType.svmMessage,
  payload: 'the original message string',
);

SignMessageContextType covers btcTransaction, eip7702Auth, evmMessage, evmTransaction, evmTypedData, evmUserOperation, stellarMessage, suiMessage, suiTransaction, svmMessage, and svmTransaction.

The context parameter is optional. Only environments whose signing policy requires it will reject a raw sign that omits it — otherwise you can call signRawMessage without a context.

Sign raw bytes (EIP-191)

Use signMessageBytes to personal-sign raw bytes with the EIP-191 prefix applied and the message hashed before signing (equivalent to viem’s signMessage({ raw })). Use this to personal-sign a 32-byte hash such as an ERC-4337 userOpHash, when you want the EIP-191 prefix — unlike signRawMessage, which signs the digest as-is.

import 'dart:typed_data';
import 'package:dynamic_sdk/dynamic_sdk.dart';

final sdk = DynamicSDK.instance;

Future<String> signBytes(BaseWallet wallet, Uint8List bytes) async {
  final signature = await sdk.wallets.signMessageBytes(
    wallet: wallet,
    bytes: bytes, // must not be empty
  );
  return signature;
}

// Usage
final wallet = sdk.wallets.userWallets.first;
final rawBytes = Uint8List.fromList([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
final signature = await signBytes(wallet, rawBytes);

Sign Message Widget

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:dynamic_sdk/dynamic_sdk.dart';

class SignMessageWidget extends StatefulWidget {
  final BaseWallet wallet;

  const SignMessageWidget({Key? key, required this.wallet}) : super(key: key);

  @override
  State<SignMessageWidget> createState() => _SignMessageWidgetState();
}

class _SignMessageWidgetState extends State<SignMessageWidget> {
  final sdk = DynamicSDK.instance;
  final _messageController = TextEditingController();

  String? signature;
  bool isLoading = false;
  String? errorMessage;

  @override
  void dispose() {
    _messageController.dispose();
    super.dispose();
  }

  Future<void> _signMessage() async {
    final message = _messageController.text.trim();

    if (message.isEmpty) {
      setState(() => errorMessage = 'Please enter a message');
      return;
    }

    setState(() {
      isLoading = true;
      errorMessage = null;
      signature = null;
    });

    try {
      final sig = await sdk.wallets.signMessage(
        wallet: widget.wallet,
        message: message,
      );
      setState(() => signature = sig);
    } catch (e) {
      setState(() => errorMessage = 'Failed to sign: $e');
    } finally {
      setState(() => isLoading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(16.0),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          TextField(
            controller: _messageController,
            decoration: const InputDecoration(
              labelText: 'Enter message to sign',
              border: OutlineInputBorder(),
            ),
            maxLines: 3,
          ),
          const SizedBox(height: 16),
          ElevatedButton(
            onPressed: isLoading ? null : _signMessage,
            child: isLoading
                ? const SizedBox(
                    height: 20,
                    width: 20,
                    child: CircularProgressIndicator(strokeWidth: 2),
                  )
                : const Text('Sign Message'),
          ),
          if (signature != null) ...[
            const SizedBox(height: 16),
            Container(
              padding: const EdgeInsets.all(16),
              decoration: BoxDecoration(
                color: Colors.grey[200],
                borderRadius: BorderRadius.circular(8),
              ),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  const Text(
                    'Signature:',
                    style: TextStyle(fontSize: 12, color: Colors.grey),
                  ),
                  const SizedBox(height: 8),
                  SelectableText(
                    signature!,
                    style: const TextStyle(
                      fontSize: 12,
                      fontFamily: 'monospace',
                    ),
                    maxLines: 4,
                  ),
                  const SizedBox(height: 8),
                  TextButton(
                    onPressed: () {
                      Clipboard.setData(ClipboardData(text: signature!));
                      ScaffoldMessenger.of(context).showSnackBar(
                        const SnackBar(content: Text('Signature copied!')),
                      );
                    },
                    child: const Text('Copy'),
                  ),
                ],
              ),
            ),
          ],
          if (errorMessage != null) ...[
            const SizedBox(height: 16),
            Text(
              errorMessage!,
              style: const TextStyle(color: Colors.red, fontSize: 12),
            ),
          ],
        ],
      ),
    );
  }
}

Common Use Cases

Authentication

/// Sign a message to prove wallet ownership
Future<String> authenticateWithSignature(BaseWallet wallet) async {
  final nonce = DateTime.now().millisecondsSinceEpoch.toString();
  final message = 'Sign this message to authenticate: $nonce';

  final signature = await DynamicSDK.instance.wallets.signMessage(
    wallet: wallet,
    message: message,
  );

  // Send signature to your backend for verification
  return signature;
}

Signing User Actions

/// Sign a message to confirm user action
Future<String> signUserAction({
  required BaseWallet wallet,
  required String action,
  required DateTime timestamp,
}) async {
  final message = '''
Action: $action
Wallet: ${wallet.address}
Timestamp: ${timestamp.millisecondsSinceEpoch}
''';

  return await DynamicSDK.instance.wallets.signMessage(
    wallet: wallet,
    message: message,
  );
}

Off-Chain Signatures

/// Create off-chain signature for gasless transactions
Future<String> signOffChainPermit({
  required BaseWallet wallet,
  required String spender,
  required String amount,
  required int deadline,
}) async {
  final message = '''
Permit:
Spender: $spender
Amount: $amount
Deadline: $deadline
''';

  return await DynamicSDK.instance.wallets.signMessage(
    wallet: wallet,
    message: message,
  );
}

Verify Signatures

While signature verification typically happens on the backend or smart contract, here’s how to structure the verification data:

class SignatureData {
  final String message;
  final String signature;
  final String signerAddress;

  SignatureData({
    required this.message,
    required this.signature,
    required this.signerAddress,
  });

  Map<String, String> toJson() {
    return {
      'message': message,
      'signature': signature,
      'signer': signerAddress,
    };
  }
}

// Usage
final signatureData = SignatureData(
  message: 'Hello, Dynamic!',
  signature: signature,
  signerAddress: wallet.address,
);

// Send to backend for verification
final jsonData = signatureData.toJson();

Best Practices

1. Always Handle Errors

Future<String?> signMessageSafely({
  required BaseWallet wallet,
  required String message,
}) async {
  try {
    final signature = await DynamicSDK.instance.wallets.signMessage(
      wallet: wallet,
      message: message,
    );
    return signature;
  } catch (e) {
    print('Could not sign message. Please try again.');
    return null;
  }
}

2. Include Context in Messages

// Bad: Unclear message
const message = '12345';

// Good: Clear message with context
String createClearMessage(BaseWallet wallet) {
  return '''
Welcome to MyApp!

Click "Sign" to prove you own this wallet.

Wallet: ${wallet.address}
Nonce: ${DateTime.now().millisecondsSinceEpoch}
''';
}

3. Show Loading States

class MessageSigner extends StatefulWidget {
  final BaseWallet wallet;

  const MessageSigner({Key? key, required this.wallet}) : super(key: key);

  @override
  State<MessageSigner> createState() => _MessageSignerState();
}

class _MessageSignerState extends State<MessageSigner> {
  bool isLoading = false;

  Future<void> signMessage(String message) async {
    setState(() => isLoading = true);

    try {
      final signature = await DynamicSDK.instance.wallets.signMessage(
        wallet: widget.wallet,
        message: message,
      );
      // Process signature
    } finally {
      setState(() => isLoading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: isLoading ? null : () => signMessage('Hello!'),
      child: isLoading
          ? const CircularProgressIndicator()
          : const Text('Sign Message'),
    );
  }
}

4. Clear Sensitive Data

Future<void> signAndClear(BaseWallet wallet, String message) async {
  String? signature;

  try {
    signature = await DynamicSDK.instance.wallets.signMessage(
      wallet: wallet,
      message: message,
    );
    // ... use signature ...
  } finally {
    signature = null; // Clear from memory
  }
}

Error Handling

Future<String?> signMessageWithErrorHandling({
  required BaseWallet wallet,
  required String message,
}) async {
  try {
    return await DynamicSDK.instance.wallets.signMessage(
      wallet: wallet,
      message: message,
    );
  } catch (e) {
    final errorDesc = e.toString().toLowerCase();

    if (errorDesc.contains('rejected') || errorDesc.contains('denied')) {
      print('User rejected the signature request');
    } else if (errorDesc.contains('unsupported')) {
      print('Wallet does not support message signing');
    } else {
      print('Signing failed: $e');
    }
    return null;
  }
}

Complete Authentication Flow

import 'package:flutter/material.dart';
import 'package:dynamic_sdk/dynamic_sdk.dart';

class AuthenticationWidget extends StatefulWidget {
  final BaseWallet wallet;
  final Function(String signature) onAuthenticated;

  const AuthenticationWidget({
    Key? key,
    required this.wallet,
    required this.onAuthenticated,
  }) : super(key: key);

  @override
  State<AuthenticationWidget> createState() => _AuthenticationWidgetState();
}

class _AuthenticationWidgetState extends State<AuthenticationWidget> {
  final sdk = DynamicSDK.instance;
  bool isLoading = false;
  String? error;

  Future<void> _authenticate() async {
    setState(() {
      isLoading = true;
      error = null;
    });

    try {
      // Generate nonce
      final nonce = DateTime.now().millisecondsSinceEpoch.toString();

      // Create authentication message
      final message = '''
Welcome to MyApp!

Sign this message to authenticate your wallet.

Wallet: ${widget.wallet.address}
Nonce: $nonce
Timestamp: ${DateTime.now().toIso8601String()}

This signature will not trigger any blockchain transaction or cost any gas fees.
''';

      // Sign message
      final signature = await sdk.wallets.signMessage(
        wallet: widget.wallet,
        message: message,
      );

      // Call success callback
      widget.onAuthenticated(signature);
    } catch (e) {
      setState(() => error = 'Authentication failed: $e');
    } finally {
      setState(() => isLoading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        const Text(
          'Authenticate Your Wallet',
          style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
        ),
        const SizedBox(height: 16),
        Text(
          'Wallet: ${widget.wallet.address}',
          style: const TextStyle(fontSize: 14, color: Colors.grey),
        ),
        const SizedBox(height: 32),
        ElevatedButton(
          onPressed: isLoading ? null : _authenticate,
          child: isLoading
              ? const SizedBox(
                  height: 20,
                  width: 20,
                  child: CircularProgressIndicator(strokeWidth: 2),
                )
              : const Text('Sign to Authenticate'),
        ),
        if (error != null) ...[
          const SizedBox(height: 16),
          Text(
            error!,
            style: const TextStyle(color: Colors.red),
          ),
        ],
      ],
    );
  }
}

Next Steps

• Typed Data Signing - Sign structured data (EIP-712)
• Send ETH Transactions - Send transactions
• Smart Contract Interactions - Interact with contracts