EOSIO SDK for Swift

EOSIO SDK for Swift 是一套用于与基于 EOSIO 的区块链集成的组件。它包含

EosioSwift，与基于 EOSIO 的区块链进行通信和交易的核心组件，使用 EOSIO RPC API。
ABIEOS 序列化提供者，一个用于 EosioSwift 的可插入序列化提供者。序列化提供者负责在 JSON 和二进制数据表示之间通过 ABI 驱动的交易和操作的序列化和反序列化。这个特定的序列化提供者包装了 ABIEOS，这是一个促进这种转换的 C/C++ 库。
ECC，用于处理公钥和私钥、加密签名、加密/解密等的组件。
Softkey 签名提供者，一个示例可插入签名提供者。它允许使用内存中的 K1 密钥进行交易签名。

迄今为止，EOSIO SDK for Swift 仅在 iOS 上进行过测试。然而，目标是在 Swift 运行的任何地方运行核心库，随着库的成熟，添加其他目标（macOS，watchOS，tvOS）。

所有产品和公司名称都是其各自持有者的商标™ 或注册® 商标。使用它们并不表示与它们有任何关联或认可。

先决条件

Xcode 11 或更高版本
CocoaPods 1.9.3 或更高版本或
Swift 包管理器 (SPM) 5.2 或更高版本
对于 iOS，iOS 12+

安装

Swift 包管理器

根据您希望使用的组件，系统将为您安装适当的依赖项。例如，如果您希望使用 EosioSwiftAbieosSerializationProvider，那么还将安装主要的 EosioSwift 组件。

如果您想使用所有组件，请将 https://github.com/EOSIO/eosio-swift 中的 EosioSwift、EosioSwiftAbieosSerializationProvider、EosioSwiftEcc 和 EosioSwiftSoftkeySignatureProvider 产品添加到您的应用程序依赖项中。

或者要将它包含到库中，请将以下内容添加到您的 Package.swift 定义中

// swift-tools-version:5.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "MyName",
    platforms: [
        .iOS(.v12)
    ],
    products: [
        // Products define the executables and libraries produced by a package, and make them visible to other packages.
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(name: "EosioSwift", url: "https://github.com/EOSIO/eosio-swift", from: "1.0.0"))
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
        .target(
            name: "MyLibrary",
            dependencies: [
                .product(name: "EosioSwift", package: "EosioSwift"),
                .product(name: "EosioSwiftAbieosSerializationProvider", package: "EosioSwift"),
                .product(name: "EosioSwiftEcc", package: "EosioSwift"),
                .product(name: "EosioSwiftSoftkeySignatureProvider", package: "EosioSwift"),
        ]),
        .testTarget(
            name: "MyLibraryTests",
            dependencies: ["MyLibrary"]),
    ]
)

从技术角度讲，在完整定义中，不必将所有组件都指定为依赖项，因为 EosioSwiftSoftkeySignatureProvider 依赖于 EosioSwiftEcc 和 EosioSwift 并且会自动包含它们，但为了演示目的，这里列出了所有产品。

如果您只想使用一些组件，您可以在目标的产品名称定义中删除不需要的依赖项。

CocoaPods

EOSIO SDK for Swift 的所有组件在 Cocoapods 中均作为 subspec 分离。如果您安装了 EOSIO SDK for Swift 的整个 pod，您将获得主要的 EosioSwift API、ABIEOS 序列化提供程序、ECC 和软密钥签名提供程序。为此，请将以下内容添加到您的 Podfile

use_frameworks!

target "Your Target" do
  pod "EosioSwift", "~> 1.0.0"
end

然后运行 pod install。现在您就准备好进行基本使用示例了！

如果您只想使用某些组件，请将以下列表中的子规格添加到您的 Podfile

use_frameworks!

target "Your Target" do
  pod "EosioSwift/Core", "~> 1.0.0" # The main Eosio Swift API
  pod "EosioSwift/AbieosSerializationProvider", "~> 1.0.0" # serialization provider
  pod "EosioSwift/Ecc", "~> 1.0.0" # ECC, mostly a dependency, normally do not need to specify
  pod "EosioSwift/SoftkeySignatureProvider", "~> 1.0.0" # experimental signature provider for development only

end

然后运行 pod install。现在您就准备好进行基本使用示例了！

基本使用

处理事务

