@chainberry/trust-wallet-core 1.0.2 → 2.5.0

package/{TrustWalletCoreModule.podspec → ChainberryTrustWalletCoreModule.podspec}

@@ -3,7 +3,7 @@ require 'json'
 package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 
 Pod::Spec.new do |s|
-  s.name           = 'TrustWalletCoreModule'
+  s.name           = 'ChainberryTrustWalletCoreModule'
   s.version        = package['version']
   s.summary        = package['description']
   s.description    = s.summary
@@ -17,5 +17,5 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/**/*.{h,m,mm,swift}'
 
   s.dependency 'ExpoModulesCore'
-  s.dependency 'TrustWalletCore'
+  s.dependency 'TrustWalletCore', '4.1.19'
 end

package/README.md

@@ -2,7 +2,7 @@
 
 Expo native module wrapping [Trust Wallet Core](https://github.com/trustwallet/wallet-core) for HD wallet generation, address derivation, and transaction signing. Runs the real native library (Kotlin/JNI on Android, Swift on iOS) — not the WASM build, so it works fine under Hermes.
 
-Supported coins: Ethereum, Solana, BNB Smart Chain (see `SupportedCoin`).
+Supported chains: Ethereum, BNB Smart Chain, Polygon, Solana, Tron, TON, Bitcoin, Bitcoin Cash (address derivation only — see Security model), Litecoin, XRP (see `Chain`).
 
 ## Installation
 
@@ -12,53 +12,61 @@ npx expo install @chainberry/trust-wallet-core
 
 This is an Expo config plugin module with native Android/iOS code, so it requires a development build (`expo prebuild` / EAS Build) — it will not work in Expo Go.
 
-### Android: GitHub Packages authentication required
+### Android: no GitHub credentials needed
 
-Trust Wallet Core's Android artifact is published to GitHub Packages, which requires authentication even though the package itself is public. Without credentials, `./gradlew` will fail to resolve `com.trustwallet:wallet-core`.
+Trust Wallet Core's Android artifact is only published to GitHub Packages, which requires authentication even though the package itself is public. To avoid making that a requirement for every dev/CI machine, `com.trustwallet:wallet-core` and its `wallet-core-proto` dependency are vendored locally as a plain Maven repo in `android/libs/` — `android/build.gradle` resolves from there first, so a normal `./gradlew` build needs no credentials at all. See `android/libs/README.md` for how it's kept up to date.
 
-Set up **one** of:
-
-```sh
-# Env vars (CI / one-off terminal)
-export GITHUB_ACTOR=your-github-username
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxx   # classic PAT, read:packages scope only
-```
-
-or add to `~/.gradle/gradle.properties` (permanent local dev setup):
-
-```properties
-gpr.user=your-github-username
-gpr.key=ghp_xxxxxxxxxxxx
-```
-
-Generate a token at github.com/settings/tokens → "classic" → check `read:packages`.
+GitHub Packages auth is still needed (via `GITHUB_ACTOR`/`GITHUB_TOKEN` env vars or `gpr.user`/`gpr.key` in `~/.gradle/gradle.properties`) only when bumping the pinned wallet-core version — see `android/libs/download.sh`.
 
 ### iOS
 
-`WalletCore` is pulled in via CocoaPods (`s.dependency 'TrustWalletCore'`) — no extra auth needed, `pod install` handles it.
+`WalletCore` is pulled in via CocoaPods (`s.dependency 'TrustWalletCore'`) — no extra auth needed, `pod install` handles it. Biometric/passcode gating uses `LocalAuthentication` (system framework, no extra dependency).
+
+Android biometric gating additionally pulls in `androidx.biometric:biometric:1.1.0`.
 
 ## Usage
 
 ```ts
-import { generateWallet, restoreWallet, getAddressForCoin } from "@chainberry/trust-wallet-core";
+import { createWallet, importWallet, signTransaction, exportMnemonic } from "@chainberry/trust-wallet-core";
 
-const { mnemonic, wallets } = await generateWallet(); // 128-bit / 12-word by default
-// wallets: { ethereum: "0x...", solana: "...", bnb: "0x..." }
+const { walletId, addresses } = await createWallet(); // 128-bit / 12-word by default
+// addresses: { ethereum: "0x...", solana: "...", bnb: "0x...", bitcoin: "...", ... }
 
-const restored = await restoreWallet(mnemonic);
+const restored = await importWallet(mnemonic);
 
-const { address, privateKey } = await getAddressForCoin(mnemonic, "ethereum");
+// Triggers a native biometry/passcode prompt; only signed tx bytes/hex cross back to JS.
+const { signedTx } = await signTransaction(walletId, "ethereum", unsignedTx);
+
+// Explicit backup flow only — biometry/passcode gated.
+const mnemonic = await exportMnemonic(walletId);
 ```
 
 ## API
 
-- `generateWallet(strength = 128, passphrase = "")` — creates a new BIP-39 mnemonic (128 = 12 words, 256 = 24 words) and returns it along with the derived address for every supported coin.
-- `restoreWallet(mnemonic, passphrase = "")` — validates an existing mnemonic and returns the same shape as `generateWallet`. Throws if the mnemonic is invalid.
-- `getAddressForCoin(mnemonic, coin, passphrase = "")` — derives `{ address, privateKey }` for a single coin (`"ethereum" | "solana" | "bnb"`).
+- `createWallet(strength = 128)` — generates a new BIP-39 mnemonic and persists it natively (Keychain on iOS / Keystore-backed file on Android, biometry-or-passcode gated). Returns `{ walletId, addresses }` — the mnemonic itself never leaves native code. No BIP-39 passphrase support: `signTransaction` always reconstructs the wallet with an empty passphrase, so a caller-supplied one would derive addresses from a seed different from the one actually used to sign.
+- `importWallet(mnemonic)` — validates and persists an existing mnemonic the same way. The `mnemonic` argument is a one-time exposure from the caller (e.g. a text-entry backup-restore screen); discard your own copy immediately after this call resolves.
+- `listWallets()` — returns `{ walletId, addresses }[]` for every persisted wallet, reading only the ungated metadata store. No biometric prompt.
+- `deleteWallet(walletId)` — removes the wallet's native key material and metadata entry. Irreversible; not biometric-gated (deleting reveals nothing, so this is a UX confirmation concern, not a key-secrecy one).
+- `signTransaction(walletId, chain, unsignedTx)` — triggers a native biometry/passcode prompt, then derives the key and signs entirely inside native code. Returns `{ signedTx, meta? }`; `meta` currently only carries TON's `txHash`.
+- `exportMnemonic(walletId)` — the one sanctioned mnemonic exposure. Biometry/passcode gated. Use only for an explicit "reveal recovery phrase" backup screen; don't hold the result in app state beyond that screen's lifetime.
+
+## Security model
+
+Mnemonic and derived private keys are generated, persisted, and used for signing entirely inside this module's native code (Swift/Kotlin) — they are never serialized back across the JS bridge, with the single exception of `exportMnemonic`'s explicit backup flow. This is a deliberate change from this module's earlier version, which returned raw private keys to JS on every address derivation; that let a compromised/malicious JS dependency, an attached JS debugger, or a JS-heap memory dump read wallet secrets in full. Now the JS runtime never holds them at all.
+
+Storage: one biometry-or-passcode-gated secret per wallet (`SecAccessControl` + iOS Keychain; an Android Keystore AES key gating an encrypted on-disk file), plus a separate, ungated metadata entry (`walletId` → addresses) for read-only UI that shouldn't need a biometric prompt just to show an address or balance.
+
+**Android hardware backing is best-effort, not guaranteed.** Key creation requests StrongBox first (API 28+), falling back to a plain Keystore key (which Keymaster backs with a TEE on virtually all real devices, but which can be software-only on an emulator or a device with no secure hardware at all) on `StrongBoxUnavailableException` or below API 28. The actual security level achieved is verified via `KeyInfo` right after creation and logged (`NativeWalletStore` logcat tag) — a software-only key is tolerated rather than blocking wallet creation, so this is a best-effort hardening measure, not an enforced guarantee. Don't assume every wallet on every device is hardware-backed; check the logs on a specific device/build if that matters for your threat model.
+
+Bitcoin Cash is derivation-only: sending BCH is unsupported both here and upstream (`chainberry-wallet`'s self-custody transaction preparation has no BCH case), so this module only derives its address.
+
+Both platforms pin **Trust Wallet Core 4.1.19** (`com.trustwallet:wallet-core:4.1.19` in `android/build.gradle`; `s.dependency 'TrustWalletCore', '4.1.19'` in the podspec).
+
+**Address derivation is verified for all 10 chains** in `conformance/address-derivation-vectors.json`, asserted by the Android instrumented test (`src/androidTest/.../AddressDerivationConformanceTest.kt`; run via `./gradlew connectedDebugAndroidTest`). Methodology: real on-device 4.1.19 addresses were harvested from the instrumented test running on an emulator, cross-checked against an independent derivation via the WASM build (`@trustwallet/wallet-core` 3.3.3, run standalone in Node — a different upstream release than the pinned 4.1.19, used only as a second data point); on-device 4.1.19 is authoritative wherever the two disagree, since that's what the app actually ships. They agreed on 6 of 7 previously-pending chains exactly; `ton` disagreed only in address-flag encoding (bounceable vs. non-bounceable — same underlying key/hash, see that fixture entry's `_note`). This same run also caught a real bug: the Ethereum/BNB/Polygon address that had been marked `"verified"` since before this pass was actually wrong — the instrumented test that should have caught it had never successfully executed (two pre-existing bugs: `coin.name()` didn't compile against this Kotlin binding, and no `testInstrumentationRunner` was configured, so `connectedAndroidTest` silently ran "0 tests" instead of failing). Both are fixed now; see the test file's header comment for details.
 
-## Security note
+**Byte-for-byte signing output is verified for 8 of 9 signable chains** in `conformance/signing-vectors.json`, asserted by `src/androidTest/.../SigningConformanceTest.kt`. Each vector calls `ChainSigner.sign()` — the same call path production code uses — with a fixed, deterministic (not necessarily broadcast-valid) unsigned tx. `ton` is verified but *not* byte-exact-asserted: `signTon()` embeds a wall-clock `expireAt` into the signed payload, so its output legitimately differs every run — the test instead checks the output is a well-formed signed BOC. `bitcoincash` has no signing vector (sending is unsupported, see above).
 
-`getAddressForCoin` returns the raw private key as hex to JS. That's a deliberate tradeoff for this module — it does no key storage or signing orchestration itself, it only derives keys. Callers are responsible for how the mnemonic and private keys are held, encrypted at rest, and cleared from memory. Don't treat this module as a secure enclave; it isn't one.
+**iOS gap — not closed by this pass.** No Swift/Xcode toolchain was available in the environment that did this verification, so none of the above has been independently confirmed on iOS. `ChainKey.coinType` maps identically to Android's, so derivation *should* match, but this hasn't been checked on-device. `ConformanceTests/` currently has no address-derivation or signing test target at all (only the pre-existing amount-parsing one) — before this finding is fully closed for both platforms, an iOS engineer needs to (1) add `AddressDerivationConformanceTests`/`SigningConformanceTests` targets mirroring the Android ones, (2) run them against these same fixtures on a Mac, and (3) specifically resolve the **Tron divergence**: Android's `signTron` signs just the `txId` digest and reassembles JSON in app code, while iOS's hands wallet-core the full `rawJson` and returns its own reconstruction — `conformance/signing-vectors.json`'s `tron` entry spells out exactly what to check (the embedded signature hex must match Android's byte-for-byte; a mismatch there is a real bug, not a formatting difference).
 
 ## License
 

package/android/build.gradle

@@ -12,12 +12,16 @@ apply from: new File(
 applyKotlinExpoModulesCorePlugin()
 
 android {
-  namespace 'expo.modules.trustwalletcore'
-  compileSdkVersion 35
+  namespace 'com.chainberry.trustwalletcore'
+  compileSdkVersion 36
 
   defaultConfig {
     minSdkVersion 24
-    targetSdkVersion 35
+    targetSdkVersion 36
+    // Without this, AGP defaults to the legacy android.test.InstrumentationTestRunner, which
+    // cannot discover @RunWith(AndroidJUnit4::class)-annotated tests at all (connectedAndroidTest
+    // silently reports "0 tests"/"No tests found" instead of running AddressDerivationConformanceTest).
+    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   }
 
   compileOptions {
@@ -30,9 +34,14 @@ android {
   }
 }
 
-// ─── wallet-core credentials ──────────────────────────────────────────────────
-// GitHub Packages requires auth even for public packages.
-// Priority order (first non-empty wins):
+// ─── wallet-core artifact ──────────────────────────────────────────────────
+// com.trustwallet:wallet-core and its wallet-core-proto dependency are vendored
+// in libs/ as a plain local Maven repo, so a normal build needs NO GitHub
+// credentials at all — see libs/README.md for how it got there and how to
+// re-vendor when bumping the pinned version below.
+//
+// The GitHub Packages repo is kept as a fallback (e.g. resolving a version not
+// yet vendored) and needs auth even for this public package:
 //   1. Env vars     GITHUB_ACTOR / GITHUB_TOKEN       (CI / one-off terminal)
 //   2. Gradle props gpr.user / gpr.key in             (permanent dev setup)
 //        ~/.gradle/gradle.properties
@@ -49,6 +58,8 @@ def githubToken = System.getenv("GITHUB_TOKEN")
     ?: (project.hasProperty("gpr.key")   ? project.property("gpr.key")   : "")
 
 repositories {
+  maven { url = uri("$projectDir/libs") }
+
   maven {
     url = uri("https://maven.pkg.github.com/trustwallet/wallet-core")
     credentials {
@@ -64,4 +75,18 @@ dependencies {
   // Check github.com/trustwallet/wallet-core/releases for the latest version
   implementation 'com.trustwallet:wallet-core:4.1.19'
   implementation 'com.google.protobuf:protobuf-javalite:3.21.9'
+  // BiometricPrompt (biometry-or-device-credential gating on the Keystore-backed wallet cipher)
+  implementation 'androidx.biometric:biometric:1.1.0'
+
+  // JVM unit tests (src/test) — AmountParsingConformanceTest reads the shared JSON fixture
+  // in ../conformance/. Use the pure-Java org.json artifact, not android.jar's stubbed
+  // org.json (which throws "Stub!" outside Robolectric/instrumented tests).
+  testImplementation 'junit:junit:4.13.2'
+  testImplementation 'org.json:json:20240303'
+
+  // Instrumented tests (src/androidTest) — AddressDerivationConformanceTest needs the
+  // TrustWalletCore JNI library, which can only load on a real device or emulator.
+  // Run via: ./gradlew connectedDebugAndroidTest
+  androidTestImplementation 'androidx.test.ext:junit:1.1.5'
+  androidTestImplementation 'androidx.test:runner:1.5.2'
 }

package/android/libs/README.md

@@ -0,0 +1,34 @@
+# Vendored wallet-core (local Maven repo)
+
+`com.trustwallet:wallet-core` (and its `wallet-core-proto` dependency) are only
+published to GitHub Packages, which requires authentication even to download a
+public package. To spare every dev/CI machine from needing a
+`read:packages` PAT, the resolved `.aar`/`.jar` + `.pom` files are vendored
+here in a plain Maven-layout directory:
+
+```
+libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.{aar,pom}
+libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.{jar,pom}
+```
+
+`../build.gradle` points its `repositories {}` block at this directory
+*before* the GitHub Packages fallback, so a normal build resolves entirely
+from here — no credentials needed.
+
+Files were downloaded from `maven.pkg.github.com/trustwallet/wallet-core` on
+2026-09-04 and their sha1 checksums verified against GitHub's own
+`.sha1` files (still alongside each artifact here).
+
+## Bumping the pinned version
+
+1. `./download.sh <new-version>` (needs `GITHUB_ACTOR`/`GITHUB_TOKEN` env vars,
+   or `gpr.user`/`gpr.key` in `~/.gradle/gradle.properties` — same credentials
+   the GitHub Packages fallback in `build.gradle` already uses).
+2. Update the pinned version in `../build.gradle`
+   (`implementation 'com.trustwallet:wallet-core:...'`) and in
+   `../../ChainberryTrustWalletCoreModule.podspec` (`s.dependency 'TrustWalletCore', '...'`)
+   to keep both platforms on the same wallet-core release.
+3. Delete the old version's directories under `com/trustwallet/wallet-core*/`
+   here (or leave them if you want to keep an easy rollback).
+4. Re-run the conformance suite (`conformance/`) — a wallet-core bump can
+   change derivation/signing output.

package/android/libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.aar.md5

@@ -0,0 +1 @@
+3f07349ecbe013f2098684cc70cef49e

package/android/libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.aar.sha1

@@ -0,0 +1 @@
+58c6ee87c3ab4fb90c6ef4e9ba4f78260740ca16

package/android/libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.pom

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <!-- This module was also published with a richer model, Gradle metadata,  -->
+  <!-- which should be used instead. Do not delete the following line which  -->
+  <!-- is to indicate to Gradle or any Gradle module metadata file consumer  -->
+  <!-- that they should prefer consuming it instead. -->
+  <!-- do_not_remove: published-with-gradle-metadata -->
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.trustwallet</groupId>
+  <artifactId>wallet-core</artifactId>
+  <version>4.1.19</version>
+  <packaging>aar</packaging>
+  <dependencies>
+    <dependency>
+      <groupId>com.trustwallet</groupId>
+      <artifactId>wallet-core-proto</artifactId>
+      <version>4.1.19</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+</project>

package/android/libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.pom.md5

@@ -0,0 +1 @@
+d4a399c80d4f896ae4d4ea6013f1f15f

package/android/libs/com/trustwallet/wallet-core/4.1.19/wallet-core-4.1.19.pom.sha1

@@ -0,0 +1 @@
+a00894bc91fbbbf496fd3792484082334363e0fe

package/android/libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.jar.md5

@@ -0,0 +1 @@
+2c47413fd480c3ae3a4245f8487a343e

package/android/libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.jar.sha1

@@ -0,0 +1 @@
+1a68899feeb645d9895264d4c58e046dbcb3d528

package/android/libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.pom

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <!-- This module was also published with a richer model, Gradle metadata,  -->
+  <!-- which should be used instead. Do not delete the following line which  -->
+  <!-- is to indicate to Gradle or any Gradle module metadata file consumer  -->
+  <!-- that they should prefer consuming it instead. -->
+  <!-- do_not_remove: published-with-gradle-metadata -->
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.trustwallet</groupId>
+  <artifactId>wallet-core-proto</artifactId>
+  <version>4.1.19</version>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.protobuf</groupId>
+      <artifactId>protobuf-javalite</artifactId>
+      <version>3.22.3</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+</project>

package/android/libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.pom.md5

@@ -0,0 +1 @@
+e3987a3948a049ac60b57fa808b8f8ae

package/android/libs/com/trustwallet/wallet-core-proto/4.1.19/wallet-core-proto-4.1.19.pom.sha1

@@ -0,0 +1 @@
+90383b24ce13303b7c7a435ba815209115fa7d06

package/android/libs/download.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Re-vendors com.trustwallet:wallet-core (+ its wallet-core-proto dependency)
+# from GitHub Packages into this directory, laid out as a plain local Maven
+# repo (com/<group>/<artifact>/<version>/...). build.gradle points at this
+# directory first, so a normal build needs no GitHub credentials — only
+# re-running this script (to bump the pinned version, or the first time
+# someone sets this up) needs a token.
+#
+# Usage:
+#   GITHUB_ACTOR=you GITHUB_TOKEN=ghp_xxx ./download.sh 4.1.19
+# or rely on gpr.user / gpr.key in ~/.gradle/gradle.properties (same
+# credentials used by build.gradle's GitHub Packages fallback).
+set -euo pipefail
+
+VERSION="${1:?Usage: download.sh <wallet-core version, e.g. 4.1.19>}"
+LIBS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+GITHUB_USER="${GITHUB_ACTOR:-}"
+GITHUB_PASS="${GITHUB_TOKEN:-}"
+if [ -z "$GITHUB_USER" ] || [ -z "$GITHUB_PASS" ]; then
+  GRADLE_PROPS="$HOME/.gradle/gradle.properties"
+  if [ -f "$GRADLE_PROPS" ]; then
+    GITHUB_USER="${GITHUB_USER:-$(grep '^gpr.user=' "$GRADLE_PROPS" | cut -d= -f2-)}"
+    GITHUB_PASS="${GITHUB_PASS:-$(grep '^gpr.key='  "$GRADLE_PROPS" | cut -d= -f2-)}"
+  fi
+fi
+if [ -z "$GITHUB_USER" ] || [ -z "$GITHUB_PASS" ]; then
+  echo "error: no GitHub credentials found (env vars or ~/.gradle/gradle.properties gpr.user/gpr.key)" >&2
+  exit 1
+fi
+
+REGISTRY="https://maven.pkg.github.com/trustwallet/wallet-core"
+
+# module:packaging pairs — wallet-core is an .aar, wallet-core-proto is a plain .jar
+MODULES=("wallet-core:aar" "wallet-core-proto:jar")
+
+for entry in "${MODULES[@]}"; do
+  artifact="${entry%%:*}"
+  ext="${entry##*:}"
+  dest="$LIBS_DIR/com/trustwallet/$artifact/$VERSION"
+  mkdir -p "$dest"
+  base="$REGISTRY/com/trustwallet/$artifact/$VERSION"
+  for file in "$artifact-$VERSION.pom" "$artifact-$VERSION.$ext" "$artifact-$VERSION.pom.sha1" "$artifact-$VERSION.$ext.sha1"; do
+    echo "fetching $file"
+    curl -sS -L -f -u "$GITHUB_USER:$GITHUB_PASS" -o "$dest/$file" "$base/$file"
+  done
+  # verify what we just wrote against GitHub's own sha1
+  ( cd "$dest" && sha1sum -c "$artifact-$VERSION.pom.sha1" "$artifact-$VERSION.$ext.sha1" )
+done
+
+echo "done — vendored wallet-core $VERSION into $LIBS_DIR"
+echo "remember to bump the version in ../build.gradle (dependencies block) and the podspec, and delete the old version's directories above if this is a version bump rather than a first-time vendor."

package/android/src/androidTest/java/com/chainberry/trustwalletcore/AddressDerivationConformanceTest.kt

@@ -0,0 +1,106 @@
+package com.chainberry.trustwalletcore
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import wallet.core.jni.CoinType
+import wallet.core.jni.HDWallet
+
+// Instrumented test — must run on a device or emulator (needs the TrustWalletCore JNI library).
+// Run via: ./gradlew connectedDebugAndroidTest
+//
+// 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 it with real funds.
+//
+// All 10 chains were verified on-device (real emulator, WalletCore 4.1.19 JNI) on 2026-08-27,
+// cross-checked against an independent derivation via the WASM build (@trustwallet/wallet-core
+// 3.3.3, run in plain Node — see conformance/address-derivation-vectors.json's _note). On-device
+// 4.1.19 is authoritative wherever the two disagree.
+//
+// IMPORTANT — this test did not actually run before this pass. Two pre-existing bugs prevented
+// it from ever executing: (1) `coin.name()` doesn't compile against this Kotlin CoinType binding
+// (name is a property, not a method — fixed here), and (2) no `testInstrumentationRunner` was
+// configured in build.gradle, so AGP defaulted to the legacy runner, which cannot discover
+// @RunWith(AndroidJUnit4::class) tests at all ("0 tests"/"No tests found", not a real pass).
+// Once actually run, it immediately caught a real bug: the ETHEREUM/SMARTCHAIN "verified" address
+// below was wrong (0x9d8A62f6...) — never actually checked against real WalletCore output despite
+// being marked "verified". The corrected value below is the real on-device 4.1.19 result.
+//
+// For any NEW chain added to ChainKey in the future: add its CoinType to PENDING, run this test,
+// read the printed address in logcat, verify it independently (e.g. against a TWC 4.1.19 REPL or
+// the iOS companion test — see ConformanceTests/), then move it into VERIFIED.
+//
+// Human-readable source of truth: conformance/address-derivation-vectors.json.
+@RunWith(AndroidJUnit4::class)
+class AddressDerivationConformanceTest {
+
+  companion object {
+    init { System.loadLibrary("TrustWalletCore") }
+
+    const val MNEMONIC = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+    // Chains with expected addresses confirmed against WalletCore 4.1.19, on a real device/emulator.
+    // ETH / BNB / POL all share CoinType.ETHEREUM (same secp256k1 key, BIP44 m/44'/60'/0'/0/0).
+    val VERIFIED = mapOf(
+      CoinType.ETHEREUM to "0x9858EfFD232B4033E47d90003D41EC34EcaEda94", // ethereum / bnb / polygon
+      CoinType.SMARTCHAIN to "0x9858EfFD232B4033E47d90003D41EC34EcaEda94", // bnb (same key as ethereum)
+      CoinType.BITCOIN to "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu",
+      CoinType.LITECOIN to "ltc1qjmxnz78nmc8nq77wuxh25n2es7rzm5c2rkk4wh",
+      CoinType.XRP to "rHsMGQEkVNJmpGWs8XUBoTBiAAbwxZN5v3",
+      CoinType.TRON to "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
+      // Non-bounceable (UQ...) — WalletCore 4.1.19's default for this CoinType. The WASM build
+      // (@trustwallet/wallet-core 3.3.3) derives the same underlying hash but defaults to the
+      // bounceable (EQ...) encoding instead — a version/binding difference in address-flag
+      // defaults, not a key-derivation discrepancy. On-device 4.1.19 (what the app actually ships)
+      // is authoritative here.
+      CoinType.TON to "UQAzWZa6nM5mJev91wGc7VCSfBoIsYRqKJpV78N8Add9-RKY",
+      CoinType.SOLANA to "GjJyeC1r2RgkuoCWMyPYkCWSGSGLcz266EaAkLA27AhL",
+      CoinType.BITCOINCASH to "bitcoincash:qqyx49mu0kkn9ftfj6hje6g2wfer34yfnq5tahq3q6",
+    )
+
+    // Steady state is empty — add a chain's CoinType here (and drop it from VERIFIED) only while
+    // actively harvesting a newly-added chain's address for the first time.
+    val PENDING = emptyList<CoinType>()
+  }
+
+  @Test
+  fun verifiedAddressesMatch() {
+    val wallet = HDWallet(MNEMONIC, "")
+    for ((coin, expected) in VERIFIED) {
+      val actual = wallet.getAddressForCoin(coin)
+      assertEquals("address mismatch for coin=${coin.name}", expected, actual)
+    }
+  }
+
+  // Regression test for a real bug: ChainSigner.addressForChain originally derived Litecoin's
+  // and Bitcoin Cash's hand-rolled testnet address from the identical path m/44'/1'/0'/0/0.
+  // BIP32 derivation only depends on (seed, path, curve) — CoinType alone doesn't perturb it
+  // when the literal path and curve (secp256k1 for both) are the same — so LTC and BCH silently
+  // derived the *same* key, and therefore the same address. Fixed by using each coin's own
+  // SLIP-44 index as the account (3rd) path component (see ChainSigner.utxoTestnetPath).
+  @Test
+  fun testnetAddressesAreDistinctPerChain() {
+    val wallet = HDWallet(MNEMONIC, "")
+    val btc = ChainSigner.addressForChain(wallet, ChainKey.BITCOIN, isTestnet = true)
+    val ltc = ChainSigner.addressForChain(wallet, ChainKey.LITECOIN, isTestnet = true)
+    val bch = ChainSigner.addressForChain(wallet, ChainKey.BITCOINCASH, isTestnet = true)
+    println("[AddressDerivationConformanceTest] testnet: BTC=$btc LTC=$ltc BCH=$bch")
+    assertNotEquals("BTC/LTC testnet addresses must not collide", btc, ltc)
+    assertNotEquals("BTC/BCH testnet addresses must not collide", btc, bch)
+    assertNotEquals("LTC/BCH testnet addresses must not collide", ltc, bch)
+  }
+
+  @Test
+  fun printPendingAddressesForVerification() {
+    val wallet = HDWallet(MNEMONIC, "")
+    val lines = PENDING.map { coin -> "  ${coin.name} -> ${wallet.getAddressForCoin(coin)}" }
+    println(
+      "\n[AddressDerivationConformanceTest] Pending — verify and move to VERIFIED map:\n" +
+        lines.joinToString("\n")
+    )
+    // This test intentionally never fails — it exists only to harvest pending addresses.
+  }
+}