@chainberry/trust-wallet-core 2.0.0 → 2.5.0

package/ios/ChainberryTrustWalletCoreModule.swift

@@ -0,0 +1,231 @@
+import ExpoModulesCore
+import UIKit
+import WalletCore
+@preconcurrency import LocalAuthentication
+
+// Mnemonic/private-key material never crosses back to JS except `exportMnemonic` — an
+// explicit, biometric/passcode-gated backup flow. Every other method returns only
+// walletIds, addresses, or signed transaction bytes/hex.
+public class ChainberryTrustWalletCoreModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("TrustWalletCore")
+
+    // strength 128 = 12 words, 256 = 24 words. Returns { walletId, addresses }.
+    // No BIP-39 passphrase support: signTransaction always reconstructs the wallet with an
+    // empty passphrase, so accepting one here would derive addresses from a seed different
+    // from the one actually used to sign — always pass "" to stay consistent with that.
+    // isTestnet selects the address format for BTC/LTC/BCH (see ChainSigner.address(for:)) —
+    // every other chain's address is the same on mainnet and testnet.
+    AsyncFunction("createWallet") { (strength: Int, isTestnet: Bool) throws -> [String: Any] in
+      guard let wallet = HDWallet(strength: Int32(strength), passphrase: "") else {
+        throw Exception(name: "WalletError", description: "Failed to generate wallet")
+      }
+      do {
+        return try Self.persistNewWallet(wallet: wallet, isTestnet: isTestnet)
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+
+    // One-time mnemonic exposure from JS, at import only — never retained after this call.
+    // Returns { walletId, addresses }. No BIP-39 passphrase support (see `createWallet`).
+    AsyncFunction("importWallet") { (mnemonic: String, isTestnet: Bool) throws -> [String: Any] in
+      guard let wallet = HDWallet(mnemonic: mnemonic, passphrase: "") else {
+        throw Exception(name: "InvalidMnemonic", description: "Invalid mnemonic phrase")
+      }
+      do {
+        return try Self.persistNewWallet(wallet: wallet, isTestnet: isTestnet)
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+
+    // Reads only the ungated metadata store — no biometric prompt.
+    AsyncFunction("listWallets") { () throws -> [[String: Any]] in
+      do {
+        return try NativeWalletStore.loadMetadata().map { walletId, addresses in
+          ["walletId": walletId, "addresses": addresses]
+        }
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+
+    // Irreversible — requires a fresh biometric/passcode confirmation before anything is
+    // deleted, same gate as `signTransaction`/`exportMnemonic`. A compromised/malicious JS
+    // caller can still invoke this directly (there's no UI call site today), so the gate
+    // must live here rather than in JS.
+    AsyncFunction("deleteWallet") { (walletId: String) async throws -> Void in
+      do {
+        let id = try NativeWalletStore.validateWalletId(walletId)
+        _ = try await Self.authenticatedContext(reason: "Delete wallet")
+        try NativeWalletStore.deleteMnemonic(walletId: id)
+        var metadata = try NativeWalletStore.loadMetadata()
+        metadata.removeValue(forKey: id)
+        try NativeWalletStore.saveMetadata(metadata)
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+
+    // Triggers the native biometry/passcode prompt, then signs entirely in-process.
+    // Returns { signedTx, meta? }. isTestnet must match whatever `createWallet`/`importWallet`
+    // used — see ChainSigner.key(for:) (a mismatch signs with the wrong key for BTC/LTC).
+    AsyncFunction("signTransaction") { (walletId: String, chain: String, unsignedTx: [String: Any], isTestnet: Bool) async throws -> [String: Any] in
+      do {
+        let id = try NativeWalletStore.validateWalletId(walletId)
+        let chainKey = try ChainKey(fromJs: chain)
+        try await Self.confirmTransaction(chain: chainKey, unsignedTx: unsignedTx)
+        let context = try await Self.authenticatedContext(reason: "Sign transaction")
+        let mnemonic = try NativeWalletStore.loadMnemonic(walletId: id, context: context)
+        guard let wallet = HDWallet(mnemonic: mnemonic, passphrase: "") else {
+          throw Exception(name: "InvalidMnemonic", description: "Stored mnemonic failed validation")
+        }
+        let result = try ChainSigner.sign(chain: chainKey, wallet: wallet, unsignedTx: unsignedTx, isTestnet: isTestnet)
+        var response: [String: Any] = ["signedTx": result.signedTx]
+        if let meta = result.meta { response["meta"] = meta }
+        return response
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+
+    // The one sanctioned mnemonic exposure — explicit backup flow only.
+    AsyncFunction("exportMnemonic") { (walletId: String) async throws -> String in
+      do {
+        let id = try NativeWalletStore.validateWalletId(walletId)
+        let context = try await Self.authenticatedContext(reason: "Reveal recovery phrase")
+        return try NativeWalletStore.loadMnemonic(walletId: id, context: context)
+      } catch let e as NativeWalletStoreError {
+        throw e.asException
+      }
+    }
+  }
+
+  // MARK: - Helpers
+
+  /// Presents a native UIAlertController showing decoded tx details (chain, recipient, amount,
+  /// fee). The user must tap "Confirm & Sign" before biometric auth fires — this is the only
+  /// place in the native module where informed consent is collected.
+  private static func confirmTransaction(chain: ChainKey, unsignedTx: [String: Any]) async throws {
+    let message = ChainSigner.buildSummary(chain: chain, unsignedTx: unsignedTx)
+    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+      DispatchQueue.main.async {
+        let scene = UIApplication.shared.connectedScenes
+          .filter({ $0.activationState == .foregroundActive })
+          .compactMap({ $0 as? UIWindowScene })
+          .first
+        var rootVC = scene?.windows.first(where: { $0.isKeyWindow })?.rootViewController
+        while let presented = rootVC?.presentedViewController { rootVC = presented }
+        guard let topVC = rootVC else {
+          continuation.resume(throwing: Exception(name: "NoViewController", description: "Cannot present confirmation"))
+          return
+        }
+        let alert = UIAlertController(title: "Confirm Transaction", message: message, preferredStyle: .alert)
+        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel) { _ in
+          continuation.resume(throwing: Exception(name: "UserCancelled", description: "Transaction cancelled by user"))
+        })
+        alert.addAction(UIAlertAction(title: "Confirm & Sign", style: .default) { _ in
+          continuation.resume(returning: ())
+        })
+        topVC.present(alert, animated: true)
+      }
+    }
+  }
+
+  private static func persistNewWallet(wallet: HDWallet, isTestnet: Bool) throws -> [String: Any] {
+    let walletId = UUID().uuidString
+    var addresses: [String: String] = [:]
+    for chain in ChainKey.allCases {
+      addresses[chain.rawValue] = ChainSigner.address(for: chain, wallet: wallet, isTestnet: isTestnet)
+    }
+
+    try NativeWalletStore.saveMnemonic(wallet.mnemonic, walletId: walletId)
+    do {
+      var metadata = try NativeWalletStore.loadMetadata()
+      metadata[walletId] = addresses
+      try NativeWalletStore.saveMetadata(metadata)
+    } catch {
+      // The mnemonic is already persisted but has no metadata pointer — compensate by
+      // best-effort deleting it rather than leaving a permanent, invisible orphan. If this
+      // rollback delete also fails, there's nothing more useful to do than propagate the
+      // original error; the item is at least no worse off than before this call.
+      try? NativeWalletStore.deleteMnemonic(walletId: walletId)
+      throw error
+    }
+
+    return ["walletId": walletId, "addresses": addresses]
+  }
+
+  /// Prompts biometry-or-device-passcode via `.deviceOwnerAuthentication` (Apple's
+  /// combined policy — no separate fallback branch needed), then hands back the
+  /// now-authenticated context for a single Keychain read via `kSecUseAuthenticationContext`.
+  private static func authenticatedContext(reason: String) async throws -> LAContext {
+    let context = LAContext()
+    var evalError: NSError?
+    guard context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &evalError) else {
+      throw classifyAuthError(evalError, fallbackDescription: "No biometry or device passcode is set up")
+    }
+    return try await withCheckedThrowingContinuation { continuation in
+      context.evaluatePolicy(.deviceOwnerAuthentication, localizedReason: reason) { success, authError in
+        if success {
+          continuation.resume(returning: context)
+        } else {
+          continuation.resume(throwing: classifyAuthError(authError, fallbackDescription: "Authentication failed"))
+        }
+      }
+    }
+  }
+
+  /// Classifies an `LAError` from either `canEvaluatePolicy`'s precheck or `evaluatePolicy`'s
+  /// prompt callback into the same typed error codes Android's `NativeWalletStore.kt`
+  /// (`classifyPromptError`/`AuthUnavailable`) uses, so `use-wallet.ts`'s `WALLET_ERROR_COPY` —
+  /// written once, keyed by code, shared across both platforms — actually fires here instead of
+  /// every prompt failure collapsing into one generic "Authentication failed" banner. This
+  /// matters most for cancellation: dismissing the prompt must produce `ERR_WALLET_AUTH_CANCELLED`
+  /// (mapped to a quiet no-op, not a banner) on both platforms, not just Android.
+  ///
+  /// Deliberately does not attempt an iOS equivalent of Android's `KeyInvalidated`
+  /// (`KeyPermanentlyInvalidatedException` after an enrollment change) — on iOS that surfaces
+  /// later, as a `SecItemCopyMatching` `OSStatus` failure inside `loadMnemonic`, not as an
+  /// `LAError` here; aligning that would mean auditing `NativeWalletStore.classify(_:)`'s
+  /// `errSecAuthFailed`/`errSecInteractionNotAllowed` handling separately; scoped out of this
+  /// pass since a wrong OSStatus->meaning mapping there is materially harder to get right without
+  /// device verification than this prompt-level LAError classification is.
+  private static func classifyAuthError(_ error: Error?, fallbackDescription: String) -> Exception {
+    guard let laError = error as? LAError else {
+      return Exception(
+        name: "AuthenticationFailed",
+        description: error?.localizedDescription ?? fallbackDescription,
+        code: "ERR_AUTHENTICATION_FAILED"
+      )
+    }
+    switch laError.code {
+    case .userCancel, .appCancel, .systemCancel:
+      // User dismissed the prompt rather than authentication actually failing — kept distinct
+      // from the default case below so `WALLET_ERROR_COPY`'s `null` entry for this code can
+      // treat it as a quiet no-op instead of an error to surface (mirrors Android's
+      // `AuthCancelled`).
+      return Exception(name: "AuthCancelled", description: "Authentication was cancelled", code: "ERR_WALLET_AUTH_CANCELLED")
+    case .biometryLockout:
+      // iOS exposes one lockout state (cleared only by a passcode unlock), closest to Android's
+      // ERROR_LOCKOUT_PERMANENT rather than its auto-clearing temporary variant.
+      return Exception(
+        name: "AuthLockedOutPermanent",
+        description: "Too many failed authentication attempts — unlock your device to reset",
+        code: "ERR_WALLET_AUTH_LOCKED_OUT_PERMANENT"
+      )
+    case .biometryNotAvailable, .biometryNotEnrolled, .passcodeNotSet:
+      // Existing-wallet-use-time unavailability (no secure auth is currently satisfiable) —
+      // mirrors Android's `AuthUnavailable` precheck, distinct from `.noDevicePasscode`
+      // (`ERR_NO_DEVICE_PASSCODE`) which is specifically the wallet-*creation*-time gate.
+      return Exception(
+        name: "AuthUnavailable",
+        description: "Authentication unavailable: \(laError.localizedDescription)",
+        code: "ERR_WALLET_AUTH_UNAVAILABLE"
+      )
+    default:
+      return Exception(name: "AuthenticationFailed", description: laError.localizedDescription, code: "ERR_AUTHENTICATION_FAILED")
+    }
+  }
+}

package/ios/NativeWalletStore.swift

@@ -0,0 +1,232 @@
+import Foundation
+import Security
+import LocalAuthentication
+import ExpoModulesCore
+
+/// Errors surfaced to the Expo bridge as `Exception`s (via `.asException`) by the caller.
+///
+/// `.notFound` and `.corrupted` are deliberately distinct: `.notFound` means "there is
+/// legitimately nothing here yet" (e.g. no metadata has ever been written, or a wallet id
+/// has no matching Keychain item) and is safe to treat as an empty/absent result. `.corrupted`
+/// means "something is here but it isn't what we expect" (malformed JSON, non-UTF8 mnemonic
+/// bytes) and must never be silently treated as absent — doing so is exactly how a transient
+/// read failure can cause `createWallet` to stomp a real, unreadable index with a fresh one.
+enum NativeWalletStoreError: Error, LocalizedError, CustomStringConvertible {
+  case keychainWrite(OSStatus)
+  case keychainRead(OSStatus)
+  case notFound(walletId: String)
+  case corrupted(String)
+  case permissionDenied(OSStatus)
+  case invalidWalletId(String)
+  case noDevicePasscode
+
+  var description: String {
+    switch self {
+    case .keychainWrite(let status): return "Keychain write failed (OSStatus \(status))"
+    case .keychainRead(let status): return "Keychain read failed (OSStatus \(status))"
+    case .notFound(let walletId): return walletId.isEmpty ? "Wallet not found" : "Wallet not found: \(walletId)"
+    case .corrupted(let detail): return "Wallet data is corrupted: \(detail)"
+    case .permissionDenied(let status): return "Permission denied (OSStatus \(status))"
+    case .invalidWalletId(let walletId): return "Invalid wallet id: \(walletId)"
+    case .noDevicePasscode: return "A device passcode must be set before creating or importing a wallet"
+    }
+  }
+
+  // `LocalizedError` conformance matters: expo-modules-core wraps any thrown error that is
+  // *not* an `Exception` in `UnexpectedException(error)`, whose `reason` is
+  // `error.localizedDescription` — not our `description`. Without this, every
+  // `NativeWalletStoreError` thrown across the bridge silently loses its message to JS.
+  var errorDescription: String? { description }
+
+  var code: String {
+    switch self {
+    case .notFound: return "ERR_WALLET_NOT_FOUND"
+    case .corrupted: return "ERR_WALLET_DATA_CORRUPTED"
+    case .permissionDenied: return "ERR_WALLET_PERMISSION_DENIED"
+    case .keychainWrite, .keychainRead: return "ERR_KEYCHAIN_IO"
+    case .invalidWalletId: return "ERR_INVALID_WALLET_ID"
+    case .noDevicePasscode: return "ERR_NO_DEVICE_PASSCODE"
+    }
+  }
+
+  /// Converts to a proper Expo `Exception` so `code`/`description` survive the bridge
+  /// (see the `errorDescription` note above) instead of being flattened by `UnexpectedException`.
+  var asException: Exception {
+    Exception(name: "NativeWalletStoreError", description: description, code: code)
+  }
+}
+
+/// Persists mnemonics in the iOS Keychain, gated by biometry-or-device-passcode
+/// (`kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` + `SecAccessControl`), plus a
+/// parallel ungated metadata store (walletId -> per-chain addresses) for read-only UI
+/// (address display, balance lookups) that shouldn't need a biometric prompt.
+///
+/// Deliberately does not use `react-native-keychain` or wallet-core's `StoredKey`
+/// keystore-JSON format — the mnemonic bytes are the only secret; wrapping them in an
+/// additional password-protected keystore would just relocate the secret to a password
+/// that itself needs identical OS-level gating, for no additional protection.
+enum NativeWalletStore {
+  private static let walletServicePrefix = "com.chainberry.vault.wallet."
+  private static let mnemonicAccount = "mnemonic"
+  private static let metadataService = "com.chainberry.vault.wallet-metadata"
+  private static let metadataAccount = "index"
+
+  /// Classifies a Keychain `OSStatus` into a typed error. `errSecItemNotFound` is handled
+  /// by each call site individually (it means different things for a read-that-defaults-to-
+  /// empty vs. a delete-that's-idempotent vs. a genuine not-found), so it's intentionally not
+  /// folded in here except as a fallback for callers that just want *a* not-found error.
+  private static func classify(_ status: OSStatus, walletId: String? = nil, isWrite: Bool = false) -> NativeWalletStoreError {
+    switch status {
+    case errSecItemNotFound:
+      return .notFound(walletId: walletId ?? "")
+    case errSecAuthFailed, errSecInteractionNotAllowed, errSecUserCanceled:
+      return .permissionDenied(status)
+    default:
+      return isWrite ? .keychainWrite(status) : .keychainRead(status)
+    }
+  }
+
+  /// Wallet ids are always internally generated as UUIDs (`UUID().uuidString`). Any
+  /// caller-supplied id is validated against that format before it's used to build a
+  /// Keychain service string, rejecting malformed/adversarial input up front.
+  static func validateWalletId(_ walletId: String) throws -> String {
+    guard UUID(uuidString: walletId) != nil else {
+      throw NativeWalletStoreError.invalidWalletId(walletId)
+    }
+    return walletId
+  }
+
+  // MARK: - Mnemonic (biometry/passcode gated)
+
+  static func saveMnemonic(_ mnemonic: String, walletId: String) throws {
+    var accessError: Unmanaged<CFError>?
+    guard let access = SecAccessControlCreateWithFlags(
+      nil,
+      kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
+      [.biometryCurrentSet, .or, .devicePasscode],
+      &accessError
+    ) else {
+      throw NativeWalletStoreError.noDevicePasscode
+    }
+
+    let service = walletServicePrefix + walletId
+    // Delete any existing item first: SecItemAdd fails on a duplicate primary key, and
+    // access control cannot be changed via SecItemUpdate — a fresh add is required.
+    // errSecItemNotFound (nothing to delete yet) is expected and fine; anything else means
+    // the slot may still be occupied, so surface it rather than attempting (and likely
+    // failing) the add anyway.
+    let deleteStatus = SecItemDelete([
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: mnemonicAccount,
+    ] as CFDictionary)
+    guard deleteStatus == errSecSuccess || deleteStatus == errSecItemNotFound else {
+      throw classify(deleteStatus, walletId: walletId, isWrite: true)
+    }
+
+    let addQuery: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: mnemonicAccount,
+      kSecValueData as String: Data(mnemonic.utf8),
+      kSecAttrAccessControl as String: access,
+    ]
+    let status = SecItemAdd(addQuery as CFDictionary, nil)
+    guard status == errSecSuccess else {
+      throw NativeWalletStoreError.keychainWrite(status)
+    }
+  }
+
+  /// Triggers the biometry/passcode prompt (via the supplied `LAContext`, so the caller
+  /// controls the prompt's reason string) and returns the mnemonic on success.
+  static func loadMnemonic(walletId: String, context: LAContext) throws -> String {
+    let query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: walletServicePrefix + walletId,
+      kSecAttrAccount as String: mnemonicAccount,
+      kSecReturnData as String: true,
+      kSecUseAuthenticationContext as String: context,
+    ]
+
+    var result: AnyObject?
+    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    guard status == errSecSuccess else {
+      throw classify(status, walletId: walletId)
+    }
+    guard let data = result as? Data, let mnemonic = String(data: data, encoding: .utf8) else {
+      throw NativeWalletStoreError.corrupted("stored mnemonic bytes are not valid UTF-8")
+    }
+    return mnemonic
+  }
+
+  /// Idempotent: deleting a wallet id that has no Keychain item is treated as success (there's
+  /// nothing left to delete), matching normal `deleteWallet` semantics. Any other failure
+  /// (e.g. an interaction-not-allowed/auth error) is surfaced rather than silently discarded.
+  static func deleteMnemonic(walletId: String) throws {
+    let status = SecItemDelete([
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: walletServicePrefix + walletId,
+      kSecAttrAccount as String: mnemonicAccount,
+    ] as CFDictionary)
+    guard status == errSecSuccess || status == errSecItemNotFound else {
+      throw classify(status, walletId: walletId, isWrite: true)
+    }
+  }
+
+  // MARK: - Metadata (ungated: walletId -> { chain: address })
+
+  /// Atomically replaces the metadata blob via `SecItemUpdate` when it already exists,
+  /// falling back to `SecItemAdd` only on the very first write. Unlike the mnemonic item,
+  /// the metadata item carries no `SecAccessControl`, so there's no access-control-change
+  /// obstacle to updating in place — this removes the delete-then-add race window entirely
+  /// (a crash between delete and add used to be able to lose the index outright).
+  static func saveMetadata(_ wallets: [String: [String: String]]) throws {
+    let data = try JSONSerialization.data(withJSONObject: wallets)
+    let baseQuery: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: metadataService,
+      kSecAttrAccount as String: metadataAccount,
+    ]
+
+    let updateStatus = SecItemUpdate(baseQuery as CFDictionary, [kSecValueData as String: data] as CFDictionary)
+    if updateStatus == errSecItemNotFound {
+      var addQuery = baseQuery
+      addQuery[kSecValueData as String] = data
+      addQuery[kSecAttrAccessible as String] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+      let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
+      guard addStatus == errSecSuccess else {
+        throw NativeWalletStoreError.keychainWrite(addStatus)
+      }
+      return
+    }
+    guard updateStatus == errSecSuccess else {
+      throw NativeWalletStoreError.keychainWrite(updateStatus)
+    }
+  }
+
+  /// Distinguishes "no metadata has ever been written" (legitimately empty — `errSecItemNotFound`)
+  /// from a genuine read/corruption failure, which now throws instead of being silently
+  /// masked as an empty map. Masking it was the root cause of the "transient read failure
+  /// followed by createWallet overwrites the index" scenario: a real failure here must abort
+  /// the caller, not look identical to "no wallets yet".
+  static func loadMetadata() throws -> [String: [String: String]] {
+    let query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: metadataService,
+      kSecAttrAccount as String: metadataAccount,
+      kSecReturnData as String: true,
+    ]
+    var result: AnyObject?
+    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    if status == errSecItemNotFound {
+      return [:]
+    }
+    guard status == errSecSuccess, let data = result as? Data else {
+      throw classify(status)
+    }
+    guard let obj = try? JSONSerialization.jsonObject(with: data) as? [String: [String: String]] else {
+      throw NativeWalletStoreError.corrupted("metadata JSON is unreadable")
+    }
+    return obj
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainberry/trust-wallet-core",
-  "version": "2.0.0",
+  "version": "2.5.0",
   "description": "Expo native module wrapping Trust Wallet Core for native-only HD wallet custody, address derivation, and transaction signing (Ethereum, BNB, Polygon, Solana, Tron, TON, Bitcoin, Bitcoin Cash, Litecoin, XRP) — mnemonic/private keys never cross the JS bridge",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -10,11 +10,12 @@
   },
   "files": [
     "src",
-    "ios/TrustWalletCoreModule.swift",
+    "ios",
     "android/src",
     "android/build.gradle",
+    "android/libs",
     "expo-module.config.json",
-    "TrustWalletCoreModule.podspec",
+    "ChainberryTrustWalletCoreModule.podspec",
     "README.md"
   ],
   "peerDependencies": {

package/src/index.ts

@@ -4,18 +4,24 @@ import { requireNativeModule } from "expo-modules-core";
  * Mnemonic/private-key material never crosses this boundary except `exportMnemonic` —
  * an explicit, biometric/passcode-gated backup flow. Every other function returns only
  * walletIds, addresses, or signed transaction bytes/hex; wallet storage and all signing
- * happen entirely inside the native module (see ios/TrustWalletCoreModule.swift,
- * android/.../TrustWalletCoreModule.kt).
+ * happen entirely inside the native module (see ios/ChainberryTrustWalletCoreModule.swift,
+ * android/.../ChainberryTrustWalletCoreModule.kt).
  */
 export type Chain =
   | "ethereum"
   | "bnb"
-  | "polygon" // shares Ethereum's secp256k1 key/address — same BIP44 path, no distinct derivation
+  | "polygon"   // shares Ethereum's secp256k1 key/address — same BIP44 path, no distinct derivation
+  | "avax"      // Avalanche C-Chain — EVM, same key derivation as Ethereum
+  | "base"      // Base — EVM L2, same key derivation as Ethereum
+  | "arbitrum"  // Arbitrum One — EVM L2, same key derivation as Ethereum
+  | "optimism"  // Optimism — EVM L2, same key derivation as Ethereum
+  | "sonic"     // Sonic — EVM, same key derivation as Ethereum
   | "solana"
   | "tron"
   | "ton"
   | "bitcoin"
-  | "bitcoincash" // address derivation only — sending is unsupported, see ChainSigner
+  | "bitcoincash"
+  | "dogecoin"
   | "litecoin"
   | "xrp";
 
@@ -32,15 +38,21 @@ export type SignResult = {
 const TrustWalletCore = requireNativeModule("TrustWalletCore");
 
 /** Generates a new mnemonic and persists it natively (biometry/passcode-gated).
- * strength 128 = 12 words, 256 = 24 words. */
-export async function createWallet(strength: 128 | 256 = 128, passphrase = ""): Promise<WalletSummary> {
-  return TrustWalletCore.createWallet(strength, passphrase);
+ * strength 128 = 12 words, 256 = 24 words. No BIP-39 passphrase support: signing always
+ * reconstructs the wallet from the mnemonic alone, so a caller-supplied passphrase here
+ * would derive addresses from a seed different from the one actually used to sign.
+ * `isTestnet` selects the address format for BTC/LTC/BCH (every other chain's address is
+ * identical on mainnet and testnet) — callers should pass `IS_TESTNET` from
+ * `@/constants/wallet-env`. */
+export async function createWallet(strength: 128 | 256 = 128, isTestnet = false): Promise<WalletSummary> {
+  return TrustWalletCore.createWallet(strength, isTestnet);
 }
 
 /** One-time mnemonic exposure from the caller — persisted natively immediately, never
- * retained in JS after this call returns. */
-export async function importWallet(mnemonic: string, passphrase = ""): Promise<WalletSummary> {
-  return TrustWalletCore.importWallet(mnemonic, passphrase);
+ * retained in JS after this call returns. No BIP-39 passphrase support (see `createWallet`).
+ * `isTestnet` — see `createWallet`. */
+export async function importWallet(mnemonic: string, isTestnet = false): Promise<WalletSummary> {
+  return TrustWalletCore.importWallet(mnemonic, isTestnet);
 }
 
 /** Reads only public metadata (walletId + addresses) — no biometric prompt. */
@@ -53,13 +65,16 @@ export async function deleteWallet(walletId: string): Promise<void> {
 }
 
 /** Triggers the native biometry/passcode prompt, then signs entirely in-process —
- * only signed transaction bytes/hex cross back. */
+ * only signed transaction bytes/hex cross back. `isTestnet` must match whatever
+ * `createWallet`/`importWallet` used for this wallet (see those for why) — pass
+ * `IS_TESTNET` from `@/constants/wallet-env`. */
 export async function signTransaction(
   walletId: string,
   chain: Chain,
   unsignedTx: Record<string, unknown>,
+  isTestnet = false,
 ): Promise<SignResult> {
-  return TrustWalletCore.signTransaction(walletId, chain, unsignedTx);
+  return TrustWalletCore.signTransaction(walletId, chain, unsignedTx, isTestnet);
 }
 
 /** The one sanctioned mnemonic exposure — explicit backup/reveal flow only, gated behind