2bbc5800bd
Closes #888. - `ZcashRustBackend` is actor now. So majority of methods in this actor are now async. - Some methods stayed `static` in `ZcashRustBackend`. It would be hard to pass instance of the `ZcashRustBackend` to the places where these methods are used in static manner. And it would change lot of APIs. But it isn't problem from technical perspective because these methods would be `nonisolated` otherwise. - Methods `lastError()` and `getLastError()` in `ZcashRustBackend` are now private. This makes sure that ther won't be aby race condition between other methods and these two error methods. - All the methods for which was `lastError()` used in code now throw error. So `lastError()` is no longer needed outside of the `ZcashRustBackend`. - There are in the public API related to `DerivationTool`. - `DerivationTool` now requires instance of the `ZcashRustBackend`. And `ZcashRustBackend` isn't public type. So `DerivationTool` doesn't have any public constructor now. It can be created only via `Initializer.makeDerivationTool()` instance method. - `deriveUnifiedSpendingKey()` and `deriveUnifiedFullViewingKey()` in `DerivationTool` are now async. It is because these are using `ZcashRustBackend` inside. `DerivationTool` offers alternative (closure and combine) APIs. But downside is that there is no sync API to dervie spending key or viewing key. - Some methods of the `DerivationTool` are now static. These methods don't use anything that requires instance of the `DerivationTool` inside. [#888] Use Sourcery to generate mocks - I wrote mock for `Synchronizer` manually. And it's tedious and long and boring work. - Now `ZcashRustBackendWelding` is changed a lot so it means `MockRustBackend` must be changed a lot. So I decided to introduce `sourcery` to generate mocks from protocols so we don't have to do it manually ever. - To generate mocks go to `ZcashLightClientKit/Tests/TestUtils/Sourcery` directory and run `generateMocks.sh` script. - Your protocol must be mentioned in `AutoMockable.swift` file. Generated mocks are in `AutoMockable.generated.swift` file. [#888] Fix Offline tests - Offline tests target now runs and tests are green. - There is log of changes in tests. But logic is not changed. - Updated `AutoMockable.stencil` so sourcery is able to generate mock as actor when protocol is marked with: `// sourcery: mockActor`. - Last few updates in `ZcashRustBackendWelding`. In previous PR `rewindCacheToHeight` methods was overlooked and it didn't throw error. - Removed `MockRustBackend` and using generated `ZCashRustBackendWeldingMock` instead. - Using generated `SynchronizerMock`. [#888] Fix NetworkTests - Changed a bit how rust backend mock is used in the tests. Introduced `RustBackendMockHelper`. There are some state variables that must be preserved within one instance of the mock. This helper does exactly this. It keeps this state variables in the memory and helping mock to work as expected. [#888] Fix Darkside tests Create ZcashKeyDeriving internal protocol Use New DerivationTool that does not require RustBackend Remove duplicated methods that had been copied over [#888] Fix potentially broken tests I broke the tests because I moved `testTempDirectory` from each `TestCase` to the `Environment`. By this I caused that each tests uses exactly same URL. Which is directly against purpose of `testTempDirectory`. So now each test calls this one and store it to local variable. So each test has unique URL. [#888] Add ability to mock nonisolated methods to AutoMockable.stencil [#888] Add changelog and fix the documentation in ZcashRustBackendWelding [#888] Rename derivation rust backend protocol and remove static methods - Renamed `ZcashKeyDeriving` to `ZcashKeyDerivationBackendWelding`. So the naming scheme is same as for `ZcashRustBackendWelding`. - `ZcashKeyDerivationBackend` is now struct instead of enum. - Methods in `ZcashKeyDerivationBackendWelding` (except one) are no longer static. Because of this the respective methods in `DerivationTool` aren't also static anymore. |
||
|---|---|---|
| .github | ||
| Example/ZcashLightClientSample | ||
| Sources/ZcashLightClientKit | ||
| Tests | ||
| docs | ||
| .gitignore | ||
| .swiftlint.yml | ||
| .swiftlint_tests.yml | ||
| .travis.yml | ||
| CHANGELOG.md | ||
| CODE_REVIEW_GUIDELINES.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| MIGRATING.md | ||
| Package.resolved | ||
| Package.swift | ||
| README.md | ||
| SWIFTLINT.md | ||
| responsible_disclosure.md | ||
| zcash.swiftformat | ||
README.md
Zcash iOS Framework
A Zcash Lightweight Client SDK for iOS This is an alpha 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 iOS 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.
Installation
Swift Package Manager
Add a package with the source "https://github.com/zcash/ZcashLightClientKit.git" and from version 0.14.0-beta onwards in either Xcode's GUI or in your Package.swift file.
Beta version support for Xcode projects
If you want to include a beta version of ZCashLightClientKit in an Xcode project e.g 0.14.0-beta you will need to specify it with the commit sha instead as it does not appear that Xcode supports 'meta data' from semantic version strings for swift packages (at the time of writing).
Testing
The best way to run tests is to open "Package.swift" in Xcode and use the Test panel and target an iOS device. Tests will build and run for a Mac target but are not currently working as expected.
There are three test targets grouped by external requirements:
OfflineTests- No external requirements.
NetworkTests- Require an active internet connection.
DarksideTests- Require an instance of
lightwalletdto be running while the tests are being run, see below for some information on how to set up. (Darkside refers to a mode in lightwalletd that allows it to be updated to represent/mock different states of the underlying blockchain.)
- Require an instance of
lightwalletd
The DarksideTests test target depend on a lightwalletd server instance running locally (or remotely). For convenience, we have added a universal (Mac) lightwalletd binary (in `Tests/lightwalletd/lightwalletd) and it can be run locally for use by the tests with the following command:
Tests/lightwalletd/lightwalletd --no-tls-very-insecure --data-dir /tmp --darkside-very-insecure --log-file /dev/stdout
You can find out more about running lightwalletd, from the main repo https://github.com/zcash/lightwalletd.
Integrating with CD/CI
The LIGHTWALLETD_ADDRESS environment variable can also be added to your shell of choice and xcodebuild will pick it up accordingly.
We advise setting this value as a secret variable on your CD/CI environment when possible.
Integrating with logging tools
There are a lots of good logging tools for iOS. So we'll leave that choice to you. ZcashLightClientKit relies on a simple protocol to bubble up logs to client applications, which is called Logger (kudos for the naming originality...)
public protocol Logger {
func debug(_ message: String, file: String, function: String, line: Int)
func info(_ message: String, file: String, function: String, line: Int)
func event(_ message: String, file: String, function: String, line: Int)
func warn(_ message: String, file: String, function: String, line: Int)
func error(_ message: String, file: String, function: String, line: Int)
}
To enable logging you need to do 2 simple steps:
- have one class conform the
Loggerprotocol - inject that logger when creating the
Initializer
For more details look the Sample App's AppDelegate code.
Swiftlint
We don't like reinventing the wheel, so we gently borrowed swift lint rules from AirBnB which we find pretty cool and reasonable.
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
This repo contains demos of isolated functionality that this SDK provides. They can be found in the examples folder.
Examples can be found in the Demo App.
License
MIT