@chainberry/trust-wallet-core 2.0.0 → 2.5.1

package/android/src/test/java/com/chainberry/trustwalletcore/AmountParsingConformanceTest.kt

@@ -0,0 +1,57 @@
+package com.chainberry.trustwalletcore
+
+import org.json.JSONArray
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Test
+import java.io.File
+
+// Reads ../../../../../../conformance/amount-parsing-cases.json — the single fixture also
+// consumed by iOS's ConformanceTests/Tests/AmountParsingConformanceTests/ — and asserts
+// AmountParsing.kt agrees with AmountParsing.swift on throw-vs-valid for every case. Keeps
+// the two platforms' numeric parsing behavior from drifting apart. Plain JVM unit test (no
+// Robolectric/instrumentation needed — AmountParsing.kt has no Android framework dependency),
+// runs via `./gradlew testDebugUnitTest` (or the autolinked module's equivalent task).
+class AmountParsingConformanceTest {
+
+  // Gradle's `Test` task runs with the working directory set to the Gradle project directory
+  // (android/) by default — conformance/ is one level up, at the trust-wallet-core module root.
+  private fun fixtureFile(): File {
+    val projectDir = File(System.getProperty("user.dir") ?: ".")
+    return File(projectDir, "../conformance/amount-parsing-cases.json").canonicalFile
+  }
+
+  @Test
+  fun conformanceCasesMatch() {
+    val fixture = fixtureFile()
+    assertTrue("expected conformance fixture at ${fixture.path}", fixture.exists())
+    val cases = JSONArray(fixture.readText())
+    assertTrue("conformance fixture should not be empty", cases.length() > 0)
+
+    for (i in 0 until cases.length()) {
+      val testCase = cases.getJSONObject(i)
+      val id = testCase.getString("id")
+      val fn = testCase.getString("fn")
+      val expect = testCase.getString("expect")
+
+      var threw = false
+      try {
+        when (fn) {
+          "xrpAmountDrops" -> parseXrpAmountDrops(testCase.getString("input"))
+          "xrpFeeDrops" -> parseXrpFeeDrops(testCase.getString("input"))
+          "xrpDestinationTag" -> parseXrpDestinationTag(testCase.getLong("input"))
+          "tonNanotons" -> parseTonNanotons(testCase.getString("input"))
+          else -> fail("Unknown conformance case fn: $fn")
+        }
+      } catch (e: ChainSigningException) {
+        threw = true
+      }
+
+      val expectedThrow = expect == "throws"
+      assertTrue(
+        "case $id: expected $expect but got ${if (threw) "throws" else "valid"}",
+        threw == expectedThrow
+      )
+    }
+  }
+}

package/android/src/test/java/com/chainberry/trustwalletcore/Bech32Test.kt

@@ -0,0 +1,35 @@
+package com.chainberry.trustwalletcore
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+// Plain JVM unit test (no wallet-core JNI needed) — verifies Bech32.encodeSegwitV0.
+//
+// p2wpkhVectorMatches is checked against a real, independently-known-valid mainnet address
+// (its checksum was verified by decoding it with a from-scratch bech32 decoder before use
+// here — this isn't just a hand-copied hex string). p2wshVectorMatches and
+// testnetHrpVectorMatches exercise the same (by then proven-correct) encoder on a 32-byte
+// program and a different hrp, generated by that same verified implementation.
+class Bech32Test {
+
+  private fun hexToBytes(hex: String): ByteArray =
+    ByteArray(hex.length / 2) { ((Character.digit(hex[it * 2], 16) shl 4) + Character.digit(hex[it * 2 + 1], 16)).toByte() }
+
+  @Test
+  fun p2wpkhVectorMatches() {
+    val program = hexToBytes("751e76e8199196d454941c45d1b3a323f1433bd6")
+    assertEquals("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", Bech32.encodeSegwitV0("bc", program))
+  }
+
+  @Test
+  fun p2wshVectorMatches() {
+    val program = hexToBytes("1863143c14c5166804bd19203356da136c985678cd4d27a1b8c6329604903262")
+    assertEquals("bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3", Bech32.encodeSegwitV0("bc", program))
+  }
+
+  @Test
+  fun testnetHrpVectorMatches() {
+    val program = hexToBytes("1863143c14c5166804bd19203356da136c985678cd4d27a1b8c6329604903262")
+    assertEquals("tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7", Bech32.encodeSegwitV0("tb", program))
+  }
+}

