Best Practices for Wallets

• Pairing - Creating secure connections between wallets and DApps
• Session Management - Handling proposal, approval, rejection, and termination of sessions
• WebSocket Connection - Maintaining stable connection with the relay network
• Error Handling - Processing and communicating errors between components

​

Checklist Before Going Live

​

1. User Feedback and Messaging

​

Context

​

Best Practices

• ✅ Display clear success and error messages for all user interactions
• ✅ Provide loading indicators during connection and transaction processing
• ✅ Include status indicators for internet availability
• ✅ Return errors to the DApp (not just the user) to allow proper state management

An example of a successful connection message in a Rainbow wallet

​

2. Pairing Implementation

​

Pairing Overview

​

Pairing Process

const uri = 'wc:a13aef...'; // pairing URI received from DApp (typically via QR code)
try {
    // Initiate pairing with the DApp
    await walletKit.pair({ uri });
    // Display success message to user
} catch (error) {
    // Handle and display specific error (see Expected Errors section)
    console.error('Pairing failed:', error);
}

​

Pairing State Management

​

Pairing Expiry

// Subscribe to pairing expiry events
core.pairing.events.on("pairing_expire", (event) => {
    const { topic } = event; // The topic identifies which pairing expired
    
    // Update UI to inform user the connection has expired
    // E.g., remove the pairing from active connections list
});

​

Expected Pairing Errors

​

3. Session Proposal Handling

​

What is a Session Proposal?

​

Sample Session Proposal Object

{
  id: '1234567890',
  params: {
    proposer: {
      publicKey: '0x...',
      metadata: {
        name: 'Example DApp',
        description: 'A DApp for testing WalletKit',
        url: 'https://example.com',
        icons: ['https://example.com/icon.png']
      }
    },
    requiredNamespaces: {
      eip155: {
        chains: ['eip155:1'],
        methods: ['eth_sendTransaction', 'personal_sign'],
        events: ['accountsChanged', 'chainChanged']
      }
    }
  }
}

​

Approving a Session

try {
    // Show loading indicator when user taps "Approve"
    showLoadingIndicator();
    
    // Approve the session with selected accounts and chains
    await walletKit.approveSession({
      id: proposal.id,
      namespaces: {
        eip155: {
          accounts: ['eip155:1:0x...'], // Format: chainId:accountAddress
          methods: proposal.requiredNamespaces.eip155.methods,
          events: proposal.requiredNamespaces.eip155.events
        }
      }
    });
    
    // Hide loading indicator, show success message
    hideLoadingIndicator();
    showSuccessMessage('Connection approved');
} catch (error) {
    // Hide loading indicator, show error message
    hideLoadingIndicator();
    showErrorMessage(`Connection failed: ${error.message}`);
}

​

Rejecting a Session

try {
    // Show loading indicator when user taps "Reject"
    showLoadingIndicator();
    
    // Reject the session with reason
    await walletKit.rejectSession({
      id: proposal.id,
      reason: {
        code: 4001,
        message: 'User rejected the request'
      }
    });
    
    // Hide loading indicator, show success message
    hideLoadingIndicator();
    showMessage('Connection rejected');
} catch (error) {
    // Hide loading indicator, show error message
    hideLoadingIndicator();
    showErrorMessage(`Error: ${error.message}`);
}

​

4. Mobile Linking

​

What is Mobile Linking?

​

Deep Links vs Universal Links

• Launch the target app directly
• Support passing parameters in the URL
• Work consistently across platforms

​

Why use Mobile Linking?

​

Establishing Communication Between Mobile Wallets and Apps

1. QR Code Handshake: The mobile app (Dapp) generates a unique URI (Uniform Resource Identifier) and displays it as a QR code. This URI acts like a secret handshake. When the user scans the QR code or copy/pastes the URI using their wallet app, they establish a connection. It’s like saying, “Hey, let’s chat!”
2. Deep Links and Universal Links: The URI from the QR code allows the wallet app to create a deep link or universal link. These links work on both Android and iOS. They enable seamless communication between the wallet and the app.

​

Key Behavior to Address

• Redirecting to the wrong app when multiple apps share the same redirect metadata (e.g., a desktop and mobile version of the same Dapp).
• Opening an unrelated application if a QR code is scanned on a different device than where the wallet is installed.

​

Recommended Approach

• Restrict Redirect Metadata to Deep Link Use Cases: Redirect metadata should only be used when the session proposal is initiated through a deep link. QR code scans should not trigger app redirects using session proposal metadata.

​

Connection Flow