事务以EosioTransaction形式实例化，并在使用前必须配置多个提供者。（有关提供者的更多信息，请参阅下面的提供者协议架构。）

import EosioSwift
import EosioSwiftAbieosSerializationProvider
import EosioSwiftSoftkeySignatureProvider

然后，在do...catch或抛出函数中，执行以下操作

let transaction = EosioTransaction()
transaction.rpcProvider = EosioRpcProvider(endpoint: URL(string: "https://:8888")!)
transaction.serializationProvider = EosioAbieosSerializationProvider()
transaction.signatureProvider = try EosioSoftkeySignatureProvider(privateKeys: ["yourPrivateKey"])

/// Actions can now be added to the transaction, which can, in turn, be signed and broadcast:

let action = try EosioTransaction.Action(
    account: EosioName("eosio.token"),
    name: EosioName("transfer"),
    authorization: [EosioTransaction.Action.Authorization(
        actor: EosioName("useraaaaaaaa"),
        permission: EosioName("active"))
    ],
    data: Transfer(
        from: EosioName("useraaaaaaaa"),
        to: EosioName("useraaaaaaab"),
        quantity: "42.0000 SYS",
        memo: "")
)

transaction.add(action: action)

transaction.signAndBroadcast { (result) in
    switch result {
    case .failure (let error):
        // Handle error.
    case .success:
        // Handle success.
    }
}

从版本1.0开始，可以将事务配置为使用最后一个不可逆块而不是链的当前头块的blocksBehind块。还可以调整blocksBehind或expireSeconds的数值。这是通过在调用prepare、sign或signAndBroadcast之前修改Transaction.Config来实现的。当useLastIrreversible为真时，则忽略blocksBehind。默认情况下，Transaction.Config将useLastIrreversible设置为true，以帮助在某些条件下最小化事务的微分叉。

let transaction = EosioTransaction()
transaction.rpcProvider = EosioRpcProvider(endpoint: URL(string: "https://:8888")!)
transaction.serializationProvider = EosioAbieosSerializationProvider()
transaction.signatureProvider = try EosioSoftkeySignatureProvider(privateKeys: ["yourPrivateKey"])

// Modify the transaction configuration.
transaction.config.useLastIrreversible = false

// Modify expireSeconds if desired.
transaction.config.expireSeconds = 60 * 8

// Add actions, sign, broadcast etc. as shown above...

事务工厂

或者，为了避免在每次事务上设置提供者，可以使用以下EosioTransactionFactory便捷类

let rpcProvider = EosioRpcProvider(endpoint: URL(string: "https://:8888")!)
let signatureProvider = try EosioSoftkeySignatureProvider(privateKeys: ["yourPrivateKey"])
let serializationProvider = EosioAbieosSerializationProvider()

let myTestnet = EosioTransactionFactory(rpcProvider: rpcProvider, signatureProvider: signatureProvider, serializationProvider: serializationProvider)

let transaction = myTestnet.newTransaction()
// add actions, sign and broadcast!

let anotherTransaction = myTestnet.newTransaction()
// add actions, sign and broadcast!
...

与PromiseKit一起使用

如果您要求EosioTransaction和RPC端点方法提供Promises，大多数会返回Promise。只需将.promise作为第一个参数调用方法，并删除回调。例如

firstly {
    transaction.signAndBroadcast(.promise)
}.done { _ in
    // Handle success.
}.catch { error in
    // Handle error.
}

ABIEOS 序列化提供者使用

如果需要直接使用 ABIEOS 序列化提供者，可以像这样调用其公共方法

let abieos: EosioAbieosSerializationProvider? = EosioAbieosSerializationProvider()
let hex = "1686755CA99DE8E73E1200" // some binary data
let json = "{"name": "John"}" // some JSON

let jsonToBinaryTransaction = try? abieos?.serializeTransaction(json: json)
let binaryToJsonTransaction = try? abieos?.deserializeTransaction(hex: hex)

ECC 使用

ECC 提供以下方法，等等。随着更多方法的添加，这个列表将会扩展。

EosioEccSign.signWithK1(...)：使用 K1 密钥对 EOSIO 链进行验证加载数据。
EccRecoverKey.recoverPublicKey(...)：从私钥或签名和消息中恢复公钥。
EccRecoverKey.recid(...)：获取签名、消息和目标公钥的恢复 ID。