package/android/src/test/java/com/chainberry/trustwalletcore/NativeWalletStoreTest.kt

@@ -0,0 +1,344 @@
+package com.chainberry.trustwalletcore
+
+import android.security.keystore.KeyProperties
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricPrompt
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import java.io.File
+import java.util.UUID
+
+// Plain JVM unit tests (no Robolectric/instrumentation, same rationale as
+// AmountParsingConformanceTest) for the pieces of NativeWalletStore that don't need an
+// Android Context/Keystore/BiometricPrompt: wallet-id validation, the File-based
+// metadata/delete helpers, the keyAlias scheme, the pure canAuthenticate()-result /
+// BiometricPrompt-errorCode classification functions, and the pure KeyInfo-securityLevel
+// description functions — all extracted specifically to be testable this way. The auth-gated
+// paths that actually drive a Keystore key or a FragmentActivity/BiometricPrompt (mode
+// resolution, both authenticateFor*Wallet flows, confirmIdentity, the StrongBox-request/fallback
+// in generateKey, and the real KeyInfo introspection in logKeySecurityLevel) need a real
+// device/emulator and are covered by manual end-to-end verification instead (see the remediation
+// plan's verification section — API 24/28/29/30/35 x biometric-only/credential-only/both/
+// neither/changed-enrollment/lockout states, plus StrongBox-present/TEE-only/software-only key
+// generation).
+class NativeWalletStoreTest {
+
+  @get:Rule
+  val tmp = TemporaryFolder()
+
+  // ─── validateWalletId ────────────────────────────────────────────────────────
+
+  @Test
+  fun validateWalletId_acceptsFreshUuid() {
+    val id = UUID.randomUUID().toString()
+    assertEquals(id, NativeWalletStore.validateWalletId(id))
+  }
+
+  @Test
+  fun validateWalletId_rejectsPathTraversal() {
+    assertThrowsInvalidWalletId("../etc/passwd")
+  }
+
+  @Test
+  fun validateWalletId_rejectsEmptyString() {
+    assertThrowsInvalidWalletId("")
+  }
+
+  @Test
+  fun validateWalletId_rejectsMalformedUuid() {
+    assertThrowsInvalidWalletId("not-a-uuid")
+  }
+
+  private fun assertThrowsInvalidWalletId(walletId: String) {
+    try {
+      NativeWalletStore.validateWalletId(walletId)
+      fail("expected InvalidWalletId for '$walletId'")
+    } catch (e: NativeWalletStoreError.InvalidWalletId) {
+      // expected
+    }
+  }
+
+  // ─── metadata round-trip / corruption / atomicity ───────────────────────────
+
+  @Test
+  fun metadata_roundTrips() {
+    val file = File(tmp.root, "metadata.json")
+    val wallets = mapOf(
+      "id-1" to mapOf("ethereum" to "0xabc"),
+      "id-2" to mapOf("bitcoin" to "bc1abc"),
+    )
+    NativeWalletStore.saveMetadataToFile(file, wallets)
+    assertEquals(wallets, NativeWalletStore.loadMetadataFromFile(file))
+  }
+
+  @Test
+  fun metadata_missingFileIsEmptyMap() {
+    val file = File(tmp.root, "does-not-exist.json")
+    assertTrue(NativeWalletStore.loadMetadataFromFile(file).isEmpty())
+  }
+
+  @Test
+  fun metadata_corruptFileThrowsCorrupted_notSilentlyEmpty() {
+    val file = File(tmp.root, "metadata.json")
+    file.writeText("{ not valid json")
+    try {
+      NativeWalletStore.loadMetadataFromFile(file)
+      fail("expected Corrupted for malformed JSON")
+    } catch (e: NativeWalletStoreError.Corrupted) {
+      // expected — this is the key regression check: a corrupt store must never look
+      // identical to an empty one (that's what let createWallet stomp a real, unreadable
+      // index in the original incident).
+    }
+  }
+
+  @Test
+  fun metadata_failedWrite_leavesExistingFileUntouched() {
+    val target = File(tmp.root, "metadata.json")
+    val original = mapOf("id-1" to mapOf("ethereum" to "0xabc"))
+    NativeWalletStore.saveMetadataToFile(target, original)
+
+    // Making the parent directory read-only blocks creating the temp file at all (the
+    // earliest possible failure point of the write), which must surface as a typed
+    // PermissionDenied — not a raw IOException, and the pre-existing target file must be
+    // left exactly as it was (this is the atomicity guarantee: a failed write never touches
+    // the previously-committed file).
+    val originalBytes = target.readText()
+    target.parentFile!!.setWritable(false)
+    try {
+      try {
+        NativeWalletStore.saveMetadataToFile(target, mapOf("id-2" to mapOf("bitcoin" to "bc1xyz")))
+        // Some filesystems/CI runners ignore setWritable(false) for the owner (e.g. root).
+        // If the write unexpectedly succeeded, there's nothing to assert here.
+      } catch (e: NativeWalletStoreError.PermissionDenied) {
+        assertEquals(originalBytes, target.readText())
+      }
+    } finally {
+      target.parentFile!!.setWritable(true)
+    }
+  }
+
+  // ─── deleteFileChecked ───────────────────────────────────────────────────────
+
+  @Test
+  fun deleteFileChecked_missingFileIsNoOp() {
+    val file = File(tmp.root, "missing.enc")
+    // Should not throw even though the file was never created.
+    NativeWalletStore.deleteFileChecked(file, "some-wallet-id")
+  }
+
+  @Test
+  fun deleteFileChecked_deletesExistingFile() {
+    val file = File(tmp.root, "present.enc")
+    file.writeBytes(byteArrayOf(1, 2, 3))
+    NativeWalletStore.deleteFileChecked(file, "some-wallet-id")
+    assertFalse(file.exists())
+  }
+
+  @Test
+  fun deleteFileChecked_undeletableFileThrowsDeleteFailed() {
+    val dir = File(tmp.root, "readonly-dir").apply { mkdirs() }
+    val file = File(dir, "present.enc")
+    file.writeBytes(byteArrayOf(1, 2, 3))
+    dir.setWritable(false)
+    try {
+      try {
+        NativeWalletStore.deleteFileChecked(file, "some-wallet-id")
+        // Some filesystems/CI runners (e.g. running as root) ignore setWritable(false);
+        // nothing to assert if the delete unexpectedly succeeded.
+      } catch (e: NativeWalletStoreError.DeleteFailed) {
+        // expected
+      }
+    } finally {
+      dir.setWritable(true)
+    }
+  }
+
+  // ─── keyAlias ────────────────────────────────────────────────────────────────
+
+  @Test
+  fun keyAlias_encodesModeAndIsDistinctPerMode() {
+    val id = UUID.randomUUID().toString()
+    val bioAlias = NativeWalletStore.keyAlias(AuthMode.BIOMETRIC_STRONG, id)
+    val credAlias = NativeWalletStore.keyAlias(AuthMode.DEVICE_CREDENTIAL, id)
+    assertTrue(bioAlias.contains(id))
+    assertTrue(credAlias.contains(id))
+    assertFalse(bioAlias == credAlias)
+  }
+
+  @Test
+  fun keyAlias_legacyCombinedHasNoInfix() {
+    // Regression check for the orphaned-wallet bug: a wallet created before the
+    // biometric/device-credential split used a bare "vault_wallet_<id>" alias (no bio_/cred_
+    // infix). resolveExistingMode's legacy fallback depends on keyAlias(LEGACY_COMBINED, id)
+    // reproducing that exact string, or a pre-split wallet becomes permanently unreachable again.
+    val id = UUID.randomUUID().toString()
+    val legacyAlias = NativeWalletStore.keyAlias(AuthMode.LEGACY_COMBINED, id)
+    assertEquals("vault_wallet_$id", legacyAlias)
+  }
+
+  // ─── describeUnavailableReason ───────────────────────────────────────────────
+
+  @Test
+  fun describeUnavailableReason_mapsEachKnownCode() {
+    val codes = listOf(
+      BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED,
+      BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE,
+      BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE,
+      BiometricManager.BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED,
+      BiometricManager.BIOMETRIC_ERROR_UNSUPPORTED,
+      BiometricManager.BIOMETRIC_STATUS_UNKNOWN,
+    )
+    // Every known code gets a distinct, non-generic reason string (i.e. none of them fall
+    // through to the "unavailable (status $n)" catch-all).
+    val reasons = codes.map { NativeWalletStore.describeUnavailableReason(it) }
+    assertEquals(reasons.size, reasons.toSet().size)
+    reasons.forEach { assertFalse(it.startsWith("unavailable (status")) }
+  }
+
+  @Test
+  fun describeUnavailableReason_unknownCodeFallsThroughToGenericMessage() {
+    val reason = NativeWalletStore.describeUnavailableReason(-999)
+    assertTrue(reason.contains("-999"))
+  }
+
+  // ─── classifyPromptError ─────────────────────────────────────────────────────
+
+  @Test
+  fun classifyPromptError_lockoutIsTemporary() {
+    val error = NativeWalletStore.classifyPromptError(BiometricPrompt.ERROR_LOCKOUT, "locked out")
+    assertTrue(error is NativeWalletStoreError.AuthLockedOutTemporary)
+    assertEquals("ERR_WALLET_AUTH_LOCKED_OUT", error.code)
+  }
+
+  @Test
+  fun classifyPromptError_lockoutPermanentIsDistinctFromTemporary() {
+    val error = NativeWalletStore.classifyPromptError(BiometricPrompt.ERROR_LOCKOUT_PERMANENT, "locked out for good")
+    assertTrue(error is NativeWalletStoreError.AuthLockedOutPermanent)
+    assertEquals("ERR_WALLET_AUTH_LOCKED_OUT_PERMANENT", error.code)
+  }
+
+  @Test
+  fun classifyPromptError_userCancelledVariantsAllMapToCancelled() {
+    val cancelCodes = listOf(
+      BiometricPrompt.ERROR_USER_CANCELED,
+      BiometricPrompt.ERROR_NEGATIVE_BUTTON,
+      BiometricPrompt.ERROR_CANCELED,
+    )
+    cancelCodes.forEach { code ->
+      val error = NativeWalletStore.classifyPromptError(code, "cancelled")
+      assertTrue("code $code should classify as AuthCancelled", error is NativeWalletStoreError.AuthCancelled)
+      assertEquals("ERR_WALLET_AUTH_CANCELLED", error.code)
+    }
+  }
+
+  @Test
+  fun classifyPromptError_unrecognizedCodeFallsBackToAuthenticationFailed() {
+    val error = NativeWalletStore.classifyPromptError(BiometricPrompt.ERROR_NO_BIOMETRICS, "no biometrics enrolled")
+    assertTrue(error is NativeWalletStoreError.AuthenticationFailed)
+    assertEquals("ERR_AUTHENTICATION_FAILED", error.code)
+    assertEquals(BiometricPrompt.ERROR_NO_BIOMETRICS, (error as NativeWalletStoreError.AuthenticationFailed).errorCode)
+  }
+
+  // ─── describeSecurityLevel / describeLegacySecurityLevel ────────────────────
+
+  @Test
+  fun describeSecurityLevel_mapsEachKnownLevel() {
+    assertEquals("STRONGBOX", NativeWalletStore.describeSecurityLevel(KeyProperties.SECURITY_LEVEL_STRONGBOX))
+    assertEquals("TEE", NativeWalletStore.describeSecurityLevel(KeyProperties.SECURITY_LEVEL_TRUSTED_ENVIRONMENT))
+    assertEquals("SOFTWARE", NativeWalletStore.describeSecurityLevel(KeyProperties.SECURITY_LEVEL_SOFTWARE))
+  }
+
+  @Test
+  fun describeSecurityLevel_unknownLevelFallsThroughToGenericMessage() {
+    val description = NativeWalletStore.describeSecurityLevel(-999)
+    assertTrue(description.contains("-999"))
+    // Must never silently read as hardware-backed for a level this function doesn't recognize.
+    assertFalse(description == "STRONGBOX")
+    assertFalse(description == "TEE")
+  }
+
+  @Test
+  fun describeLegacySecurityLevel_insideSecureHardwareIsHardware() {
+    assertEquals("HARDWARE", NativeWalletStore.describeLegacySecurityLevel(true))
+  }
+
+  @Test
+  fun describeLegacySecurityLevel_notInsideSecureHardwareIsSoftware() {
+    assertEquals("SOFTWARE", NativeWalletStore.describeLegacySecurityLevel(false))
+  }
+
+  // ─── parseKeyAlias ───────────────────────────────────────────────────────────
+
+  @Test
+  fun parseKeyAlias_isTheInverseOfKeyAlias() {
+    val id = UUID.randomUUID().toString()
+    for (mode in AuthMode.entries) {
+      val alias = NativeWalletStore.keyAlias(mode, id)
+      assertEquals(mode to id, NativeWalletStore.parseKeyAlias(alias))
+    }
+  }
+
+  @Test
+  fun parseKeyAlias_legacyInfixDoesNotSwallowBioOrCredAliases() {
+    // Regression check: LEGACY_COMBINED's infix is "", which is a prefix of every alias under
+    // KEY_ALIAS_PREFIX — parseKeyAlias must still resolve a bio_/cred_ alias to its actual mode,
+    // not fall through to LEGACY_COMBINED just because the empty-infix check would also match.
+    val id = UUID.randomUUID().toString()
+    assertEquals(
+      AuthMode.BIOMETRIC_STRONG to id,
+      NativeWalletStore.parseKeyAlias(NativeWalletStore.keyAlias(AuthMode.BIOMETRIC_STRONG, id)),
+    )
+    assertEquals(
+      AuthMode.DEVICE_CREDENTIAL to id,
+      NativeWalletStore.parseKeyAlias(NativeWalletStore.keyAlias(AuthMode.DEVICE_CREDENTIAL, id)),
+    )
+  }
+
+  @Test
+  fun parseKeyAlias_unrelatedAliasReturnsNull() {
+    assertEquals(null, NativeWalletStore.parseKeyAlias("some_other_features_key"))
+  }
+
+  // ─── findOrphanFiles / findStaleMetadataTempFiles (reconciliation, docs/adr/0001) ────────────
+
+  @Test
+  fun findOrphanFiles_fileWithNoMetadataEntryIsOrphaned() {
+    File(tmp.root, "orphan-id.enc").writeBytes(byteArrayOf(1))
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = emptySet())
+    assertEquals(listOf("orphan-id.enc"), orphans.map { it.name })
+  }
+
+  @Test
+  fun findOrphanFiles_fileWithMatchingMetadataEntryIsNotOrphaned() {
+    File(tmp.root, "live-id.enc").writeBytes(byteArrayOf(1))
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = setOf("live-id"))
+    assertTrue(orphans.isEmpty())
+  }
+
+  @Test
+  fun findOrphanFiles_ignoresNonEncFiles() {
+    // metadata.json itself (and any stray temp file) must never be swept up as a wallet orphan.
+    File(tmp.root, "metadata.json").writeText("{}")
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = emptySet())
+    assertTrue(orphans.isEmpty())
+  }
+
+  @Test
+  fun findStaleMetadataTempFiles_findsLeftoverTempFile() {
+    // Simulates a saveMetadataToFile interrupted after the temp write but before the rename.
+    File(tmp.root, "metadata.json.tmp-12345").writeText("{}")
+    val stale = NativeWalletStore.findStaleMetadataTempFiles(tmp.root)
+    assertEquals(listOf("metadata.json.tmp-12345"), stale.map { it.name })
+  }
+
+  @Test
+  fun findStaleMetadataTempFiles_ignoresCommittedMetadataFile() {
+    File(tmp.root, "metadata.json").writeText("{}")
+    assertTrue(NativeWalletStore.findStaleMetadataTempFiles(tmp.root).isEmpty())
+  }
+}

