From 017fc897f4c5971948af24372dc4945c5e3b36d1 Mon Sep 17 00:00:00 2001
From: Sameh Abouelsaad <farouks@incubaid.com>
Date: Fri, 16 May 2025 02:16:36 +0300
Subject: [PATCH] docs: Clarify the rationale for split  trait implementations
 for native and WASM targets

---
 evm_client/tests/balance.rs    | 6 ++++++
 evm_client/tests/evm_client.rs | 6 ++++++
 evm_client/tests/wasm.rs       | 2 ++
 3 files changed, 14 insertions(+)

diff --git a/evm_client/tests/balance.rs b/evm_client/tests/balance.rs
index 6db8d54..658df21 100644
--- a/evm_client/tests/balance.rs
+++ b/evm_client/tests/balance.rs
@@ -3,6 +3,11 @@ use evm_client::{EvmClient, EvmProvider, Signer};
 // Dummy signer that returns a known Ethereum address (Vitalik's address)
 struct DummySigner;
 
+// --- IMPORTANT ---
+// The Signer trait's async methods require different trait bounds on native vs WASM:
+// - Native Rust: futures must be Send, so use #[async_trait::async_trait]
+// - WASM (wasm32): futures do NOT require Send, so use #[async_trait::async_trait(?Send)]
+// This split is required for cross-platform test compatibility. DO NOT merge these impls!
 #[cfg(not(target_arch = "wasm32"))]
 #[async_trait::async_trait]
 impl Signer for DummySigner {
@@ -35,6 +40,7 @@ async fn test_get_balance_vitalik() {
 #[cfg(target_arch = "wasm32")]
 use wasm_bindgen_test::*;
 
+// See explanation above for why this impl uses ?Send
 #[cfg(target_arch = "wasm32")]
 #[async_trait::async_trait(?Send)]
 impl Signer for DummySigner {
diff --git a/evm_client/tests/evm_client.rs b/evm_client/tests/evm_client.rs
index fd790dc..93c0eaa 100644
--- a/evm_client/tests/evm_client.rs
+++ b/evm_client/tests/evm_client.rs
@@ -4,6 +4,11 @@ use evm_client::{EvmClient, EvmProvider, Signer, EvmError};
 
 struct DummySigner;
 
+// --- IMPORTANT ---
+// The Signer trait's async methods require different trait bounds on native vs WASM:
+// - Native Rust: futures must be Send, so use #[async_trait::async_trait]
+// - WASM (wasm32): futures do NOT require Send, so use #[async_trait::async_trait(?Send)]
+// This split is required for cross-platform test compatibility. DO NOT merge these impls!
 #[cfg(target_arch = "wasm32")]
 #[async_trait::async_trait(?Send)]
 impl Signer for DummySigner {
@@ -15,6 +20,7 @@ impl Signer for DummySigner {
     }
 }
 
+// See explanation above for why this impl uses #[async_trait::async_trait]
 #[cfg(not(target_arch = "wasm32"))]
 #[async_trait::async_trait]
 impl Signer for DummySigner {
diff --git a/evm_client/tests/wasm.rs b/evm_client/tests/wasm.rs
index 0dec357..38fa065 100644
--- a/evm_client/tests/wasm.rs
+++ b/evm_client/tests/wasm.rs
@@ -1,3 +1,5 @@
+// This test file is only compiled for wasm32. The DummySigner uses #[async_trait::async_trait(?Send)]
+// because WASM async traits do not require Send. See balance.rs or evm_client.rs for the trait bound split rationale.
 #![cfg(target_arch = "wasm32")]
 use wasm_bindgen_test::*;
 wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);