IcpKit 是一个全面的 iOS 软件包，用于编写与互联网计算机协议 (ICP) 交互的移动应用程序，使用 Swift 编写。IcpKit 旨在促进 iOS 应用程序与 ICP 区块链之间的交互。

有关 ICP 开发的更多信息，我们建议从 https://internetcomputer.org/docs/current/references/ 开始。

此软件包的主要开发者是 Konstantinos Gaitanis。

此软件包由 Bity SA 在 DFinity 基金会开发者资助计划的帮助下构建。

MIT 许可证适用于所有 Swift 代码（参见 LICENSE）。

BLS12381 Rust 库已获得 Levi Feldman 的许可（参见 LICENSE）。

将 IcpKit 作为依赖项添加到您的 Xcode 项目非常容易，只需将其添加到 Package.swift 的 dependencies 值中即可。

...
dependencies: [
    .package(url: "https://github.com/kosta-bity/IcpKit.git", .upToNextMajor(from: "0.2.0"))
]
...

IcpKit 软件包定义了两个库 Candid 和 IcpKit。Candid 实现了 Candid 规范，IcpKit 实现了与容器的通信。要在您的代码中使用

import Candid  // not needed when using the CodeGenerator
import IcpKit

IcpKit 将负责与 ICP 通信所需的所有编码、序列化和密码学操作，使开发人员能够专注于应用程序的实际功能并启动其开发周期。

• CodeGenerator 命令行工具，用于解析 .did 文件并生成可以直接添加到您的项目中的 Swift 代码。
• CandidEncoder 和 CandidDecoder，用于将任何 Encodable/Decodable 转换为 CandidValue
• Candid 二进制序列化/反序列化
• CBOR 序列化
• 适用于 ICP 的密码学方法，例如签名和签名验证。
• 用于交易、帐户、自认证主体等的基本 ICP 模型。
• Ledger 和 Archive Canister 实现作为示例代码。

IcpKit 软件包分为 3 个产品

• Candid 库
• IcpKit 库
• CodeGenerator 命令行可执行文件

Candid 是用于与任何 ICP 容器通信的语言。它描述了容器使用的数据类型，以及可以在容器上调用的方法。Candid 本质上是这些类型的文本和二进制表示形式。二进制表示形式是实际发送/接收到/从容器的数据，而文本表示形式用于 Candid 接口定义文件 (.did) 中，以描述容器的接口。

如果您使用 CodeGenerator 工具，那么您将永远不必直接使用 Candid 与容器交互。

Candid 库的主要类如下

IcpKit 库构建于 Candid 之上，负责与容器的实际通信。IcpKit 的作用是抽象出调用容器函数时使用的底层数据结构。

IcpKit 库的主要类如下

ICPRequestClient 类是该库的通信主力，允许向任何容器发出方法调用。

Ledger Canister 作为示例实现提供，也允许轻松创建 ICP 钱包应用程序。

要使用 CodeGenerator，您必须首先克隆项目

git clone https://github.com/kosta-bity/IcpKit
cd IcpKit

然后，您可以使用 Swift 编译和运行，或者自己构建可执行文件。

从 IcpKit 根文件夹

./compile_code_generator.sh

您将在文件夹 .build/release/CodeGenerator 中找到可执行文件。运行不带任何参数的 CodeGenerator 将显示帮助信息。

或者，您可以使用 swift 从 IcpKit 根文件夹运行它

swift run CodeGenerator

容器由用于与其交互的所有类型和方法定义。大多数容器以 此处 定义的 .did 格式发布其定义。

IcpKit 可以解析这些文件并生成 Swift 代码，该代码可以包含在您的 iOS/Mac 项目中以与容器交互。这有效地抽象化了有关通信的所有技术细节。

.did 文件可以是以下两种类型之一

• 服务接口定义，包括类型定义和服务方法。这些称为接口 .did 文件。
• 单个 candid 值。这些称为值 .did 文件。

假设您有一个 .did 服务接口定义文件，与容器交互的步骤如下

• 使用 CodeGeneratorTool 为 .did 文件生成 Swift 代码。
• 将生成的 Swift 文件添加到您的项目中。
• 根据需要修改生成的 Swift 文件。允许的修改类型是
  • 重命名类型和方法。
    • Candid 命名标准与 Swift 命名标准不同。您可能希望遵循命名约定
    • 并非所有生成的类型都分配了名称。这些类型生成为 UnnamedType<n>，可以重命名为更易读的名称。
  • 添加/修改文档。
• 编写代码以调用容器的方法。

这是一个简单的接口 MyDid.did