package/expo-module.config.json

@@ -1,9 +1,10 @@
 {
   "platforms": ["ios", "android"],
   "ios": {
-    "modules": ["TrustWalletCoreModule"]
+    "modules": ["ChainberryTrustWalletCoreModule"],
+    "podspecPath": "ChainberryTrustWalletCoreModule.podspec"
   },
   "android": {
-    "modules": ["expo.modules.trustwalletcore.TrustWalletCoreModule"]
+    "modules": ["com.chainberry.trustwalletcore.ChainberryTrustWalletCoreModule"]
   }
 }

package/ios/AmountParsing.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+// Pure numeric-string parsing for the fields that used to silently substitute 0 on
+// malformed input (`Int64(s) ?? 0` / `UInt64(s) ?? 0`) instead of failing closed — see
+// ChainSigning.swift's signXrp/signTon. Deliberately has no WalletCore/ExpoModulesCore
+// dependency so it can be unit-tested standalone via the ConformanceTests SwiftPM package,
+// against the same fixture Android's AmountParsing.kt conformance test reads
+// (../conformance/amount-parsing-cases.json).
+
+enum AmountParsingError: Error, CustomStringConvertible {
+  case invalidXrpAmount(String)
+  case invalidXrpFee(String)
+  case invalidXrpDestinationTag
+  case invalidTonAmount(String)
+
+  var description: String {
+    switch self {
+    case .invalidXrpAmount(let s): return "Invalid XRP Amount: \(s)"
+    case .invalidXrpFee(let s): return "Invalid XRP Fee: \(s)"
+    case .invalidXrpDestinationTag: return "Invalid XRP DestinationTag: must be an integer 0...4294967295"
+    case .invalidTonAmount(let s): return "Invalid TON amount: \(s)"
+    }
+  }
+}
+
+/// XRP `Amount` (drops) must parse as a strictly positive Int64. A non-numeric, decimal,
+/// empty, or negative string must throw rather than silently sign a zero-value transfer.
+func parseXrpAmountDrops(_ s: String) throws -> Int64 {
+  guard let value = Int64(s), value > 0 else {
+    throw AmountParsingError.invalidXrpAmount(s)
+  }
+  return value
+}
+
+/// XRP `Fee` (drops) must parse as a non-negative Int64 (0 is a legitimate fee for some
+/// transaction types — only genuinely malformed input, not zero, should throw).
+func parseXrpFeeDrops(_ s: String) throws -> Int64 {
+  guard let value = Int64(s), value >= 0 else {
+    throw AmountParsingError.invalidXrpFee(s)
+  }
+  return value
+}
+
+/// XRP DestinationTag is an optional UInt32. `nil` passes through unchanged; a present
+/// value must be validated as non-negative and in-range *before* widening — Swift's
+/// `UInt64(someNegativeInt)` traps at runtime rather than throwing, so that conversion must
+/// never run on unvalidated input.
+func parseXrpDestinationTag(_ tag: Int?) throws -> UInt64? {
+  guard let tag else { return nil }
+  guard tag >= 0, tag <= 0xFFFF_FFFF else {
+    throw AmountParsingError.invalidXrpDestinationTag
+  }
+  return UInt64(tag)
+}
+
+/// TON `amount` (nanotons) must parse as a strictly positive UInt64.
+func parseTonNanotons(_ s: String) throws -> UInt64 {
+  guard let value = UInt64(s), value > 0 else {
+    throw AmountParsingError.invalidTonAmount(s)
+  }
+  return value
+}