软密钥签名提供者使用

重要：软密钥签名提供者在内存中存储密钥，因此不安全。它仅应用于开发目的。在生产环境中，我们强烈建议使用与安全保险库、验证器或钱包接口的签名提供者，例如来自 EOSIO Swift SDK：保险库的 Vault 签名提供者。

通常，签名提供者在签名过程中被 EosioTransaction 调用。（请在此处查看示例。）但是，如果您发现需要获取可用密钥或直接请求签名，可以通过以下方式调用此库：

let signProvider = try? EosioSoftkeySignatureProvider(privateKeys: privateKeysArray)
let publicKeysArray = signProvider?.getAvailableKeys() // Returns the public keys.

要签署 EosioTransaction，创建一个 EosioTransactionSignatureRequest 对象，并使用请求调用 EosioSoftkeySignatureProvider.signTransaction(request:completion:) 方法。

var signRequest = EosioTransactionSignatureRequest()
signRequest.serializedTransaction = serializedTransaction
signRequest.publicKeys = publicKeys
signRequest.chainId = chainId

signProvider.signTransaction(request: signRequest) { (response) in
    ...
}

密钥管理和签名工具

密钥生成和管理以及其他签名功能可以在 EOSIO Swift SDK：保险库库中找到。

其他代码示例

更多示例可以在EXAMPLES.md文档中找到。

iOS 示例应用

如果您想查看EOSIO SDK for Swift的实际应用，请查看我们的开源iOS 示例应用——一个可以从账户中检索代币余额并执行转账操作的工作应用。

代码文档

请参考生成的代码文档https://eosio.github.io/eosio-swift/，或者通过克隆此仓库并在浏览器中打开以下文件查看

docs/EosioSwift/index.html
docs/EosioSwiftAbieosSerializationProvider/index.html
docs/EosioSwiftEcc/index.html
docs/EosioSwiftSoftkeySignatureProvider/index.html

可以通过在仓库中运行update_documentation.sh脚本来重新生成或更新文档。

提供者协议架构

核心EOSIO SDK for Swift库使用提供者协议驱动的架构，以在多种环境和用例中提供最大灵活性。《EosioTransaction》利用这些提供者来准备和处理交易。EOSIO SDK for Swift公开了四个协议。您，作为开发者，可以选择使用哪些符合的实现对齐进行操作。

签名提供者协议

签名提供者抽象可能是EOSIO SDK for Swift中所有提供者中最有用的一种。它负责...

找出可用于签名的密钥（getAvailableKeys），以及
使用可用密钥子集请求和获取交易签名（signTransaction）。

通过简单地切换交易上的签名提供程序，签名请求可以以多种方式被路由。需要软件签名？请使用配置EosioTransaction 并 Softkey Signature Provider 签名提供程序。想要从平台密钥库或安全加密环境中获取签名？请查看 Vault Signature Provider 。需要从用户设备上的钱包获取签名？签名提供程序也能做到！

所有签名提供程序都必须遵守 EosioSignatureProviderProtocol 协议。

EOSIO SDK for Swift 包含签名提供程序实现；EosioSoftkeySignatureProvider，这是一个用于在内存中使用 K1 密钥签名的示例签名提供程序。此签名提供程序将密钥存储在内存中，因此不安全。它仅应用于开发目的。在生产环境中，我们强烈建议使用与安全保险库、身份验证器或钱包接口的签名提供程序。

虽然可以使用 EosioSoftkeySignatureProvider，但为了签名交易使用密钥库中或设备安全加密环境中存储的密钥，强烈推荐使用 Vault Signature Provider。

RPC提供程序协议

RPC提供程序负责所有对nodeos的RPC调用，以及一般网络处理（可达性，重试逻辑等）。虽然EOSIO SDK for Swift 包含 RPC提供程序实现，但在创建EosioTransaction时必须明确设置，因为它必须使用端点实例化。（默认实现适用于大多数用例。）

EosioRpcProviderProtocol - 所有RPC提供程序都必须遵守此协议。
EosioRpcProvider 默认实现 - 包含在 EOSIO SDK for Swift 中的默认RPC提供程序实现。
Nodeos RPC参考文档 - Nodeos RPC参考。

序列化提供程序协议

