Zcash iOS 框架

适用于 iOS
的 Zcash 轻量级客户端 SDK 这是一个 alpha 版本，目前正在积极开发中。请注意以下事项：

• 此代码目前未由外部安全审核员审核，使用风险自负
• 该代码尚未经过Electric Coin Company工程师的彻底审查。
• 我们正在积极更改代码库，并在需要时添加功能

?安全警告

• Zcash iOS 钱包 SDK 是实验性的，正在进行中。使用它的风险由您自己承担。
• 使用此 SDK 的开发人员必须熟悉当前的威胁
  模型，尤其是其中描述的已知弱点。

构建依赖项

ZcashLightClientKit 使用一个名为 Librustzcash 的 rust 库。为了构建它，您需要在您的环境中安装锈迹和货物。

按照以下说明安装 Rust 和 Cargo，然后使用以下示例安装和添加相应的体系结构：cargo-liporustup

$ cargo install cargo-lipo
$ rustup target add aarch64-apple-ios x86_64-apple-ios

椰子足类支持

安装 ZcashLightClientKit 作为贡献者

use_frameworks!

pod 'ZcashLightClientKit', :path => '../../', :testspecs => ['Tests']  # include testspecs if you want to run the tests

安装 ZcashLightClientKit 作为钱包应用程序开发人员

use_frameworks!

pod 'ZcashLightClientKit'

Custom build phases warning

When running you will see this warning upon success:pod install

[!] ZcashLightClientKit has added 2 script phases. Please inspect before executing a build. 
See `https://guides.cocoapods.org/syntax/podspec.html#script_phases` for more information.

Integrating Rust code with Swift code and delivering it in a consistent and (build) reproducible way, is hard. We’ve taken the lead to get that burden off your shoulders as much as possible by leveraging the and features from Cocoapods to carefully generate a build for the Rust layer.prepare_commandscript_phases

Build system

This section explains the ‘Build System’ that integrates the rust code and creates the corresponding environment.

Overview

There are some basic steps to build ZcashLightClientKit. Even though they are ‘basic’ they can be cumbersome. So we automated them in scripts.

1. Pod install and prepare_command

ZcashLightClientKit needs files to be present at pod installation time, but that can’t be defined properly yet and depend on librustzcash building properly and for an environment to be set up at build time. For know we just need to let Cocoapods that these files exist:

• ${ZCASH_POD_SRCROOT}/zcashlc/libzcashlc.a this is the librustzcash build .a file itself
• lib/libzcashlc.a (as vendored library that will be added as an asset by xcodeproj)

2. Build Phase

The build Phase scripts executes within the Xcode Build Step and has all the known variables of a traditional build at hand.

s.script_phase = {
      :name => 'Build generate constants and build librustzcash',
      :script => 'sh ${PODS_TARGET_SRCROOT}/Scripts/build_librustzcash_xcode.sh',
      :execution_position => :before_compile
   }

This step will generate files needed on the next steps and build the librustzcash with Xcode but not using cargo’s built-in Xcode integration

** Building librustzcash and integrating it to the pod structure**

Where the magic happens. Here we will make sure that everything is set up properly to start building librustzcash. When on mainnet, the build will append a parameter to include mainnet features.

Scripts

On the Scripts folder you will find the following files:

 | Scripts
 |-/prepare_zcash_sdk.sh
 |-/generate_test_constants.sh
 |-/build_librustzcash_xcode.sh
 |-/build_librustzcash.sh
 |-/script_commons.sh

prepare_zcash_sdk.sh

This script is run by the Cocoapods ‘prepare_command’.

s.prepare_command = <<-CMD
      sh Scripts/prepare_zcash_sdk.sh
    CMD

It basically creates empty files that cocoapods needs to pick up on its pod structure but that are still not present in the file system and that will be generated in later build phases.

NOTE: pod install will only run this phase when no Pods/ folder is present or if your pod hash has changed or is not present on manifest.lock. When in doubt, just clean the Pods/ folder and start over. That usually gets rid of weirdness caused by Xcode caching a lot of stuff you are not aware of.

script_commons.sh

A lot of important environment variables and helper functions live in the .script_commons.sh

Testing

Currently tests depend on a server instance running locally or remotely to pass.
To know more about running , refer to its repo https://github.com/zcash/lightwalletdlightwalletdlightwalletd

Pointing tests to a lightwalletd instance

Tests use to generate a Constants file which injects the server address to the test themselves.Sourcerylightwalletd

Installing sourcery

Refer to the official repo https://github.com/krzysztofzablocki/Sourcery

Setting env-var.sh file to run locally

Create a file called on the project root to create the environment variable on build time.env-var.shLIGHTWALLETD_ADDRESS

export LIGHTWALLETD_ADDRESS="localhost%3a9067"

Integrating with CD/CI

The environment variable can also be added to your shell of choice and will pick it up accordingly.LIGHTWALLETD_ADDRESSxcodebuild

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 (kudos for the naming originality…)Logger

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:

1. have one class conform the protocolLogger
2. inject that logger when creating the Initializer

For more details look the Sample App’s code.AppDelegate

Swiftlint

We don’t like reinventing the wheel, so we gently borrowed swift lint rules from AirBnB which we find pretty cool and reasonable.

Troubleshooting

clean pod install

it’s not necessary to delete the whole Pods/ directory and download all of your dependencies again

1. on your project root, locate the directoryPods/
2. remove ZcashLightClientKit from it
3. clean derived data from Xcode
4. close Xcode
5. run (run –verbose to see more details)pod install
6. open Xcode project
7. build

_function_name referenced from…

if you get a build error similar to _function_name referenced from...

• on your project root directory *

1. remove the ‘Pods’ directory rm -rf Pods/
2. delete derived data and clean
3. run pod install
4. build

can’t find crate for … target may not be installed

This error could be a side effect of having more then one rust toolchain installed.
If you worked with ZcashLightClientKit 0.6.6 or below you might have had to set the compiler to 1.40.0 which can cause this compilation error to happen.
make sure that the directory that you are working on has the correct rust environment.
You can do so by calling in the working directory.rustup show

Building in Apple Silicon

So far we have come up with this set up (april 2021)

• Clone a terminal and run it in rosetta mode
• Clone your Xcode of choice and run it in rosetta mode
• Installing the right toolchain for cargo
  • rustup toolchain add stable-x86_64-apple-darwin
  • rustup target add aarch64-apple-ios x86_64-apple-darwin x86_64-apple-ios

Versioning

This project follows semantic versioning with pre-release versions. An example of a valid version number is denoting the iteration of the pre-release of version . Stable releases, such as will not contain any pre-release identifiers. Pre-releases include the following, in order of stability: , , . 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:1.0.4-alpha1111thalpha1.0.41.0.4alphabetarc

Build Types

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

GitHub

点击跳转