candid_dart_core 是一个用于与 Internet Computer (IC) 区块链上的 Candid 接口进行交互的 Dart 包。Candid 是一种接口描述语言（IDL），用于定义 IC 上智能合约（称为 Canisters）的接口。candid_dart_core 提供了 Dart 语言的原生支持，使开发者能够与 IC 上的 Canisters 进行交互。

安装 candid_dart_core

首先，你需要在 pubspec.yaml 文件中添加 candid_dart_core 依赖：

dependencies:
  candid_dart_core: ^0.1.0

然后运行 flutter pub get 来安装依赖。

基本使用

1. 创建 Candid 类型

candid_dart_core 提供了多种 Candid 类型的支持，例如 Nat, Int, Text, Bool, Opt, Vec, Record, Variant 等。

import 'package:candid_dart_core/candid_dart_core.dart';

void main() {
  // 创建一个 Nat 类型
  final nat = Nat(BigInt.from(42));
  print(nat); // 输出: 42

  // 创建一个 Text 类型
  final text = Text('Hello, Candid!');
  print(text); // 输出: Hello, Candid!

  // 创建一个 Vec 类型
  final vec = Vec([Nat(BigInt.from(1)), Nat(BigInt.from(2)), Nat(BigInt.from(3))]);
  print(vec); // 输出: [1, 2, 3]

  // 创建一个 Record 类型
  final record = Record({'name': Text('Alice'), 'age': Nat(BigInt.from(25))});
  print(record); // 输出: {name: Alice, age: 25}
}

2. 编码和解码 Candid 数据

candid_dart_core 提供了 CandidCodec 类来编码和解码 Candid 数据。

import 'package:candid_dart_core/candid_dart_core.dart';

void main() {
  // 创建一个 CandidCodec 实例
  final codec = CandidCodec();

  // 编码 Candid 数据
  final encoded = codec.encode([Nat(BigInt.from(42)), Text('Hello')]);
  print(encoded); // 输出: Uint8List 编码数据

  // 解码 Candid 数据
  final decoded = codec.decode(encoded);
  print(decoded); // 输出: [42, Hello]
}

3. 与 IC Canister 交互

candid_dart_core 还提供了与 IC Canister 进行交互的功能。你需要使用 Agent 类来发送请求并接收响应。

import 'package:candid_dart_core/candid_dart_core.dart';
import 'package:candid_dart_core/agent.dart';

void main() async {
  // 创建一个 Agent 实例
  final agent = Agent();

  // 定义 Canister ID 和方法名
  final canisterId = Principal.fromText('ryjl3-tyaaa-aaaaa-aaaba-cai');
  final methodName = 'greet';

  // 创建 Candid 参数
  final args = [Text('Alice')];

  // 发送请求并获取响应
  final response = await agent.call(canisterId, methodName, args);

  // 解码响应
  final decodedResponse = CandidCodec().decode(response);
  print(decodedResponse); // 输出: Hello, Alice!
}

高级用法

1. 使用 Opt 类型处理可选值

Opt 类型用于表示可选值。如果值为 null，则 Opt 将表示该值不存在。

import 'package:candid_dart_core/candid_dart_core.dart';

void main() {
  // 创建一个 Opt 类型
  final opt = Opt(Text('Hello'));
  print(opt); // 输出: Hello

  // 创建一个空的 Opt 类型
  final emptyOpt = Opt(null);
  print(emptyOpt); // 输出: null
}

2. 使用 Variant 类型处理多态数据

Variant 类型用于表示多态数据。它可以包含多个不同的类型。

import 'package:candid_dart_core/candid_dart_core.dart';

void main() {
  // 创建一个 Variant 类型
  final variant = Variant('name', Text('Alice'));
  print(variant); // 输出: {name: Alice}

  // 访问 Variant 的值
  if (variant.tag == 'name') {
    final name = variant.value as Text;
    print(name); // 输出: Alice
  }
}