[![license](https://img.shields.io/github/license/zcash/zcash-android-wallet-sdk.svg?maxAge=2592000&style=plastic)](https://github.com/zcash/zcash-android-wallet-sdk/blob/master/LICENSE) [![@gmale](https://img.shields.io/badge/contact-android@z.cash-5AA9E7.svg?style=plastic)](https://github.com/gmale) ![Maven Central](https://img.shields.io/maven-central/v/cash.z.ecc.android/zcash-android-sdk?color=success&style=plastic) 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 🔒 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](https://zcash.readthedocs.io/en/latest/rtd_pages/wallet_threat_model.html), 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](#requirements) - [Structure](#structure) - [Overview](#overview) - [Components](#components) - [Quickstart](#quickstart) - [Examples](#examples) - [Compiling Sources](#compiling-sources) - [Versioning](#versioning) - [Examples](#examples) ## Requirements This SDK is designed to work with [lightwalletd](https://github.com/zcash-hackworks/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: ![SDK Diagram](assets/sdk_diagram_final.png?raw=true "SDK Diagram") Thankfully, the only thing an app developer has to be concerned with is the following: ![SDK Diagram Developer Perspective](assets/sdk_dev_pov_final.png?raw=true "SDK Diagram Dev PoV") [Back to contents](#contents) ## 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](docs/-synchronizer/README.md) provides that layer of abstraction so that the primary steps to make use of this SDK are simply: 1. Start the [Synchronizer](docs/-synchronizer/README.md) 2. Subscribe to wallet data The [Synchronizer](docs/-synchronizer/README.md) 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 [lightwalletd](https://github.com/zcash/lightwalletd) - 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](docs/-synchronizer/README.md), 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 initialize databases. | | **DerivationTool**, **BirthdayTool** | Utilities for deriving keys, addresses and loading wallet checkpoints, called "birthdays." | | **RustBackend** | Wraps and simplifies the rust library and exposes its functionality to the Kotlin SDK | [Back to contents](#contents) ## Quickstart Add flavors for testnet v mainnet. Since `productFlavors` cannot start with the word 'test' we recommend: ```groovy flavorDimensions 'network' productFlavors { // would rather name them "testnet" and "mainnet" but product flavor names cannot start with the word "test" zcashtestnet { dimension 'network' matchingFallbacks = ['zcashtestnet', 'debug'] } zcashmainnet { dimension 'network' matchingFallbacks = ['zcashmainnet', 'release'] } } ``` Add the SDK dependency: ```groovy implementation 'cash.z.ecc.android:zcash-android-sdk:1.3.0-beta20' ``` Start the [Synchronizer](docs/-synchronizer/README.md) ```kotlin synchronizer.start(this) ``` Get the wallet's address ```kotlin synchronizer.getAddress() // or alternatively DerivationTool.deriveShieldedAddress(viewingKey) ``` Send funds to another address ```kotlin synchronizer.sendToAddress(spendingKey, zatoshi, address, memo) ``` [Back to contents](#contents) ## Examples Full working examples can be found in the [demo app](demo-app), covering all major functionality of the SDK. Each demo strives to be self-contained so that a developer can understand everything required for it to work. Testnet builds of the demo app will soon be available to [download as github releases](https://github.com/zcash/zcash-android-wallet-sdk/releases). ### Demos Menu Item|Related Code|Description :-----|:-----|:----- Get Private Key|[GetPrivateKeyFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getprivatekey/GetPrivateKeyFragment.kt)|Given a seed, display its viewing key and spending key Get Address|[GetAddressFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getaddress/GetAddressFragment.kt)|Given a seed, display its z-addr Get Balance|[GetBalanceFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getbalance/GetBalanceFragment.kt)|Display the balance Get Latest Height|[GetLatestHeightFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getlatestheight/GetLatestHeightFragment.kt)|Given a lightwalletd server, retrieve the latest block height Get Block|[GetBlockFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getblock/GetBlockFragment.kt)|Given a lightwalletd server, retrieve a compact block Get Block Range|[GetBlockRangeFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/getblockrange/GetBlockRangeFragment.kt)|Given a lightwalletd server, retrieve a range of compact blocks List Transactions|[ListTransactionsFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/listtransactions/ListTransactionsFragment.kt)|Given a seed, list all related shielded transactions Send|[SendFragment.kt](demo-app/src/main/java/cash/z/ecc/android/sdk/demoapp/demos/send/SendFragment.kt)|Send and monitor a transaction, the most complex demo [Back to contents](#contents) ## Compiling Sources :warning: 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: 1. [Install rust](https://www.rust-lang.org/learn/get-started) 1. If you're a macOS user with homebrew already installed 1. `brew install rustup` 1. `rustup-init` 2. Then, add the android targets via: ```bash rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android ``` 3. Clone this repo 4. [Install Android Studio](https://developer.android.com/studio/install) and open this project via `/your/path/to/zcash-android-wallet-sdk/build.gradle.kts` 5. Open Android Studio’s SDK manager