package/ios/Bech32.swift

@@ -0,0 +1,66 @@
+import Foundation
+
+/// Minimal BIP-173 (bech32) segwit-address encoder, witness-version-0 only.
+///
+/// wallet-core's own `SegwitAddress` class only accepts an HRP from its closed native `HRP`
+/// enum — there's no "tltc" entry (Litecoin testnet isn't in wallet-core's coin registry at
+/// all; see ChainSigner.address(for:)). This reimplements just the encode half of BIP-173 by
+/// hand so Litecoin testnet can still get a real native-segwit address in the same style as
+/// its own mainnet "ltc1..." address, instead of falling back to a legacy P2PKH format.
+///
+/// Mirrors android/.../Bech32.kt exactly — see that file's Bech32Test for the algorithm's
+/// verification against a real, independently-decoded mainnet address.
+enum Bech32 {
+  private static let charset = Array("qpzry9x8gf2tvdw0s3jn54khce6mua7l")
+
+  private static func polymod(_ values: [Int]) -> Int {
+    let gen = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3]
+    var chk = 1
+    for v in values {
+      let b = chk >> 25
+      chk = ((chk & 0x1ffffff) << 5) ^ v
+      for i in 0..<5 {
+        if (b >> i) & 1 == 1 { chk ^= gen[i] }
+      }
+    }
+    return chk
+  }
+
+  private static func hrpExpand(_ hrp: String) -> [Int] {
+    let bytes = Array(hrp.utf8).map { Int($0) }
+    return bytes.map { $0 >> 5 } + [0] + bytes.map { $0 & 31 }
+  }
+
+  private static func createChecksum(hrp: String, data: [Int]) -> [Int] {
+    let values = hrpExpand(hrp) + data + [0, 0, 0, 0, 0, 0]
+    let mod = polymod(values) ^ 1
+    return (0..<6).map { (mod >> (5 * (5 - $0))) & 31 }
+  }
+
+  /// 8-bit bytes -> 5-bit groups (BIP-173 "convertbits", 8→5, with padding).
+  private static func convertBits8to5(_ data: Data) -> [Int] {
+    var acc = 0
+    var bits = 0
+    var out: [Int] = []
+    for b in data {
+      acc = (acc << 8) | Int(b)
+      bits += 8
+      while bits >= 5 {
+        bits -= 5
+        out.append((acc >> bits) & 0x1f)
+      }
+    }
+    if bits > 0 { out.append((acc << (5 - bits)) & 0x1f) }
+    return out
+  }
+
+  /// Encodes a witness-version-0 program (20 bytes for P2WPKH, 32 for P2WSH) as a lowercase
+  /// bech32 segwit address under `hrp`.
+  static func encodeSegwitV0(hrp: String, program: Data) -> String {
+    let data = [0] + convertBits8to5(program)
+    let combined = data + createChecksum(hrp: hrp, data: data)
+    var result = hrp + "1"
+    for d in combined { result.append(charset[d]) }
+    return result
+  }
+}