序列化提供程序负责通过ABI在JSON和二进制数据表示之间进行交易和操作的序列化和反序列化。这些实现通常包含平台相关的C++代码和较大的依赖项。EOSIO SDK for Swift 包含序列化提供程序实现。

EosioSerializationProviderProtocol - 所有序列化提供程序都必须遵守此协议。
EosioAbieosSerializationProvider - 使用 ABIEOS 进行序列化和反序列化。目前支持 iOS 12 及以上版本。

ABI 提供者协议

ABI 提供者负责获取和缓存 ABIs 以供序列化和反序列化期间使用。如果未在 EosioTransaction 上显式设置，则将使用默认的 EosioAbiProvider。（默认实现适用于大多数使用场景。）

EosioAbiProviderProtocol - 所有 ABI 提供者都必须遵守此协议。
EosioAbiProvider 默认实现 - 包含在 EOSIO SDK for Swift 中的默认 ABI 提供者实现。

RPC：使用默认 RPC 提供者

EOSIO Swift 包含了用于通过 EOSIO RPC API 与 EOSIO 节点通信的默认 RPC 提供者实现（EosioRpcProvider）。如果提供者符合最小化的 EosioRpcProviderProtocol，则可以使用其他 RPC 提供者。EOSIO SDK for Swift 核心库仅依赖于该协议中规定的六个 RPC 端点的五个。 pushTransaction 已不再由核心库使用，但保留以支持向后兼容。但是，其他端点在默认的 EosioRpcProvider 中都已经暴露。

可以像以下这样调用任何可用的端点：

rpcProvider.getInfo { (infoResponse) in
    switch infoResponse {
    case .failure(let error):
        // handle the error
    }
    case .success(let info) {
        // do stuff with the info!
        print(info.chainId)
    }
}

尝试将响应转换为方便的 Swift 结构体。更深层次的响应属性可能以字典的形式表示。

每个响应结构体还将包含一个 _rawResponse 属性。如果在返回的结构体中缺少您期望从响应中获取的属性，请检查 _rawResponse。您可能会在那里找到它。

响应结构体目前还不完整。一些响应将仅返回 _rawResponse。我们旨在继续改进响应序列化。我们也欢迎您帮助我们改进响应。

想要帮助？

有兴趣贡献？太棒了！这里有贡献指南和行为准则。

我们一直在寻找改进 EOSIO SDK for Swift 的方法。请查看我们#enhancement Issues，了解您如何参与其中。

许可证

MIT

重要

有关版权和许可证条款，请参阅LICENSE。作为EOSIO社区的成员，Block.one自愿贡献并不对软件或任何相关应用程序的整体性能负责。我们不就软件或任何相关文档做出任何表述或保证，包括但不限于适用性、特定目的的适用性和非侵权性保证。在任何情况下，我们不承担由于软件或文档的使用或交易而产生的任何索赔、损害或其他责任，无论是因为合同、侵权或其他原因。任何测试结果或性能指标仅供参考，并不能反映在所有条件下的性能。提及任何第三方或第三方产品、服务或其他资源不代表Block.one的认可或推荐。我们不承担任何责任，并否认对我们使用或依赖这些资源的任何责任和责任。第三方资源可能随时更新、更改或终止，因此这里的信息可能过时或不准确。任何使用或向第三方提供此软件并与提供软件、商品或服务相关的人员应向此类第三方告知这些许可证条款、免责声明和责任限制。Block.one、EOSIO、EOSIO Labs、EOS、多面体及其相关标志是Block.one的商标。

钱包和相关组件是复杂的软件，需要最高级别的安全性。如果构建或使用不当，可能会损害用户的私钥和数字资产。在使用之前，钱包应用程序和相关组件应进行彻底的安全评估。只有经验丰富的开发人员才能使用此软件。

EosioSwift 1.0.0

EosioSwift 1.0.0

EosioSwift 1.0.0

EOSIO SDK for Swift

内容

先决条件

安装

Swift 包管理器

CocoaPods

基本使用

处理事务

事务工厂

与PromiseKit一起使用

ABIEOS 序列化提供者使用

ECC 使用

软密钥签名提供者使用

密钥管理和签名工具

其他代码示例

iOS 示例应用

代码文档

提供者协议架构

签名提供者协议

RPC提供程序协议

序列化提供程序协议

ABI 提供者协议

RPC：使用默认 RPC 提供者

想要帮助？

许可证

重要