@chainberry/trust-wallet-core 2.0.0 → 2.5.1

package/{TrustWalletCoreModule.podspec → ChainberryTrustWalletCoreModule.podspec}

@@ -3,19 +3,20 @@ 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
   s.homepage       = 'https://github.com/Chainberry-com/trust-wallet-core'
   s.license        = package['license']
   s.author         = 'Chainberry'
-  s.platform       = :ios, '16.0'
+  s.platform       = :ios, '15.1'
   s.source         = { git: 'git@github.com:Chainberry-com/trust-wallet-core.git', tag: "v#{package['version']}" }
   s.static_framework = true
 
-  s.source_files = 'ios/**/*.{h,m,mm,swift}'
+  s.source_files         = 'ios/**/*.{h,m,mm,swift}'
+  s.exclude_files        = 'ios/ConformanceTests/**'
 
   s.dependency 'ExpoModulesCore'
-  s.dependency 'TrustWalletCore'
+  s.dependency 'TrustWalletCore', '4.1.19'
 end

package/README.md

@@ -10,28 +10,13 @@ Supported chains: Ethereum, BNB Smart Chain, Polygon, Solana, Tron, TON, Bitcoin
 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.
+This is an Expo native module with native Android/iOS code. It uses Expo's autolinking mechanism and does not ship an Expo config plugin. A development build is required (`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
 
@@ -42,7 +27,12 @@ Android biometric gating additionally pulls in `androidx.biometric:biometric:1.1
 ## Usage
 
 ```ts
-import { createWallet, importWallet, signTransaction, exportMnemonic } from "@chainberry/trust-wallet-core";
+import {
+  createWallet,
+  importWallet,
+  signTransaction,
+  exportMnemonic,
+} from "@chainberry/trust-wallet-core";
 
 const { walletId, addresses } = await createWallet(); // 128-bit / 12-word by default
 // addresses: { ethereum: "0x...", solana: "...", bnb: "0x...", bitcoin: "...", ... }
@@ -58,10 +48,10 @@ 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).
+- `deleteWallet(walletId)` — removes the wallet's native key material and metadata entry. Irreversible; requires a fresh biometric/passcode confirmation before deletion proceeds on both platforms.
 - `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.
 
@@ -69,11 +59,23 @@ 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).
+
+Both Android suites are CI-gated on every push/PR (`.github/workflows/ci.yml`'s `android-unit-tests` and `android-instrumented-tests` jobs, via `example/` — see that folder's README for why an Expo host app is needed to build this module at all). iOS's CI job is still a structural podspec lint only; see the conformance-suite note below for what's missing to close that gap.
+
+**Tron divergence resolved.** iOS's `signTron` used to hand wallet-core the full `rawJson` and return its own reconstruction, diverging from Android's `txId`-only input + manual JSON reassembly — and `TronSigningInput` has no `rawJson` field in the pinned 4.1.19 anyway, so the old iOS code didn't compile. iOS now signs the same way Android does: `TronSigningInput.txID` set to the digest, signature reassembled into `{...tx, signature}` in app code (see `ios/ChainSigning.swift`'s `signTron`). Same key + same digest is guaranteed to produce the same ECDSA signature, so this is a structural fix, not something that needs a device to confirm.
+
+**iOS conformance suites are written but not yet wired into a runnable target.** `ios/ConformanceTests/AddressDerivationConformanceTests.swift` and `SigningConformanceTests.swift` mirror the Android fixtures above (all 10 address-derivation chains, the same 8 signing vectors, including a `testTron()` that asserts the reassembled signature matches Android's byte-for-byte). Neither file is part of the `ConformanceTests/` SwiftPM package (which still only builds the amount-parsing target — these two `import WalletCore`/`import XCTest`, which that dependency-free package deliberately avoids) or of any Xcode project (`ios/` is gitignored, regenerated by `expo prebuild`, so nothing durable lives there). An iOS engineer still needs to add both files to an XCTest target in the host app's workspace that links `WalletCore.xcframework`, run them on a Mac, and promote `conformance/signing-vectors.json`'s `tron` vector off `"verified-android-only"` once that run confirms the signature match. Until then, `ChainKey.coinType` mapping identically to Android's makes address derivation _likely_ correct on iOS, but this hasn't been independently run on-device.
 
 ## 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.
+  }
+}