8.6 KiB
This is a beta build and is currently under active development. Please be advised of the following:
- This code currently is not audited by an external security auditor, use it at your own risk
- The code has not been subjected to thorough review by engineers at the Electric Coin Company
- We are actively changing the codebase and adding features where/when needed
- The code is not yet published (to Bintray/Maven Central)
🔒 Security Warnings
- The Zcash Android Wallet SDK is experimental and a work in progress. Use it at your own risk.
- Developers using this SDK must familiarize themselves with the current threat model, especially the known weaknesses described there.
Zcash Android SDK
This lightweight SDK connects Android to Zcash. It welds together Rust and Kotlin in a minimal way, allowing third-party Android apps to send and receive shielded transactions easily, securely and privately.
Contents
Requirements
This SDK is designed to work using a custom block server lightwalletd
Structure
From an app developer's perspective, this SDK will encapsulate the most complex aspects of using Zcash, freeing the developer to focus on UI and UX, rather than scanning blockchains and building commitment trees! Internally, the SDK is structured as follows:
Thankfully, the only thing an app developer has to be concerned with is the following:
Overview
At a high level, this SDK simply helps native Android codebases connect to Zcash's Rust crypto libraries without needing to know Rust or be a Cryptographer. Think of it as welding. The SDK takes separate things and tightly bonds them together such that each can remain as idiomatic as possible. Its goal is to make it easy for an app to incorporate shielded transactions while remaining a good citizen on mobile devices.
Given all the moving parts, making things easy requires coordination. The Synchronizer provides that layer of abstraction so that the primary steps to make use of this SDK are simply:
- Start the Synchronizer
- Subscribe to wallet data
The Synchronizer takes care of
- Connecting to the light wallet server
- Downloading the latest compact blocks in a privacy-sensitive way
- Scanning and trial decrypting those blocks for shielded transactions related to the wallet
- Processing those related transactions into useful data for the UI
- Sending payments to a full node through the light wallet server
- Monitoring sent payments for status updates
To accomplish this, these responsibilities of the SDK are divided into separate components. Each component is coordinated by the Synchronizer, which is the thread that ties it all together.
Components
Component | Summary |
---|---|
LightWalletService | Service used for requesting compact blocks |
CompactBlockStore | Stores compact blocks that have been downloaded from the LightWalletService |
CompactBlockProcessor | Validates and scans the compact blocks in the CompactBlockStore for transaction details |
OutboundTransactionManager | Creates, Submits and manages transactions for spending funds |
Initializer | Responsible for all setup that must happen before synchronization can begin. Loads the rust library and helps with key derivation. |
RustBackend | Wraps the rust library and exposes its functionality to the Kotlin SDK |
Quickstart
Add the SDK dependency
implementation "cash.z.android.wallet:zcash-android-testnet:1.0.0-alpha01@aar"
Start the Synchronizer
synchronizer.start(this)
Get the wallet's address
synchronizer.getAddress()
Send funds to another address
synchronizer.sendToAddress(spendingKey, zatoshi, address, memo)
Compiling Sources
⚠️ Compilation is not required unless you plan to submit a patch or fork the code. Instead, it is recommended to simply add the SDK dependencies via gradle.
In the event that you do want to compile the SDK from sources, follow these steps:
- Install rust
- Then, add the android targets via:
rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android
- Clone this repo
- Install android studio and open this project via
/your/path/to/zcash-android-wallet-sdk/build.gradle
- Open Android Studio’s SDK manager
- Then, install NDK 20.0.5594570
- Create an emulator if you don’t already have one (recommended target: API 29)
- Select your desired build variant. Currently, we recommend
zcashmainnetDebug
as the testnet variants are slower to sync to current height due to a lack of checkpoints.
- Sync project with Gradle files, and build from the IDE. Alternatively, to build from the command line run:
./gradlew clean assembleZcashmainnetDebug
This creates a build of the SDK under build/outputs/aar/
that can be used to preview functionality. For more detailed examples, checkout the demo app. Note that merely using the SDK does not require installing Rust or Cargo--that is only required when compiling from source.
Versioning
This project follows semantic versioning with pre-release versions. An example of a valid version number is 1.0.4-alpha11
denoting the 11th
iteration of the alpha
pre-release of version 1.0.4
. Stable releases, such as 1.0.4
will not contain any pre-release identifiers. Pre-releases include the following, in order of stability: alpha
, beta
, rc
. Version codes offer a numeric representation of the build name that always increases. The first six significant digits represent the major, minor and patch number (two digits each) and the last 3 significant digits represent the pre-release identifier. The first digit of the identifier signals the build type. Lastly, each new build has a higher version code than all previous builds. The following table breaks this down:
Build Types
Type | Purpose | Stability | Audience | Identifier | Example Version |
---|---|---|---|---|---|
alpha | Sandbox. For developers to verify behavior and try features. Things seen here might never go to production. Most bugs here can be ignored. | Unstable: Expect bugs | Internal developers | 0XX | 1.2.3-alpha04 (10203004) |
beta | Hand-off. For developers to present finished features. Bugs found here should be reported and immediately addressed, if they relate to recent changes. | Unstable: Report bugs | Internal stakeholders | 2XX | 1.2.3-beta04 (10203204) |
release candidate | Hardening. Final testing for an app release that we believe is ready to go live. The focus here is regression testing to ensure that new changes have not introduced instability in areas that were previously working. | Stable: Hunt for bugs | External testers | 4XX | 1.2.3-rc04 (10203404) |
production | Delivery. Deliver new features to end users. Any bugs found here need to be prioritized. Some will require immediate attention but most can be worked into a future release. | Stable: Prioritize bugs | Public | 8XX | 1.2.3 (10203800) |
Examples
Examples can be found in the Demo App