@chainberry/trust-wallet-core 2.0.0 → 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

@@ -12,26 +12,11 @@ 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
 
@@ -58,8 +43,8 @@ const mnemonic = await exportMnemonic(walletId);
 
 ## API
 
-- `createWallet(strength = 128, passphrase = "")` — 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.
-- `importWallet(mnemonic, passphrase = "")` — 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.
+- `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`.
@@ -69,11 +54,19 @@ const mnemonic = await exportMnemonic(walletId);
 
 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; a hardware-backed 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.
+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.
 
-**Not yet verified against a real device/build**: the per-chain `SigningInput` field mappings for Bitcoin, Litecoin, Tron, XRP, and TON, and Solana's raw-transaction signing mode, were written against the general Trust Wallet Core API shape but haven't been compiled or run against this module's pinned `wallet-core` version. Confirm field names and produce byte-for-byte signed-output parity against the previous JS-based signers (or a testnet broadcast) before trusting any of these chains with real funds. Ethereum/BNB/Polygon signing is a straightforward reshape of what this module already proved out.
+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.
+
+**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).
+
+**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 {
@@ -66,4 +77,16 @@ dependencies {
   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.
+  }
+}

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

@@ -0,0 +1,186 @@
+package com.chainberry.trustwalletcore
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import wallet.core.jni.BitcoinScript
+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 ChainSigner.sign() — the exact same call path ChainberryTrustWalletCoreModule.kt uses in
+// production — produces the expected byte-for-byte signed output for a fixed, representative
+// unsignedTx per chain, under WalletCore 4.1.19 (the pinned version). Inputs are deterministic
+// but NOT necessarily broadcast-valid (fake txids/blockhash/etc.) — this is a regression fixture,
+// not a live-network test.
+//
+// BCH is intentionally absent — ChainSigner.sign() throws for BITCOINCASH (sending unsupported
+// on both platforms; see ChainSigning.kt). Every other advertised chain has exactly one vector,
+// except EVM: `ethereum` covers the legacy gasPriceHex path and `polygon` covers the separate
+// EIP-1559 maxFeePerGasHex/maxPriorityFeePerGasHex branch in signEvm — bnb needs no case of its
+// own beyond that (same code path/CoinType as ethereum).
+//
+// Human-readable source of truth: conformance/signing-vectors.json.
+@RunWith(AndroidJUnit4::class)
+class SigningConformanceTest {
+
+  companion object {
+    init { System.loadLibrary("TrustWalletCore") }
+
+    const val MNEMONIC = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+
+    // Wallet's own on-device-derived addresses (see AddressDerivationConformanceTest.VERIFIED) —
+    // used as toAddress/changeAddress/Account/feePayer below so every UTXO/XRP/Solana vector is a
+    // (fake, never-broadcast) *self-send*, keeping this fixture self-contained with no external
+    // address dependency.
+    const val ETH_ADDR = "0x9858EfFD232B4033E47d90003D41EC34EcaEda94"
+    const val BTC_ADDR = "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu"
+    const val LTC_ADDR = "ltc1qjmxnz78nmc8nq77wuxh25n2es7rzm5c2rkk4wh"
+    const val XRP_ADDR = "rHsMGQEkVNJmpGWs8XUBoTBiAAbwxZN5v3"
+    const val TON_ADDR = "UQAzWZa6nM5mJev91wGc7VCSfBoIsYRqKJpV78N8Add9-RKY"
+
+    // Fixed, deterministic (not necessarily real/broadcastable) inputs per chain.
+    fun vectors(): Map<String, Pair<ChainKey, Map<String, Any>>> {
+      // Same 32-byte all-zero value reused below purely as a deterministic placeholder txid/hash
+      // — never broadcast, so it doesn't need to reference a real UTXO/blockhash.
+      val fakeTxId = "00".repeat(32)
+
+      return linkedMapOf(
+        "ethereum" to (ChainKey.ETHEREUM to mapOf(
+          "to" to ETH_ADDR,
+          "chainId" to 1,
+          "nonce" to 0,
+          "gasLimitHex" to "5208", // 21000
+          "valueHex" to "de0b6b3a7640000", // 1 ETH
+          "gasPriceHex" to "4a817c800", // 20 gwei — legacy path
+        )),
+        "polygon" to (ChainKey.POLYGON to mapOf(
+          "to" to ETH_ADDR,
+          "chainId" to 137,
+          "nonce" to 0,
+          "gasLimitHex" to "5208",
+          "valueHex" to "de0b6b3a7640000",
+          "maxFeePerGasHex" to "9502f9000", // EIP-1559 path
+          "maxPriorityFeePerGasHex" to "3b9aca00",
+        )),
+        "bitcoin" to (ChainKey.BITCOIN to utxoTx(CoinType.BITCOIN, BTC_ADDR, fakeTxId)),
+        "litecoin" to (ChainKey.LITECOIN to utxoTx(CoinType.LITECOIN, LTC_ADDR, fakeTxId)),
+        "xrp" to (ChainKey.XRP to mapOf(
+          "Account" to XRP_ADDR,
+          "Destination" to XRP_ADDR,
+          "Amount" to "1000000", // 1 XRP, drops
+          "Fee" to "12",
+          "Sequence" to 1,
+          "LastLedgerSequence" to 100,
+        )),
+        "ton" to (ChainKey.TON to mapOf(
+          "toAddress" to TON_ADDR,
+          "amount" to "1000000000", // 1 TON, nanotons
+          "seqno" to 1,
+          "memoId" to "conformance-test",
+        )),
+        "tron" to (ChainKey.TRON to mapOf(
+          // A genuinely all-zero digest degenerates silently in wallet-core's direct-sign path
+          // (empty signature, no error) — use a non-trivial fixed fake digest instead.
+          "txID" to "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+        )),
+        "solana" to (ChainKey.SOLANA to mapOf(
+          // Fixed unsigned tx built via @solana/web3.js: feePayer/from = this wallet's own
+          // Solana address, to = the System Program id (32 zero bytes, a fixed valid pubkey),
+          // recentBlockhash = the same all-zero value (never broadcast, only needs to be
+          // shape-valid base58 for TransactionDecoder). See conformance/signing-vectors.json's
+          // solana entry for the exact base64 blob and how it was generated.
+          "unsignedTxBase64" to "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAC6bYGKEG7l3rSHeceyWGQBjPCbyE4TgFbAUpjemFJlUcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAEMAgAAAEBCDwAAAAAA",
+        )),
+      )
+    }
+
+    // scriptPubKeyHex is computed here (BitcoinScript.lockScriptForAddress), not hand-derived from
+    // bech32, so the UTXO vector always matches this wallet's own real P2WPKH lock script.
+    private fun utxoTx(coin: CoinType, ownAddress: String, fakeTxId: String): Map<String, Any> {
+      val scriptHex = BitcoinScript.lockScriptForAddress(ownAddress, coin).data()
+        .joinToString("") { "%02x".format(it) }
+      return mapOf(
+        "toAddress" to ownAddress,
+        "changeAddress" to ownAddress,
+        "sendAmountSats" to "50000",
+        "changeAmountSats" to "40000",
+        "satsPerByte" to 10,
+        "inputs" to listOf(
+          mapOf(
+            "txIdHex" to fakeTxId,
+            "vout" to 0,
+            "amountSats" to "100000",
+            "scriptPubKeyHex" to scriptHex,
+          )
+        ),
+      )
+    }
+
+    // Expected signed outputs, confirmed on-device against WalletCore 4.1.19 (harvested via
+    // printSigningVectorsForVerification, see conformance/signing-vectors.json for the full
+    // methodology). "ton" is deliberately absent — signTon() embeds a wall-clock
+    // `expireAt = now + 600s` into the signed payload, so its output is never byte-reproducible
+    // across runs; see tonVectorIsWellFormed() below for what's actually checked instead.
+    val EXPECTED: Map<String, String> = mapOf(
+      "ethereum" to "0xf86c808504a817c800825208949858effd232b4033e47d90003d41ec34ecaeda94880de0b6b3a76400008026a0b7cca5f69561cd482cec4e692bd2da17d9eb1d6b3a83fe3f7f11d117de99ca97a00ad0dc153460e39b355c226a2744fc2926f84b95b89c954551571f1bbc251478",
+      "polygon" to "0x02f874818980843b9aca008509502f9000825208949858effd232b4033e47d90003d41ec34ecaeda94880de0b6b3a764000080c001a038b5c72ee38aa18607462b80ab0cb170a8d4df1c4090ac49acd41d6b4b0f9acca05bdee390ee8a50ff569f55d408371213df72a3065902b07317289b39788cb434",
+      "bitcoin" to "0100000000010100000000000000000000000000000000000000000000000000000000000000000000000000000000000250c3000000000000160014c0cebcd6c3d3ca8c75dc5ec62ebe55330ef910e2cebd000000000000160014c0cebcd6c3d3ca8c75dc5ec62ebe55330ef910e20247304402201e8f3663c97712bbf662c96df532e701ca9b660b507ab170d7b4ffbd966d4be0022033bd537c7720b1e7be2b7663d1a0adcbe565ff18a25794aec828015529ab80e101210330d54fd0dd420a6e5f8d3624f5f3482cae350f79d5f0753bf5beef9c2d91af3c00000000",
+      "litecoin" to "0100000000010100000000000000000000000000000000000000000000000000000000000000000000000000000000000250c300000000000016001496cd3178f3de0f307bcee1aeaa4d5987862dd30acebd00000000000016001496cd3178f3de0f307bcee1aeaa4d5987862dd30a0248304502210093a73dec624132e9ea3d1a629c0c08be77be68416b0f99cbeb23381967ce8c560220385912e0b0835bcd1dd844bae68e4df208af8b07b095d5ac5ce6cd4407a27a85012102e49c9b9b5d0f127235dc26a0c252814c52fb333d651a946773f59d72c2da990400000000",
+      "xrp" to "12000022000000002400000001201b000000646140000000000f424068400000000000000c7321031d68bc1a142e6766b2bdfb006ccfe135ef2e0e2e94abb5cf5c9ab6104776fbae7446304402207fb80c118799a9b3d4dad6e91ad1b8f0c5c9d189a0bcdaf50e823ea44f8044e70220422f638bf4b4e634cb39a4250cf72513d5e3c7e810a13c2f35b5df54b02dc7c98114aff3c2e33458b30714ca16ffee19952dd35c17c88314aff3c2e33458b30714ca16ffee19952dd35c17c8",
+      "tron" to "{\"txID\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\"signature\":[\"4b63d125c56637e9f09d9578bf9fbf30e0e6796085bb0fe8aa7c466b2ae9bc690a26d26fe36ff0d42d416ce76b70b486c50c0294b50d5a6e9871d2f3a7ebd28901\"]}",
+      "solana" to "Aa+eJgDHJo2f9vGrz1EpPPnfGWcZoySFIEw0sS7OVvYiF4U421YCQqLme/uESu3SLan0AM6xblAfUgYlM28StQcBAAAC6bYGKEG7l3rSHeceyWGQBjPCbyE4TgFbAUpjemFJlUcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAEMAgAAAEBCDwAAAAAA",
+    )
+  }
+
+  @Test
+  fun printSigningVectorsForVerification() {
+    val wallet = HDWallet(MNEMONIC, "")
+    val lines = vectors().map { (chain, pair) ->
+      val (chainKey, unsignedTx) = pair
+      val result = try {
+        ChainSigner.sign(chainKey, wallet, unsignedTx, isTestnet = false)
+      } catch (e: Exception) {
+        return@map "  $chain -> ERROR: ${e.message}"
+      }
+      val metaStr = result.meta?.let { " meta=$it" } ?: ""
+      "  $chain -> ${result.signedTx}$metaStr"
+    }
+    println(
+      "\n[SigningConformanceTest] Harvested signed outputs — verify and populate EXPECTED:\n" +
+        lines.joinToString("\n")
+    )
+    // This test intentionally never fails — it exists only to harvest signing vectors.
+  }
+
+  @Test
+  fun signedOutputsMatch() {
+    val wallet = HDWallet(MNEMONIC, "")
+    for ((chain, pair) in vectors()) {
+      val expected = EXPECTED[chain] ?: continue
+      val (chainKey, unsignedTx) = pair
+      val actual = ChainSigner.sign(chainKey, wallet, unsignedTx, isTestnet = false).signedTx
+      assertEquals("signed output mismatch for chain=$chain", expected, actual)
+    }
+  }
+
+  // TON's signTon() embeds a wall-clock `expireAt = now + 600s` into the signed BOC, so its
+  // output (and meta.txHash, which hashes that BOC) is never byte-reproducible across runs —
+  // a real constraint of the production code, not a test gap. This checks the parts that ARE
+  // deterministic instead: signing succeeds, the output is a well-formed base64 BOC, and
+  // meta.txHash is present and the right shape.
+  @Test
+  fun tonVectorIsWellFormed() {
+    val wallet = HDWallet(MNEMONIC, "")
+    val (chainKey, unsignedTx) = vectors().getValue("ton")
+    val result = ChainSigner.sign(chainKey, wallet, unsignedTx, isTestnet = false)
+    assert(result.signedTx.startsWith("te6cc")) {
+      "TON signed output doesn't look like a BOC (expected te6cc... prefix): ${result.signedTx}"
+    }
+    val txHash = result.meta?.get("txHash") as? String
+    assertEquals("TON meta.txHash should be a 32-byte hex string", 64, txHash?.length)
+  }
+}