type MyVector = vec opt bool;
type FooResult = record { name: text; count: int8 };
service: { 
    foo: (input: MyVector; sorted: bool) -> (FooResult) query
};

使用命令

CodeGenerator -n SimpleExample MyDid.did

我们得到了生成的 SimpleExample.swift 文件，其内容如下

import IcpKit

enum SimpleExample {
	typealias MyVector = [Bool?]
    
	struct FooResult: Codable {
		let name: String
		let count: Int8
	}  
  
	class Service: ICPService {
		func foo(input: MyVector, sorted: Bool) async throws -> FooResult {
			let caller = ICPQuery<CandidTuple2<MyVector, Bool>, FooResult>(canister, "foo")
			let response = try await caller.callMethod(.init(input, sorted), client, sender: sender)
			return response
		}
	}
}

然后，我们可以将此文件添加到我们的项目中，并在我们的代码中的任何位置使用它，如下所示

let client = ICPRequestClient()
let myService = SimpleExample.Service("aaaaa-aa", client)
let myVector: SimpleExample.MyVector = [true, false, nil]
let record = try await myService.foo(input: myVector, sorted: false)
print(record.name)
print(record.count)

生成的代码是完全类型安全的，并避免了常见的错误，例如错误的数字类型等...

值 .did 文件的示例是以下 phone_book.did

(
	vec {
	   record { name = "MyName"; phone = 1234 : nat; };
	   record { name = "AnotherName"; phone = 4321 : nat; };
	}
)

可以使用以下命令解析这些类型的文件

./CodeGenerator value -n PhoneBook phone_book.did

这将生成 PhoneBook.swift，其内容如下

enum PhoneBook {
   struct UnnamedType0: Codable {
      let name: String
      let phone: BigUInt
   }
   
   let cValue: [UnnamedType0] = [
   		.init(name: "MyName", phone: 1234),
      .init(name: "AnotherName", phone: 4321),
   ]
}

您的应用程序可能需要下载 .did 文件，解析它并从中提取一些值。这可以使用 CandidParser 完成。例如，如果我们想下载并读取上面的 phone_book.did

let phoneBookDidContents: String = try await downloadDid() // download phone_book.did file and read it 
let phoneBookCandidValue: CandidValue = try CandidParser().parseValue(phoneBookContents)

我们可以更进一步，将解析的 CandidValue 解码为 Swift struct

struct PhoneBookEntry: Decodable {
  let name: String
	let phone: BigUInt
}
let phoneBook: [PhoneBookEntry] = try CandidDecoder().decode(phoneBookCandidValue)

当从 CandidValue 解码 null、reserved 或 empty 到 Swift 时，它们始终在 Swift 中解码为 nil。

当从 Swift 编码 nil 到 CandidValue 时，它始终编码为 opt <sub_type>。

Candid 二进制格式不支持 record、variant、function 等的键的文本表示形式...而是使用 此处 定义的简单哈希方法

hash(id) = ( Sum_(i=0..k) utf8(id)[i] * 223^(k-i) ) mod 2^32 where k = |utf8(id)|-1

这意味着当从二进制格式反序列化 CandidValue 时，我们无法访问生成哈希的原始键。

CandidDecoder 会自动处理所有 Swift structs 的此问题，方法是哈希 swift 名称，然后比较哈希值。

但是，由于 Swift 解码系统的工作方式，我们无法对 Swift enums 执行相同的操作。这意味着为了从反序列化的 CandidValue（基本上是通过 ICPRequestClient 接收的每个值）解码 Swift enum，我们需要定义 CodingKeys 如下

• 如果我们从具有命名值的 variant 解码

  type NamedVariant = variant { one: int8; two: int16; three: record { a: int8; b: int16 } };
  

  我们使用 CandidCodingKey 执行哈希处理

  enum NamedVariant {
    case one(Int8)
    case two(Int16)
    case three(a: Int8, b: Int16)
      
    enum CodingKeys: String, CandidCodingKey {
      case one, two, three
    }
    enum ThreeCodingKeys: String, CandidCodingKey {
      case a, b
    }
  }

• 如果我们从具有未命名值的 variant 解码

  type UnnamedVariant = variant { int8; int16; record { int8, int16} };
  

  我们使用 Int, CodingKey 将整数值分配给键

  enum UnnamedVariant {
    case anyName(Int8)
    case really(Int16)
    case weCanChoose(here: Int8, too: Int16)
      
    enum CodingKeys: Int, CodingKey {
      case anyName, really, weCanChoose	// as long as we keep the order here
    }
    enum WeCanChooseCodingKeys: Int, CodingKey {
      case here, too										// and here
    }
  }

