@chainberry/trust-wallet-core 2.5.0 → 2.5.2

package/ios/ChainberryTrustWalletCoreModule.swift

@@ -10,12 +10,23 @@ public class ChainberryTrustWalletCoreModule: Module {
   public func definition() -> ModuleDefinition {
     Name("TrustWalletCore")
 
-    // strength 128 = 12 words, 256 = 24 words. Returns { walletId, addresses }.
+    // Runs once, right after module init, before any of the AsyncFunctions below can be reached
+    // from JS — so nothing can legitimately be mid-operation yet, which is exactly what makes a
+    // one-shot pass here sufficient (no lock/grace-period needed against an in-flight call). This
+    // is the actual crash-safety mechanism for an interrupted create/delete; see CONTEXT.md and
+    // docs/adr/0001. `reconcileOrphans` is non-throwing — never allowed to block or crash startup.
+    OnCreate {
+      NativeWalletStore.reconcileOrphans()
+    }
+
+    // strength 128 = 12 words, 256 = 24 words. Returns { walletId, addresses, isTestnet }.
     // 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.
+    // every other chain's address is the same on mainnet and testnet. This value is persisted
+    // as immutable per-wallet metadata (NativeWalletStore.WalletRecord) — signTransaction reads
+    // it back from there instead of accepting it as a parameter, so it can never drift.
     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")
@@ -28,7 +39,7 @@ public class ChainberryTrustWalletCoreModule: Module {
     }
 
     // One-time mnemonic exposure from JS, at import only — never retained after this call.
-    // Returns { walletId, addresses }. No BIP-39 passphrase support (see `createWallet`).
+    // Returns { walletId, addresses, isTestnet }. 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")
@@ -43,8 +54,8 @@ public class ChainberryTrustWalletCoreModule: Module {
     // 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]
+        return try NativeWalletStore.loadMetadata().map { walletId, record in
+          ["walletId": walletId, "addresses": record.addresses, "isTestnet": record.isTestnet]
         }
       } catch let e as NativeWalletStoreError {
         throw e.asException
@@ -55,23 +66,33 @@ public class ChainberryTrustWalletCoreModule: Module {
     // 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.
+    //
+    // Removes the metadata entry *before* the secret (Keychain item) — the reverse of the old
+    // ordering. If this is interrupted between the two steps, the wallet is already gone from
+    // `listWallets` and only an orphaned Keychain item is left behind, which the next app
+    // launch's reconciliation pass cleans up (see docs/adr/0001) — never a metadata record still
+    // pointing at a secret that's already gone.
     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
+      try await Self.withLifecycleLock(rejectIfBusy: false) {
+        do {
+          let id = try NativeWalletStore.validateWalletId(walletId)
+          _ = try await Self.authenticatedContext(reason: "Delete wallet")
+          var metadata = try NativeWalletStore.loadMetadata()
+          metadata.removeValue(forKey: id)
+          try NativeWalletStore.saveMetadata(metadata)
+          try NativeWalletStore.deleteMnemonic(walletId: id)
+        } 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
+    // Returns { signedTx, meta? }. Network mode (mainnet/testnet) is read from the wallet's own
+    // persisted record, not accepted as a parameter — see ChainSigner.key(for:) and
+    // NativeWalletStore.WalletRecord for why a caller-supplied value here could sign with the
+    // wrong key for BTC/LTC.
+    AsyncFunction("signTransaction") { (walletId: String, chain: String, unsignedTx: [String: Any]) async throws -> [String: Any] in
       do {
         let id = try NativeWalletStore.validateWalletId(walletId)
         let chainKey = try ChainKey(fromJs: chain)
@@ -81,6 +102,25 @@ public class ChainberryTrustWalletCoreModule: Module {
         guard let wallet = HDWallet(mnemonic: mnemonic, passphrase: "") else {
           throw Exception(name: "InvalidMnemonic", description: "Stored mnemonic failed validation")
         }
+        // Backfill any addresses that were missing when the wallet was first stored
+        // (e.g. chains added after the wallet was created). Runs silently after the
+        // biometric gate — no extra prompt needed.
+        var metadata = try NativeWalletStore.loadMetadata()
+        guard var record = metadata[id] else {
+          throw NativeWalletStoreError.notFound(walletId: id)
+        }
+        let isTestnet = record.isTestnet
+        var changed = false
+        for chain in ChainKey.allCases {
+          if record.addresses[chain.rawValue] == nil {
+            record.addresses[chain.rawValue] = ChainSigner.address(for: chain, wallet: wallet, isTestnet: isTestnet)
+            changed = true
+          }
+        }
+        if changed {
+          metadata[id] = record
+          try? NativeWalletStore.saveMetadata(metadata)
+        }
         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 }
@@ -102,13 +142,84 @@ public class ChainberryTrustWalletCoreModule: Module {
     }
   }
 
+  // MARK: - Lifecycle serialization (see docs/adr/0002)
+
+  /// Serializes create/import/delete against each other — a `Task`-based actor rather than
+  /// `NSLock`, since these calls `await` across the biometric prompt and holding an `NSLock`
+  /// across a suspension point (where Swift Concurrency may resume on a different underlying
+  /// thread) is unsafe.
+  private actor LifecycleLock {
+    private var locked = false
+    private var waiters: [CheckedContinuation<Void, Never>] = []
+
+    /// Non-blocking: returns `false` immediately if already held (used by create/import, which
+    /// reject rather than queue).
+    func tryAcquire() -> Bool {
+      guard !locked else { return false }
+      locked = true
+      return true
+    }
+
+    /// Blocking: waits until the lock is free, then acquires it (used by delete, which queues).
+    func acquire() async {
+      guard locked else {
+        locked = true
+        return
+      }
+      await withCheckedContinuation { waiters.append($0) }
+    }
+
+    /// Hands ownership directly to the next waiter rather than freeing the lock and letting
+    /// every waiter race a fresh `tryAcquire`/`acquire`.
+    func release() {
+      if !waiters.isEmpty {
+        waiters.removeFirst().resume()
+      } else {
+        locked = false
+      }
+    }
+  }
+
+  private static let lifecycleLock = LifecycleLock()
+
+  /// Serializes `body` — including the biometric/passcode prompt, not just the store writes —
+  /// against every other lifecycle-mutating call, so at most one is ever touching the shared
+  /// metadata store at a time (see docs/adr/0002). Also forecloses a second, separate bug: two
+  /// concurrent `LAContext` evaluations racing each other.
+  ///
+  /// `rejectIfBusy` chooses the policy for a caller that finds the lock already held:
+  /// `createWallet`/`importWallet` reject immediately (`ERR_WALLET_OPERATION_IN_PROGRESS`) so a
+  /// double-tap can never mint two wallets; `deleteWallet` queues instead, since two distinct
+  /// deletes are both legitimate and should both eventually happen.
+  private static func withLifecycleLock<T>(rejectIfBusy: Bool, _ body: () async throws -> T) async throws -> T {
+    if rejectIfBusy {
+      guard await lifecycleLock.tryAcquire() else {
+        throw Exception(
+          name: "OperationInProgress",
+          description: "Another wallet operation is already in progress",
+          code: "ERR_WALLET_OPERATION_IN_PROGRESS"
+        )
+      }
+    } else {
+      await lifecycleLock.acquire()
+    }
+    do {
+      let result = try await body()
+      await lifecycleLock.release()
+      return result
+    } catch {
+      await lifecycleLock.release()
+      throw error
+    }
+  }
+
   // 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)
+    let message = try ChainSigner.buildSummary(chain: chain, unsignedTx: unsignedTx)
     try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
       DispatchQueue.main.async {
         let scene = UIApplication.shared.connectedScenes
@@ -143,7 +254,7 @@ public class ChainberryTrustWalletCoreModule: Module {
     try NativeWalletStore.saveMnemonic(wallet.mnemonic, walletId: walletId)
     do {
       var metadata = try NativeWalletStore.loadMetadata()
-      metadata[walletId] = addresses
+      metadata[walletId] = NativeWalletStore.WalletRecord(isTestnet: isTestnet, addresses: addresses)
       try NativeWalletStore.saveMetadata(metadata)
     } catch {
       // The mnemonic is already persisted but has no metadata pointer — compensate by
@@ -154,7 +265,7 @@ public class ChainberryTrustWalletCoreModule: Module {
       throw error
     }
 
-    return ["walletId": walletId, "addresses": addresses]
+    return ["walletId": walletId, "addresses": addresses, "isTestnet": isTestnet]
   }
 
   /// Prompts biometry-or-device-passcode via `.deviceOwnerAuthentication` (Apple's

package/ios/ConformanceTests/AddressDerivationConformanceTests.swift

@@ -0,0 +1,39 @@
+import XCTest
+import WalletCore
+
+// iOS companion to android/src/androidTest/.../AddressDerivationConformanceTest.kt.
+// Verifies that HDWallet.getAddressForCoin produces the expected address for every
+// chain under WalletCore 4.1.19 (the pinned version).
+//
+// The test mnemonic is the BIP39 standard test vector — never use with real funds.
+//
+// How to run:
+//   xcodebuild test -workspace ios/vault.xcworkspace -scheme WalletConformanceTests \
+//     -destination 'platform=iOS Simulator,name=iPhone 17'
+final class AddressDerivationConformanceTests: XCTestCase {
+
+  static let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+  // All addresses confirmed against WalletCore 4.1.19 on-device (Android instrumented test
+  // 2026-08-27; iOS confirmed via this test suite). ETH/BNB/POL share CoinType.ethereum.
+  static let verified: [(coin: CoinType, chain: String, expected: String)] = [
+    (.ethereum,    "ethereum",    "0x9858EfFD232B4033E47d90003D41EC34EcaEda94"),
+    (.smartChain,  "bnb",         "0x9858EfFD232B4033E47d90003D41EC34EcaEda94"),
+    (.ethereum,    "polygon",     "0x9858EfFD232B4033E47d90003D41EC34EcaEda94"),
+    (.bitcoin,     "bitcoin",     "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu"),
+    (.litecoin,    "litecoin",    "ltc1qjmxnz78nmc8nq77wuxh25n2es7rzm5c2rkk4wh"),
+    (.xrp,         "xrp",         "rHsMGQEkVNJmpGWs8XUBoTBiAAbwxZN5v3"),
+    (.tron,        "tron",        "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH"),
+    (.ton,         "ton",         "UQAzWZa6nM5mJev91wGc7VCSfBoIsYRqKJpV78N8Add9-RKY"),
+    (.solana,      "solana",      "GjJyeC1r2RgkuoCWMyPYkCWSGSGLcz266EaAkLA27AhL"),
+    (.bitcoinCash, "bitcoincash", "bitcoincash:qqyx49mu0kkn9ftfj6hje6g2wfer34yfnq5tahq3q6"),
+  ]
+
+  func testVerifiedAddressesMatch() {
+    let wallet = HDWallet(mnemonic: Self.mnemonic, passphrase: "")!
+    for v in Self.verified {
+      let actual = wallet.getAddressForCoin(coin: v.coin)
+      XCTAssertEqual(actual, v.expected, "chain '\(v.chain)': derived '\(actual)' ≠ expected '\(v.expected)'")
+    }
+  }
+}

package/ios/ConformanceTests/SigningConformanceTests.swift

@@ -0,0 +1,292 @@
+import XCTest
+import WalletCore
+
+// Mirrors Android's SigningConformanceTest.kt: reads conformance/signing-vectors.json and asserts
+// iOS WalletCore 4.1.19 produces byte-for-byte identical signed transactions. Covers every status:
+//   "verified"                  — assert output == expectedSignedTx
+//   "verified-non-deterministic"— assert signing succeeds and output is structurally valid (TON)
+//   "verified-android-only"     — run the same input on iOS to confirm cross-platform parity (TRX)
+//
+// Add this file to an XCTest target in vault.xcworkspace that links WalletCore.xcframework.
+class SigningConformanceTests: XCTestCase {
+
+  private struct SigningVector: Decodable {
+    let chain: String
+    let status: String
+    let unsignedTx: [String: JSONValue]
+    let expectedSignedTx: String?
+  }
+
+  private struct FixtureFile: Decodable {
+    let testMnemonic: String
+    let testPassphrase: String
+    let signingVectors: [SigningVector]
+  }
+
+  // Minimal JSON value type so unsignedTx can be decoded without knowing its shape up front.
+  private enum JSONValue: Decodable {
+    case string(String), int(Int), double(Double), bool(Bool), array([JSONValue]), object([String: JSONValue]), null
+    init(from decoder: Decoder) throws {
+      let c = try decoder.singleValueContainer()
+      if c.decodeNil() { self = .null }
+      else if let v = try? c.decode(Bool.self) { self = .bool(v) }
+      else if let v = try? c.decode(Int.self) { self = .int(v) }
+      else if let v = try? c.decode(Double.self) { self = .double(v) }
+      else if let v = try? c.decode(String.self) { self = .string(v) }
+      else if let v = try? c.decode([JSONValue].self) { self = .array(v) }
+      else { self = .object(try c.decode([String: JSONValue].self)) }
+    }
+    var string: String? { if case .string(let s) = self { return s }; return nil }
+    var int: Int? { if case .int(let i) = self { return i }; return nil }
+    var object: [String: JSONValue]? { if case .object(let o) = self { return o }; return nil }
+    var array: [JSONValue]? { if case .array(let a) = self { return a }; return nil }
+  }
+
+  private func loadFixture() throws -> FixtureFile {
+    guard let url = Bundle(for: SigningConformanceTests.self)
+      .url(forResource: "signing-vectors", withExtension: "json") else {
+      throw XCTSkip("signing-vectors.json not found in test bundle")
+    }
+    return try JSONDecoder().decode(FixtureFile.self, from: Data(contentsOf: url))
+  }
+
+  private var wallet: HDWallet!
+
+  override func setUpWithError() throws {
+    let fixture = try loadFixture()
+    guard let w = HDWallet(mnemonic: fixture.testMnemonic, passphrase: fixture.testPassphrase) else {
+      throw XCTSkip("HDWallet init failed")
+    }
+    wallet = w
+  }
+
+  // MARK: - Per-chain tests
+
+  func testEthereum() throws { try runVector(chain: "ethereum") }
+  func testPolygon()  throws { try runVector(chain: "polygon") }
+  func testBitcoin()  throws { try runVector(chain: "bitcoin") }
+  func testLitecoin() throws { try runVector(chain: "litecoin") }
+  func testXrp()      throws { try runVector(chain: "xrp") }
+  func testTron()     throws { try runVector(chain: "tron") }
+  func testSolana()   throws { try runVector(chain: "solana") }
+  func testTon()      throws { try runVector(chain: "ton") }
+
+  // MARK: - Dispatch
+
+  private func runVector(chain: String) throws {
+    let fixture = try loadFixture()
+    guard let v = fixture.signingVectors.first(where: { $0.chain == chain }) else {
+      throw XCTSkip("No vector for chain '\(chain)'")
+    }
+    let tx = v.unsignedTx
+    switch chain {
+    case "ethereum", "polygon": try assertEvm(v, tx: tx)
+    case "bitcoin", "litecoin": try assertUtxo(v, tx: tx)
+    case "xrp":    try assertXrp(v, tx: tx)
+    case "tron":   try assertTron(v, tx: tx)
+    case "solana": try assertSolana(v, tx: tx)
+    case "ton":    try assertTon(v, tx: tx)
+    default: XCTFail("No signing impl for chain '\(chain)'")
+    }
+  }
+
+  // MARK: - EVM
+
+  private func assertEvm(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let coin: CoinType = .ethereum
+    let pk = wallet.getKeyForCoin(coin: coin)
+    guard let to      = tx["to"]?.string,
+          let nonce   = tx["nonce"]?.int,
+          let gasLim  = tx["gasLimitHex"]?.string,
+          let chainId = tx["chainId"]?.int else {
+      XCTFail("Missing EVM params"); return
+    }
+    let valueHex = tx["valueHex"]?.string ?? "0"
+    var input = EthereumSigningInput()
+    input.chainID    = BigIntHelper(chainId).toMinimal()
+    input.nonce      = BigIntHelper(nonce).toMinimal()
+    input.gasLimit   = Data(hexString: gasLim.padEven())!
+    input.toAddress  = to
+    input.privateKey = pk.data
+    var transfer = EthereumTransaction.Transfer()
+    transfer.amount = Data(hexString: valueHex.padEven()) ?? Data([0])
+    var etx = EthereumTransaction(); etx.transfer = transfer
+    input.transaction = etx
+    if let gp = tx["gasPriceHex"]?.string {
+      input.gasPrice = Data(hexString: gp.padEven())!
+    } else if let mf = tx["maxFeePerGasHex"]?.string,
+              let pf = tx["maxPriorityFeePerGasHex"]?.string {
+      input.txMode = .enveloped
+      input.maxFeePerGas         = Data(hexString: mf.padEven())!
+      input.maxInclusionFeePerGas = Data(hexString: pf.padEven())!
+    }
+    let out: EthereumSigningOutput = AnySigner.sign(input: input, coin: coin)
+    XCTAssertEqual(out.error, .ok, "EVM signing error: \(out.errorMessage)")
+    let signed = "0x" + out.encoded.hexString
+    if v.status == "verified", let expected = v.expectedSignedTx {
+      XCTAssertEqual(signed, expected, "chain '\(v.chain)': signed tx mismatch")
+    }
+  }
+
+  // MARK: - UTXO (BTC / LTC)
+
+  private func assertUtxo(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let coin: CoinType = v.chain == "litecoin" ? .litecoin : .bitcoin
+    let pk = wallet.getKeyForCoin(coin: coin)
+    guard let toAddress     = tx["toAddress"]?.string,
+          let changeAddress = tx["changeAddress"]?.string,
+          let sendSats      = tx["sendAmountSats"]?.string.flatMap(Int64.init),
+          let spbNum        = tx["satsPerByte"]?.int,
+          let inputArr      = tx["inputs"]?.array else {
+      XCTFail("Missing UTXO params"); return
+    }
+    var input = BitcoinSigningInput()
+    input.hashType      = BitcoinScript.hashTypeForCoin(coinType: coin)
+    input.amount        = sendSats
+    input.byteFee       = Int64(spbNum)
+    input.toAddress     = toAddress
+    input.changeAddress = changeAddress
+    input.useMaxAmount  = false
+    input.coinType      = coin.rawValue
+    input.privateKey    = [pk.data]
+    input.utxo = inputArr.compactMap { entry -> BitcoinUnspentTransaction? in
+      guard let obj      = entry.object,
+            let txId     = obj["txIdHex"]?.string,
+            let vout     = obj["vout"]?.int,
+            let amt      = obj["amountSats"]?.string.flatMap(Int64.init),
+            let script   = obj["scriptPubKeyHex"]?.string,
+            let scriptData = Data(hexString: script),
+            var txIdData   = Data(hexString: txId) else { return nil }
+      txIdData.reverse()
+      var op = BitcoinOutPoint(); op.hash = txIdData; op.index = UInt32(vout)
+      var utxo = BitcoinUnspentTransaction()
+      utxo.outPoint = op; utxo.amount = amt; utxo.script = scriptData
+      return utxo
+    }
+    let out: BitcoinSigningOutput = AnySigner.sign(input: input, coin: coin)
+    XCTAssertEqual(out.error, .ok, "UTXO signing error: \(out.errorMessage)")
+    if v.status == "verified", let expected = v.expectedSignedTx {
+      XCTAssertEqual(out.encoded.hexString, expected, "chain '\(v.chain)': signed tx mismatch")
+    }
+  }
+
+  // MARK: - XRP
+
+  private func assertXrp(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let pk = wallet.getKeyForCoin(coin: .xrp)
+    guard let account  = tx["Account"]?.string,
+          let dest     = tx["Destination"]?.string,
+          let amount   = tx["Amount"]?.string.flatMap(Int64.init),
+          let fee      = tx["Fee"]?.string.flatMap(Int64.init),
+          let sequence = tx["Sequence"]?.int else {
+      XCTFail("Missing XRP params"); return
+    }
+    var payment = RippleOperationPayment()
+    payment.amount = amount; payment.destination = dest
+    var input = RippleSigningInput()
+    input.privateKey = pk.data; input.account = account
+    input.fee = fee; input.sequence = Int32(sequence)
+    if let lls = tx["LastLedgerSequence"]?.int { input.lastLedgerSequence = Int32(lls) }
+    input.opPayment = payment
+    let out: RippleSigningOutput = AnySigner.sign(input: input, coin: .xrp)
+    XCTAssertEqual(out.error, .ok, "XRP signing error: \(out.errorMessage)")
+    if v.status == "verified", let expected = v.expectedSignedTx {
+      XCTAssertEqual(out.encoded.hexString, expected, "chain 'xrp': signed tx mismatch")
+    }
+  }
+
+  // MARK: - TRX
+
+  private func assertTron(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let pk = wallet.getKeyForCoin(coin: .tron)
+    guard let txID = tx["txID"]?.string else { XCTFail("Missing TRX txID"); return }
+    var input = TronSigningInput()
+    input.privateKey = pk.data
+    input.txID = txID
+    let out: TronSigningOutput = AnySigner.sign(input: input, coin: .tron)
+    XCTAssertEqual(out.error, .ok, "TRX signing error: \(out.errorMessage)")
+    let signatureHex = out.signature.hexString
+    XCTAssertFalse(signatureHex.isEmpty, "TRX: empty signature")
+    // verified-android-only: same private key + same digest → same ECDSA sig — mismatch is a real bug.
+    if let expected = v.expectedSignedTx,
+       let data = expected.data(using: .utf8),
+       let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+       let sigs = json["signature"] as? [String],
+       let androidSig = sigs.first {
+      XCTAssertEqual(signatureHex, androidSig,
+        "TRX: iOS signature differs from Android — same digest + key must produce same ECDSA sig")
+    }
+  }
+
+  // MARK: - Solana
+
+  private func assertSolana(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let pk = wallet.getKeyForCoin(coin: .solana)
+    guard let b64 = tx["unsignedTxBase64"]?.string,
+          let txBytes = Data(base64Encoded: b64) else {
+      XCTFail("Missing/invalid Solana unsignedTxBase64"); return
+    }
+    let decoded = TransactionDecoder.decode(coinType: .solana, encodedTx: txBytes)
+    let decodedOut = try SolanaDecodingTransactionOutput(serializedBytes: decoded)
+    XCTAssertEqual(decodedOut.error, .ok, "SOL decode error: \(decodedOut.errorMessage)")
+    let blockhash = decodedOut.transaction.legacy.recentBlockhash
+    let keys = DataVector(); keys.add(data: pk.data)
+    let signedBytes = SolanaTransaction.updateBlockhashAndSign(
+      encodedTx: b64, recentBlockhash: blockhash, privateKeys: keys)
+    let signedOut = try SolanaSigningOutput(serializedBytes: signedBytes)
+    XCTAssertEqual(signedOut.error, .ok, "SOL signing error: \(signedOut.errorMessage)")
+    if v.status == "verified", let expected = v.expectedSignedTx {
+      XCTAssertEqual(signedOut.encoded, expected, "chain 'solana': signed tx mismatch")
+    }
+  }
+
+  // MARK: - TON (non-deterministic — verify structure only)
+
+  private func assertTon(_ v: SigningVector, tx: [String: JSONValue]) throws {
+    let pk = wallet.getKeyForCoin(coin: .ton)
+    guard let toAddress = tx["toAddress"]?.string,
+          let amountStr = tx["amount"]?.string,
+          let nanotons  = UInt64(amountStr),
+          let seqno     = tx["seqno"]?.int else {
+      XCTFail("Missing TON params"); return
+    }
+    var transfer = TheOpenNetworkTransfer()
+    transfer.dest   = toAddress
+    transfer.amount = nanotons
+    transfer.mode   = UInt32(
+      TheOpenNetworkSendMode.payFeesSeparately.rawValue |
+      TheOpenNetworkSendMode.ignoreActionPhaseErrors.rawValue)
+    transfer.bounceable = true
+    if let memo = tx["memoId"]?.string { transfer.comment = memo }
+    var input = TheOpenNetworkSigningInput()
+    input.privateKey     = pk.data
+    input.walletVersion  = .walletV4R2
+    input.sequenceNumber = UInt32(seqno)
+    input.expireAt       = UInt32(Date().timeIntervalSince1970) + 600
+    input.messages       = [transfer]
+    let out: TheOpenNetworkSigningOutput = AnySigner.sign(input: input, coin: .ton)
+    XCTAssertEqual(out.error, .ok, "TON signing error: \(out.errorMessage)")
+    // Non-deterministic due to wall-clock expireAt — check well-formed BOC and 32-byte hash only.
+    XCTAssertTrue(out.encoded.hasPrefix("te6cc"),
+      "TON: unexpected BOC prefix in '\(out.encoded)'")
+    XCTAssertEqual(out.hash.count, 32,
+      "TON: txHash should be 32 bytes, got \(out.hash.count)")
+  }
+}
+
+// MARK: - Helpers
+
+private extension String {
+  func padEven() -> String { count % 2 == 0 ? self : "0" + self }
+}
+
+private struct BigIntHelper {
+  let value: Int
+  init(_ v: Int) { value = v }
+  func toMinimal() -> Data {
+    guard value > 0 else { return Data([0]) }
+    var v = value; var bytes: [UInt8] = []
+    while v > 0 { bytes.insert(UInt8(v & 0xFF), at: 0); v >>= 8 }
+    return Data(bytes)
+  }
+}

package/ios/NativeWalletStore.swift

@@ -173,15 +173,24 @@ enum NativeWalletStore {
     }
   }
 
-  // MARK: - Metadata (ungated: walletId -> { chain: address })
+  // MARK: - Metadata (ungated: walletId -> { isTestnet, addresses: { chain: address } })
+
+  /// A wallet's network mode is fixed at creation time (`ChainberryTrustWalletCoreModule
+  /// .persistNewWallet`) and never changes thereafter — `isTestnet` is the authoritative value
+  /// `signTransaction` must derive/sign with, replacing the old pattern of accepting it fresh as
+  /// a parameter on every call.
+  struct WalletRecord: Codable {
+    var isTestnet: Bool
+    var addresses: [String: String]
+  }
 
   /// 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)
+  static func saveMetadata(_ wallets: [String: WalletRecord]) throws {
+    let data = try JSONEncoder().encode(wallets)
     let baseQuery: [String: Any] = [
       kSecClass as String: kSecClassGenericPassword,
       kSecAttrService as String: metadataService,
@@ -208,8 +217,10 @@ enum NativeWalletStore {
   /// 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]] {
+  /// the caller, not look identical to "no wallets yet". Data written by a pre-migration build
+  /// (walletId -> {chain: address} with no isTestnet/addresses wrapper) fails to decode and is
+  /// treated the same as any other corruption — there is no legacy-shape fallback.
+  static func loadMetadata() throws -> [String: WalletRecord] {
     let query: [String: Any] = [
       kSecClass as String: kSecClassGenericPassword,
       kSecAttrService as String: metadataService,
@@ -224,9 +235,65 @@ enum NativeWalletStore {
     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 {
+    guard let obj = try? JSONDecoder().decode([String: WalletRecord].self, from: data) else {
       throw NativeWalletStoreError.corrupted("metadata JSON is unreadable")
     }
     return obj
   }
+
+  // MARK: - Reconciliation (see CONTEXT.md "orphan"/"reconciliation pass", docs/adr/0001)
+
+  /// Runs once at module init (see `TrustWalletCoreModule`'s `OnCreate`), before the JS layer can
+  /// issue its first `createWallet`/`importWallet`/`deleteWallet` call — the actual source of
+  /// crash-safety for an interrupted create or delete, not the in-call rollback in
+  /// `persistNewWallet`. Finds every Keychain item under `walletServicePrefix` with no matching
+  /// metadata entry and deletes it.
+  ///
+  /// Enumeration requires listing *every* generic-password item (`kSecMatchLimitAll`) — the
+  /// Keychain has no service-prefix query — and filtering client-side; this is safe today because
+  /// nothing else in this app touches the Keychain directly (see docs/adr/0001). If that ever
+  /// changes, this filter must stay airtight or it risks touching an unrelated item.
+  ///
+  /// Best-effort and never throws: any failure here is logged and skipped, since a broken
+  /// reconciliation pass must never become "the app won't launch." A metadata entry with no
+  /// matching Keychain item (the reverse shape — a "zombie") is deliberately left untouched here;
+  /// see `.notFound` and docs/adr/0001 for why.
+  static func reconcileOrphans() {
+    let liveIds: Set<String>
+    do {
+      liveIds = Set(try loadMetadata().keys)
+    } catch {
+      NSLog("[NativeWalletStore] reconciliation: failed to load metadata, skipping this pass entirely: \(error)")
+      return
+    }
+
+    let query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecMatchLimit as String: kSecMatchLimitAll,
+      kSecReturnAttributes as String: true,
+    ]
+    var result: AnyObject?
+    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    guard status == errSecSuccess || status == errSecItemNotFound else {
+      NSLog("[NativeWalletStore] reconciliation: failed to enumerate Keychain items (OSStatus \(status))")
+      return
+    }
+    let items = (result as? [[String: Any]]) ?? []
+
+    for item in items {
+      guard let service = item[kSecAttrService as String] as? String,
+            service.hasPrefix(walletServicePrefix) else { continue }
+      let walletId = String(service.dropFirst(walletServicePrefix.count))
+      guard !liveIds.contains(walletId) else { continue }
+
+      let deleteStatus = SecItemDelete([
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: service,
+        kSecAttrAccount as String: mnemonicAccount,
+      ] as CFDictionary)
+      if deleteStatus != errSecSuccess && deleteStatus != errSecItemNotFound {
+        NSLog("[NativeWalletStore] reconciliation: failed to delete orphaned item for \(walletId) (OSStatus \(deleteStatus))")
+      }
+    }
+  }
 }