10. Android
The AAR is the same library as the JAR, packaged for Android. It holds the Java classes, the native library for three ABIs and the R8 rules an app needs. This chapter covers what is different on Android: the dependency, devices, the RPC classes below API 26 and the network. It then covers storage, backup, lifecycle, logs, a first test and the R8 rules. TLS to a node, with Android's default trust, is in TLS to a node.
The dependency#
The repository goes where the project declares its repositories, which in a project created by Android Studio is settings.gradle.kts:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://loki-notfound.github.io/myzephyr-java/maven") }
}
}
The dependency and the packaging line go into the app module's build.gradle.kts:
android {
packaging { resources.excludes += "/META-INF/DEPENDENCIES" }
}
dependencies {
implementation("io.github.loki-notfound:zephyr-java-android:2.3.0-sec.2-java.4")
}
The packaging line is required.
httpclient5, httpcore5 and httpcore5-h2 each carry a file META-INF/DEPENDENCIES. Without the exclude the app's build stops in mergeDebugJavaResource with "3 files found with path 'META-INF/DEPENDENCIES'". The file is Maven metadata; nothing reads it at run time.
Android Studio's project template also sets repositoriesMode to FAIL_ON_PROJECT_REPOS in that block. A repositories { } block in the module's build file then stops the build:
Build was configured to prefer settings repositories over project repositories but repository '…' was added by build file '…'
So put the repository line in the settings file.
The same in the Groovy DSL (settings.gradle and app/build.gradle):
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = 'https://loki-notfound.github.io/myzephyr-java/maven' }
}
}
android {
packaging { resources.excludes += '/META-INF/DEPENDENCIES' }
}
dependencies {
implementation 'io.github.loki-notfound:zephyr-java-android:2.3.0-sec.2-java.4'
}
With a version catalog, gradle/libs.versions.toml gets the entry and the module uses implementation(libs.zephyr.java.android) (Groovy: implementation libs.zephyr.java.android):
[versions]
zephyrJava = "2.3.0-sec.2-java.4"
[libraries]
zephyr-java-android = { module = "io.github.loki-notfound:zephyr-java-android", version.ref = "zephyrJava" }
The AAR is published as zephyr-java-android (the JAR for the JVM is zephyr-java). It brings three dependencies: Jackson (jackson-core, jackson-databind, 2.13.5) and the Apache HTTP client 5 (httpclient5 5.2.1, used by the RPC classes). It brings no Kotlin standard library, no Bouncy Castle and no Apache commons-codec. jeromq is compile-only (Dependencies).
Jackson on API 24 and 25#
A newer Jackson breaks API 24 and 25.
The library pins Jackson 2.13.5, the last Jackson line that runs on Android below API 26. Gradle does not report a conflict when your app or another library asks for Jackson 2.14 or newer. The app then fails at run time on API 24 and 25.
Within the 2.13 line, releases before 2.13.5 call Method.getParameterCount(), which Android has only from API 26. Gradle resolves the highest version for the whole app, zephyr-java included, and the build succeeds. On API 26 and newer that is fine: zephyr-java was tested on Jackson 2.21.7 on the JVM, in the coexistence test. Check what the app really gets:
./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep jackson
A line such as jackson-databind:2.13.5 -> 2.21.7 means that another dependency lifted Jackson. Then minSdk 24 and that dependency do not go together. Raise minSdk to 26, or use a version of the other library that stays on Jackson 2.13. On Android zephyr-java has run with 2.13.5 only.
Devices#
- minSdk 24 (Android 7.0). The native wallet,
ZephyrWalletFull, runs from API 24. The RPC classes need API 26 or core library desugaring in the app (The RPC classes below API 26). - ABIs:
arm64-v8a,armeabi-v7aandx86_64. There is no 32-bitx86library. Thearmeabi-v7alibrary is built with zephyr's own-mfpu=vfpv4, so it needs a CPU with VFPv4. Cortex-A8 and A9 cores lack it; every Android 7 device supports it. - 16 KB pages (16 KiB): the libraries are linked for 16 KB page alignment. Google Play requires it for apps that target Android 15 and later. Keep them uncompressed in the APK (
packaging { jniLibs.useLegacyPackaging = false }, the default from minSdk 23). An app built against the AAR with AGP 9.5.0 passeszipalign -c -P 16, with the libraries stored.
Size. The libraries are stored uncompressed, so each ABI adds its library's full size to the APK. The libraries in the 2.3.0-sec.2-java.4 AAR:
| ABI | Bytes | MB | MiB | Compressed inside the AAR |
|---|---|---|---|---|
arm64-v8a | 20,141,000 | 20.14 | 19.21 | 7,484,104 bytes |
armeabi-v7a | 18,019,980 | 18.02 | 17.19 | 7,165,617 bytes |
x86_64 | 23,897,880 | 23.90 | 22.79 | 8,590,609 bytes |
So each ABI adds about 20 MB for arm64-v8a, 18 MB for armeabi-v7a and 24 MB for x86_64. The size of a finished APK or of a Play delivery was not measured.
An app built as an Android App Bundle reaches each device from Google Play with the library of that device's ABI only. The Android documentation, "About Android App Bundles", describes it. An APK you distribute yourself carries every ABI unless you filter them; x86_64 is mostly needed for the emulator:
android {
defaultConfig {
ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
}
}
The x86_64 library ran on the Android emulator; the ARM libraries had not run on hardware by release 2.3.0-sec.2-java.4 (What was tested).
The RPC classes below API 26#
ZephyrDaemonRpc and ZephyrWalletRpc send their requests through the Apache HTTP client, which needs java.time; Android has it from API 26 (8.0). On API 24 and 25 every request throws a ZephyrError with the NoClassDefFoundError in its causes:
The RPC classes need java.time: Android 8.0 (API 26) or newer, or core library desugaring in the app (user guide, chapter 6)
Releases up to 2.3.0-sec.2-java.4 print "chapter 6" in that message; the section it means is this one. Later releases name this section instead.
An app with minSdk 24 or 25 that uses the RPC classes enables core library desugaring in the app module:
android {
compileOptions { isCoreLibraryDesugaringEnabled = true }
}
dependencies {
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}
(Groovy: coreLibraryDesugaringEnabled = true and coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'.) With these two lines ZephyrDaemonRpc runs on API 24. The native wallet, ZephyrWalletFull, does not use the HTTP client and needs neither. The RPC classes covers what they do.
The network#
Permission. The AAR declares no permission. An app that connects to a node declares <uses-permission android:name="android.permission.INTERNET" /> in its manifest.
Clear text. The native wallet and the RPC classes open their own sockets. They do not read the app's Network Security Configuration. On API 35, an app with targetSdk 36 reached an http:// node without any usesCleartextTraffic setting. Android refuses clear text by default for apps that target API 28 and later (Android documentation, "Network security configuration"). But the documentation of android:usesCleartextTraffic notes that the socket API does not honour that flag.
So the configuration neither blocks nor protects these connections. cleartextTrafficPermitted="false" does not stop an http:// node. The configuration's trust anchors and pins do not apply to an https:// node either. The native wallet's root certificates are set with ZephyrTls (TLS to a node).
Storage#
Android apps usually keep their data in the app's private storage or in their own database. Both work:
- Files: give
createWalleta path insidecontext.getFilesDir(). The wallet writes<name>.keysand<name>there onsave(). - Bytes: create the wallet without a path, take
wallet.getData()(keys and cache) and store the two arrays yourself; open later withZephyrWalletFull.openWalletData(...). This suits an encrypted database (Wallet bytes).
Backup#
What Auto Backup does. Android's Auto Backup includes an app's files by default for apps that target API 23 or newer. The files directory and databases go to the user's Google Drive, at most 25 MB per app. A device-to-device transfer copies them too (Android documentation, "Back up user data with Auto Backup").
What ends up in it. Wallet files in getFilesDir(), or the bytes of getData() in a database, are in the backup unless the app excludes them.
What protects it. Both the keys and the cache are encrypted with keys derived from the wallet password, so a backup is as strong as that password. With an empty password anyone who has the backup can open the wallet.
How to keep wallet data out. Whether wallet data belongs in a backup is the app's choice:
android:allowBackup="false"in the manifest turns the cloud backup off. For an app that targets Android 12 or newer, on devices of some manufacturers, it does not stop a device-to-device transfer;android:dataExtractionRules(Android 12 and newer, for apps that target it) includes or excludes single files and directories, for the cloud backup and the device-to-device transfer separately;android:fullBackupContent(Android 11 and lower) includes or excludes them with one set of rules; a rule can require a device-to-device transfer or client-side encryption;- files in
context.getNoBackupFilesDir()are never backed up.
Lifecycle and threads#
A wallet is expensive to open and must be closed exactly once. It belongs to something that outlives an Activity: a ViewModel, a bound service, or an application-wide holder. Close it (after storing it) when that owner ends.
Callbacks arrive on a thread you did not choose (Callbacks run on threads you did not create). Post to the main thread before you touch views, and catch every exception inside the callback (An exception thrown in a callback):
Handler main = new Handler(Looper.getMainLooper());
wallet.addListener(new ZephyrWalletListener() {
@Override
public void onBalancesChanged(BigInteger balance, BigInteger unlocked, String assetType) {
main.post(() -> viewModel.setBalance(assetType, balance, unlocked));
}
});
This block uses Android classes, so it is not compiled with the tests.
While the app is in the background, Android may stop it at any time. Store the wallet when the app goes to the background (onStop), and stop background syncing (stopSyncing()) if you do not need it there. Do not close the wallet while a sync may still run (Closing a wallet that syncs). None of the observations of that section were made on Android.
Logs#
The core has no Android log output: nothing it logs appears in logcat (seen on the emulator, API 24 and API 35). ZephyrUtils.configureNativeLogging(path, false) with a path in context.getFilesDir() would send it to a file; on Android this has not been tried (The native log).
zephyr-java's own messages (ZephyrUtils.setLogLevel(...)) are printed with System.out, and Android shows System.out and System.err in logcat under those tags. Creating the first ZephyrRpcConnection (an RPC class, or a wallet given a server URI) prints three SLF4J lines to System.err. Among them are "Failed to load class org.slf4j.impl.StaticLoggerBinder" and "Defaulting to no-operation (NOP) logger implementation". The Apache HTTP client finds no logging backend and logs nothing. The lines are harmless.
A first test on a device#
Call GuideFirstProgram.smokeTest() (A first program) off the main thread and log the result:
new Thread(() -> Log.i("zephyr", "smoke test: " + GuideFirstProgram.smokeTest())).start();
A mainnet primary address (it starts with ZEPHYR) in logcat means that the device loaded the library of its ABI and the core created a wallet.
The shipped R8 rules#
The AAR's proguard.txt is applied to every app that uses it. It keeps:
- every class with
nativemethods and those methods' names, because the native library binds its exports by class and method name; ZephyrWalletFull$WalletJniListenerwith all members, because the native side looks it up by name and calls its five callbacks by name and signature;- the model packages
zephyr.wallet.model,zephyr.daemon.modelandzephyr.common, because Jackson maps the native JSON onto them by reflection; - annotations and generic signatures, which Jackson reads at run time.
Your own listener classes need no rule: the native side calls the library's listener, which calls yours through ordinary Java.