入门

# 入门

当前 Ask! 只进行到了 Kusama 国库议案的第二期的开发,功能还未稳定,因此还未发布到 npm 等公开仓库中。

该文档假定用户拥有基本的 AssemblyScript 或 Typescript 编程基础,如果用户之前未接触过 AssemblyScript (opens new window),需要对它先有个基本的了解。

# 下载

目前 Ask 项目代码还未上传到 npm,所以需要直接 clone 仓库,待功能开发稳定后将会发布到 npm。

git clone https://github.com/patractlabs/ask

进入目录下载依赖:

yarn

# 开始使用

# 案例合约

在 Ask! 项目中的/examples目录下维护了一些基本的示例合约例如flipperincrementer等,开发者可以参考这些示例来编写智能合约。 下面的智能合约编写流程以/examples/flipper 目录下的合约为例来说明。

首先我们新建文件 flipper.ts作为入口点,后续编译生成的 wasm 代码中的 export 段对应的是该文件编译后导出的函数。实际上 AS 单文件就可以作为一个项目,但在这里我们需要通过 package.json 引入开发依赖。

你也可以使用 AssemblyScript 官方提供的 asbuild (opens new window) 构建工具来生成初始项目。

在工程创建完毕后,我们开始定义合约存储。 Ask! 采用装饰器 @storage 定义一个合约存储类。这个过程类似于 ink!中的 #[ink(storage)]宏。例如在这个案例中,我们定义以下合约存储类:

@storage
class Stored {
  flag: bool;
}

这样Stored就可以作为存储类在合约里使用。下面展示合约类的定义。

Ask! 提供@contract装饰器来定义一个合约类,它类似于 ink!中的 #[ink::contract]宏。@contract 支持继承。

@contract
class Flipper {
  // ...
}

Ask! 提供了@constructor@message 装饰器可以装饰@contract合约类中的非静态方法,它们类似于 ink!中的 #[ink(constructor)]#[ink(message)]

  • @constructor 装饰的方法会成为合约的一个初始化函数,每个@contract装饰的类必须至少需要有一个@constructor方法(不包括父类),父类的初始化函数不会直接成为合约初始化的函数。
  • @message 装饰的方法会成为合约的一个方法调用,每个@contract装饰的类必须至少需要有一个@message方法(包括父类),子类默认会继承父类的合约方法,用户可以重载继承的合约的方法。

注意:每个合约类需要定义一个无参的构造函数来实例化合约,@constructor 函数是在构造函数调用之后才被调用。

之后我们实现 Flipper 具体逻辑:

@contract
class Flipper {
  private stored: Stored;

  constructor() {
    this.stored = new Stored();
  }

  @constructor
  default(initFlag: bool): void {
    this.stored.flag = initFlag;
  }

  @message
  flip(): void {
    const v = this.stored.flag;
    this.stored.flag = !v;
  }

  @message(mutates = false)
  get(): bool {
    return this.stored.flag;
  }
}

它提供了一个合约初始化函数和两个合约方法,其中 get 方法是只读的,因为它设置了mutates = false

这里简单介绍了@storage@contract 装饰器,并且我们已经实现了一个最小合约示例。

# 编译

假设我们在 Ask! 项目的根目录下编译合约,当前合约的路径位于examples/flipper/flipper.ts(也可以替换为自己合约文件的路径),则编译命令是:

npx ask examples/flipper/flipper.ts

执行了这个命令后,会在合约文件的目录下生成一个目录 extension,里面存放的是展开后的代码,而合约的编译产物位于合约文件目录下的target目录:

  • metadata.json描述了这个合约的 ABI,它可以提供给支持该规范的链或工具。
  • target.wasm 是最终的 wasm 合约代码,部署到相应的链上即可执行。

# 链上环境测试

Ask! 当前不支持单元测试。

开发者可以采用 Patract 提供的合约执行环境沙盒 Europa 进行合约的部署调用和测试。

启动 Europa 后,开发者可以通过 https://polkadot.js.org/apps (opens new window)target目录下的合约进行部署和调用,这个过程和 ink! 合约的操作过程一致。