有关更深入的理解，请参阅 Swift 文档中关于编码、解码和 Coding Keys 的内容。

有几种方法可以执行请求。取决于它是简单的查询还是请求实际更改了区块链的状态。

let method = ICPMethod(
  canister: ICPSystemCanisters.ledger,
  methodName: "account_balance",
  arg: .record([
    "account": .blob(account.accountId)
  ])
)

let response = try await client.query(method, effectiveCanister: ICPSystemCanisters.ledger)

等效地，我们也可以这样做

let response = try await client.query(.uncertified, method, effectiveCanister: ICPSystemCanisters.ledger)

let requestId = try await client.call(method, effectiveCanister: ICPSystemCanisters.ledger)
let response = try await client.pollRequestStatus(requestId: requestId, effectiveCanister: ICPSystemCanisters.ledger)

等效地，我们也可以这样做

let response = try await client.callAndPoll(requestId: requestId, effectiveCanister: ICPSystemCanisters.ledger)

甚至

let response = try await client.query(.certified, method, effectiveCanister: ICPSystemCanisters.ledger)

所有这些都具有完全相同的结果。

可以使用以下代码实现相同的目的，只是这次使用 ICPFunction。这允许我们直接将 Encodable 馈送到函数，并接收回 Decodable。ICPFunction 将确保输入从输入 Swift 类型正确编码为 CandidValue，并且输出从 CandidValue 解码为输出 Swift 类型。

struct Result: Decodable {
	let name: String
	let count: Int?
}
// equivalent Candid definition:
// function (nat) -> ( record { name: text; count: opt int64; } )
let function = ICPFunction<BigUInt, Result>(canister, "foo")
let result = try await function.callMethod(12345)

我们建议使用 HorizontalSystems 的 HdWalletKit.Swift，以便从种子派生公钥/私钥对。ICP 派生路径为 m/44'/223'/0'/0/0

公钥必须采用未压缩形式。

1. 使用 ICPCryptography.selfAuthenticatingPrincipal(uncompressedPublicKey:) 创建 ICPPrincipal 实例。
2. 如果您需要对请求进行签名（例如，发送交易），您还需要创建 ICPSigningPrincipal。
3. 可以使用 ICPAccount.mainAccount(of:) 创建此 principal 的主帐户。

这是一个最小的 ICPSigningPrincipal 实现。这仅作为示例给出。请勿在生产环境中使用此代码，因为将私钥保存在内存中通常不是一个好习惯。

sign 方法特意设置为 async，以允许任何类型的延迟获取私钥（例如，远程访问或访问 iOS Secure Enclave）。

class SimpleSigningPrincipal: ICPSigningPrincipal {
  private let privateKey: Data
  let rawPublicKey: Data
  let principal: ICPPrincipal
  
  init(publicKey: Data, privateKey: Data) throws {
    self.privateKey = privateKey
    self.rawPublicKey = publicKey
    self.principal = try ICPCryptography.selfAuthenticatingPrincipal(uncompressedPublicKey: publicKey)    
  }
  
  func sign(_ message: Data, domain: ICPDomainSeparator) async throws -> Data {
    return try ICPCryptography.ellipticSign(message, domain: domain, with: privateKey)
  }
  
  static func fromMnemonic(_ words: [String]) throws -> SimplePrincipal {
    let seed = HdWalletKit.Mnemonic.seed(mnemonic: words)!
    let xPrivKey = HDExtendedKeyVersion.xprv.rawValue
    let privateKey = try HDPrivateKey(seed: seed, xPrivKey: xPrivKey)
      .derived(at: 44, hardened: true)
      .derived(at: 223, hardened: true)
      .derived(at: 0, hardened: true)
      .derived(at: 0, hardened: false)
      .derived(at: 0, hardened: false)
    let publicKey = privateKey.publicKey(compressed: false)
    return try SimplePrincipal(privateKey: privateKey.raw, uncompressedPublicKey: publicKey.raw)
  }
}

• 序列化递归 candid 值会导致无限循环。
• 不支持编码 CandidFunctionProtocol，因为没有简单的方法来推断函数参数和结果中使用的 CandidTypes。这意味着当调用期望另一个函数作为输入的容器方法时，自动代码生成将失败。
• 不支持编码 CandidServiceProtocol，因为函数无法编码。
• 可选 Structs 的编码无法推断结构体的成员。这些被编码为 opt empty，根据 Candid 规范，所有容器都应该接受它。