1. Dapp prompts user: The Dapp asks the user to connect.
2. User chooses wallet: The user selects a wallet from a list of compatible wallets.
3. Redirect to wallet: The user is redirected to their chosen wallet.
4. Wallet approval: The wallet prompts the user to approve or reject the session (similar to granting permission).
5. Return to dapp:
   • Manual return: The wallet asks the user to manually return to the Dapp.
   • Automatic return: Alternatively, the wallet automatically takes the user back to the Dapp.
6. User reunites with dapp: After all the interactions, the user ends up back in the Dapp.

​

Sign Request Flow

1. Automatic redirect: The Dapp automatically sends the user to their previously chosen wallet.
2. Approval prompt: The wallet asks the user to approve or reject the request.
3. Return to dapp:
   • Manual return: The wallet asks the user to manually return to the Dapp.
   • Automatic return: Alternatively, the wallet automatically takes the user back to the Dapp.
4. User reconnects: Eventually, the user returns to the Dapp.

​

Platform Specific Preparation

​

How to Test

​

Implementing Mobile Linking

// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    // Check if URL is a WalletKit deep link
    if WalletKit.instance.isWalletConnectDeepLink(url) {
        // Handle WalletConnect URL
        Task {
            do {
                try await WalletKit.instance.handleDeepLink(url)
                return true
            } catch {
                // Handle error
                print("Deep link error: \(error)")
                return false
            }
        }
    }
    return false
}

​

Redirecting Back to DApp

// After session approval or transaction signing
func redirectBackToDApp(using redirectUrl: String?) {
    guard let redirectUrl = redirectUrl,
          let url = URL(string: redirectUrl) else { return }
    
    DispatchQueue.main.async {
        UIApplication.shared.open(url)
    }
}

​

5. Session Request

try {
    // Show loading indicator when user approves/rejects
    showLoadingIndicator();
    
    // Respond to the session request
    await walletKit.respondSessionRequest({
      topic: request.topic,
      response: {
        id: request.id,
        jsonrpc: '2.0',
        result: response // The response could be a signature or other data
      }
    });
    
    // Hide loading indicator, show success message
    hideLoadingIndicator();
    showSuccessMessage('Request completed');
} catch (error) {
    // Hide loading indicator, show error message
    hideLoadingIndicator();
    showErrorMessage(`Request failed: ${error.message}`);
}

​

Session Request Expiry

walletKit.on("session_request_expire", (event) => {
  // Request expired and any modal displaying it should be removed
  const { id } = event;
  // Update UI to remove the request
  removeRequestFromUI(id);
});

​

Expected Session Request Errors

​

6. Connection State

core.relayer.on("relayer_connect", () => {
  // Connection to the relay server is established
  updateConnectionStatus('connected');
})

core.relayer.on("relayer_disconnect", () => {
  // Connection to the relay server is lost
  updateConnectionStatus('disconnected');
})

​

Connection State Messages

​

7. Latency

​

Target Latency

• Under 5 seconds in normal conditions
• Under 15 seconds when throttled (3G network speed)

• Under 5 seconds in normal conditions
• Under 10 seconds when throttled (3G network speed)

​

How to Test

​

8. Verify API

• Domain match
• Unverified
• Mismatch
• Threat

​

Domain Risk Detection

• Domain match: The domain linked to this request has been verified as this application’s domain.
  • This interface appears when the domain a user is attempting to connect to has been ‘verified’ in our domain registry as the registered domain of the application the user is trying to connect to, and the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of VALID.
• Unverified: The domain sending the request cannot be verified.
  • This interface appears when the domain a user is attempting to connect to has not been verified in our domain registry, but the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of UNKNOWN.
• Mismatch: The application’s domain doesn’t match the sender of this request.
  • This interface appears when the domain a user is attempting to connect to has been flagged as a different domain to the one this application has verified in our domain registry, but the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of INVALID
• Threat: This domain is flagged as malicious and potentially harmful.
  • This interface appears when the domain a user is attempting to connect to has been flagged as malicious on one or more of the security tools we work with. The verifyContext included in the request will contain parameter isScam with value true.

​

Verify API Implementation

​

How to Test

​

Error Messages

​

9. Latest SDK Version

​

Subscribe to Updates

​

10. Testing WalletKit Features

​

Test Scenarios

​

11. Troubleshooting

​

Common Issues

​

Resources

• React Wallet - for testing DApps, features, Verify API messages, etc.
• React DApp - for testing wallets
• Malicious React DApp - for testing Verify API with malicious domain