Update README for first versioned release
This commit is contained in:
Bradley Miller
parent
0c60dbab5e
commit
7bde72f11f
94
README.md
94
README.md
|
|
@ -1,42 +1,15 @@
|
|||
# Security Disclaimer
|
||||
This is an alpha build and is currently under active development. Please be advised of the following:
|
||||
|
||||
#### :warning: WARNING: This is an *early preview* under active development and *anything may change at anytime!*
|
||||
- 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
|
||||
|
||||
In the spirit of transparency, we provide this as a window into what we are actively developing. This is an alpha build, not yet intended for 3rd party use. Please be advised of the following:
|
||||
The Zcash Android Wallet SDK is experimental and a work in progress. Use it at your own risk.
|
||||
|
||||
* 🛑 This code currently is not audited 🛑
|
||||
* ❌ This is a public, active branch with **no support**
|
||||
* ❌ The code **does not have** documentation that is reviewed and approved by our Documentation team
|
||||
* ❌ The code **does not have** adequate unit tests, acceptance tests and stress tests
|
||||
* ❌ The code **does not have** automated tests that use the officially supported CI system
|
||||
* ❌ The code **has not been subjected to thorough review** by engineers at the Electric Coin Company
|
||||
* ❌ This product **does not run** compatibly with the latest version of zcashd
|
||||
* ❌ The product **is** majorly broken in several ways including:
|
||||
* master seed management is left to the 3rd party wallet developer (beacause that's what wallets do best)
|
||||
* secure spending key management is left to the 3rd party wallet developer
|
||||
* ❌ The library **only runs** on testnet
|
||||
* ❌ The library **does not run** on mainnet and **cannot** run on regtest
|
||||
* ❌ We **are actively changing** the codebase and adding features where/when needed
|
||||
* ❌ We **do not** undertake appropriate security coverage (threat models, review, response, etc.)
|
||||
* :heavy_check_mark: There is a product manager for this library
|
||||
* :heavy_check_mark: Electric Coin Company maintains the library as we discover bugs and do network upgrades/minor releases
|
||||
* :heavy_check_mark: Users can expect to get a response within a few weeks after submitting an issue
|
||||
* ❌ The User Support team **had not yet been briefed** on the features provided to users and the functionality of the associated test-framework
|
||||
* ❌ The code is **unpolished**
|
||||
* ❌ The code is **not documented**
|
||||
* ❌ The code **is not yet published** (to Bintray/Maven Central)
|
||||
* ❌ Requires external lightwalletd server
|
||||
|
||||
|
||||
### 🛑 Use of this code may lead to a loss of funds 🛑
|
||||
|
||||
Use of this code in its current form or with modifications may lead to loss of funds, loss of "expected" privacy, or denial of service for a large portion of users, or a bug which could leverage any of those kinds of attacks (especially a "0 day" where we suspect few people know about the vulnerability).
|
||||
|
||||
### :eyes: At this time, this is for preview purposes only. :eyes:
|
||||
|
||||
----
|
||||
---
|
||||
|
||||
# Zcash Android SDK
|
||||
|
||||
|
|
@ -46,32 +19,37 @@ This lightweight SDK connects Android to Zcash. It welds together Rust and Kotli
|
|||
|
||||
- [Structure](#structure)
|
||||
- [Overview](#overview)
|
||||
- [Components](#components)
|
||||
- [Components](#components)
|
||||
- [Quickstart](#quickstart)
|
||||
- [Compiling Sources](#compiling-sources)
|
||||
- [Versioning](#versioning)
|
||||
- [Examples](#examples)
|
||||
|
||||
## Requirements
|
||||
|
||||
This SDK is designed to work using a custom block server [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:
|
||||
|
||||
|
||||
|
||||
|
||||
Thankfully, the only thing an app developer has to be concerned with is the following:
|
||||
|
||||
|
||||
|
||||
|
||||
[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. It's goal is to make it easy for an app to incorporate shielded transactions while remaining a good citizen on mobile devices.
|
||||
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. It's 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
|
||||
|
||||
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
|
||||
|
|
@ -85,39 +63,47 @@ To accomplish this, these responsibilities of the SDK are divided into separate
|
|||
|
||||
#### Components
|
||||
|
||||
| Component | Summary |
|
||||
| :--------- | :------ |
|
||||
| **LightWalletService** | Service used for requesting compact blocks |
|
||||
| **CompactBlockStore** | Stores compact blocks that have been downloaded from the `LightWalletService` |
|
||||
| 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 |
|
||||
| **TransactionManager** | Creates, Submits and manages transactions for spending funds |
|
||||
| **Wallet** | Wraps the Zcash rust libraries, insulating SDK users from changes in that layer |
|
||||
| **TransactionManager** | Creates, Submits and manages transactions for spending funds |
|
||||
| **Wallet** | Wraps the Zcash rust libraries, insulating SDK users from changes in that layer |
|
||||
|
||||
[Back to contents](#contents)
|
||||
|
||||
## Quickstart
|
||||
|
||||
Add the SDK dependency
|
||||
|
||||
```gradle
|
||||
implementation "cash.z.android.wallet:zcash-android-testnet:1.0.0-alpha01@aar"
|
||||
```
|
||||
|
||||
Start the [Synchronizer](docs/-synchronizer/README.md)
|
||||
|
||||
```kotlin
|
||||
synchronizer.start(this)
|
||||
```
|
||||
|
||||
Get the wallet's address
|
||||
|
||||
```kotlin
|
||||
synchronizer.getAddress()
|
||||
```
|
||||
|
||||
Send funds to another address
|
||||
|
||||
```kotlin
|
||||
synchronizer.sendToAddress(zatoshi, address, memo)
|
||||
```
|
||||
|
||||
[Back to contents](#contents)
|
||||
|
||||
## Compiling Sources
|
||||
|
||||
:warning: Presently, the latest stable code lives in the `preview` branch, under active development, and is not yet released.
|
||||
:warning: Presently, the latest stable code lives in the `preview` branch, under active development, and is not yet released.
|
||||
|
||||
Importing the dependency should be enough for use but in the event that you want to compile the SDK from sources, including the Kotlin and Rust portions, simply use Gradle.
|
||||
|
||||
|
|
@ -126,15 +112,17 @@ Compilation requires `Cargo` and has been tested on Ubuntu, MacOS and Windows. T
|
|||
```bash
|
||||
./gradlew clean assembleZcashtestnetRelease
|
||||
```
|
||||
|
||||
This creates a `testnet` build of the SDK that can be used to preview basic functionality for sending and receiving shielded transactions. If you do not have `Rust` and `Cargo` installed, the build script will let you know and provide further instructions for installation. Note that merely using the SDK does not require installing Rust or Cargo--that is only required for compilation.
|
||||
|
||||
|
||||
[Back to contents](#contents)
|
||||
|
||||
## Versioning
|
||||
|
||||
This project follows [semantic versioning](https://semver.org/) 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) |
|
||||
|
|
@ -143,3 +131,9 @@ This project follows [semantic versioning](https://semver.org/) with pre-release
|
|||
| **production** | **Dellivery.** 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) |
|
||||
|
||||
[Back to contents](#contents)
|
||||
|
||||
## Examples
|
||||
|
||||
Examples can be found in the [Demo App](/samples/demo-app)
|
||||
|
||||
[Back to contents](#contents)
|
||||
|
|
|
|||
Loading…
Reference in New Issue