内容


使用 IBM Blockchain Platform VS Code 扩展开发智能合约

简化智能合约的开发、测试和部署过程

Comments

了解如何使用 IBM Blockchain Platform 的 Visual Studio Code 扩展来简化智能合约的开发、测试和部署过程。完成本教程后,您将了解如何使用 VS Code 在本地 Hyperledger Fabric 网络上快速开发、演示和部署区块链应用程序。本教程假设您对 Hyperledger Fabric 有一些基本了解。

学习目标

本教程将展示如何:

  • 安装 IBM Blockchain Platform VS Code 扩展
  • 创建一个新的智能合约项目
  • 打包智能合约
  • 启动并使用本地预先配置的 Hyperledger Fabric 运行时
  • local_fabric 上部署智能合约
  • 在本地部署的智能合约上进行交易

前提条件

您需要安装以下软件才能使用扩展:

  • VS Code V1.32 或更高版本
  • Node v8.x 或更高版本以及 npm v5.x 或更高版本
  • Docker v17.06.2-ce 或更高版本
  • Docker Compose v1.14.0 或更高版本

如果您使用的是 Windows,还必须确保满足以下要求:

  • 您的 Windows 版本支持 Hyper-V 和 Docker:
    • Windows 10 Enterprise、Pro 或 Education,并且安装了 1607 周年更新或更高版本的更新
  • Docker for Windows 配置为使用 Linux 容器(这是默认设置)
  • 已经通过 windows-build-tools 安装了适用于 Windows 的 C++ 构建工具
  • 已经通过 Win32 OpenSSL 安装了 OpenSSL v1.0.2,如下所示:
    • 安装正常版本,而不是标记为 "light" 的版本
    • 在 32 位系统上,将 Win32 版本安装到 C:\OpenSSL-Win32` 中
    • 在 64 位系统上,将 Win64 版本安装到 C:\OpenSSL-Win64` 中

您可以通过从终端运行以下命令来检查安装的版本:

  • node --version
  • npm --version
  • docker --version
  • docker-compose --version

预估时间

安装必备软件后,大约需要 20 到 30 分钟来完成本教程。

步骤

在开始之前,您需要安装 IBM Blockchain Platform VS Code 扩展。为此,您应该安装最新版本的 VS Code;要查看是否有最新的 VS Code 扩展,请转到 Code > Check for Updates。完成后,单击屏幕左侧边栏中的 Extensions。在顶部的扩展市场中搜索 IBM Blockchain Platform。单击 Install,然后单击 reload。现在,您应该能够使用该扩展了!

1 创建一个新的智能合约项目

该扩展可以采用所选的 Hyperledger Fabric 支持的编程语言生成智能合约框架。这意味着您将从基本但有用的智能合约开始,而不是从一片空白开始!

对于本教程,我们将使用 TypeScript 作为示例语言。

在 VS Code 中,每个命令都可以从命令面板中执行(按 Ctrl+Shift+P,在 MacOS 上则按 Cmd+Shift+P)。此扩展的所有命令都以 IBM Blockchain Platform: 开始。在这些教程步骤中,我们将向您展示在 UI 中单击哪里,但是如果您想知道命令面板替代选项,可留意类似于此的注释框。

  1. 在左侧边栏中,单击 IBM Blockchain Platform  图标(像一个正方形,如果这是您安装的最新扩展,那么可能位于图标集的底部)。
  2. 将鼠标悬停在 SMART CONTRACT PACKAGES 面板上,单击 "..." 菜单,然后从下拉菜单中选择 Create Smart Contract Project

    命令面板替代选项:Create Smart Contract Project

  3. 选择智能合约语言。可以使用 JavaScript、TypeScript、Java 和 Go。对于本教程,请选择 TypeScript
  4. 该扩展将询问您是否希望在生成的合约中命名资产。(这将默认为 "MyAsset",但您也可享受命名带来的乐趣。;) 您期望将区块链用于哪些用途?了解这一点将决定您将创建、更新和从分类账中读取哪些类型的资产:"Radish?""Pineapple?""Penguin?" 选取您需要的任何资产!对于本教程,我们仍坚持使用 "MyAsset"。

    更多技巧:如果您决定更改资产的名称,记住在以后的步骤中将 "MyAsset" 替换为您命名的任何名称!

  5. 选择项目的保存位置。单击 Browse,然后单击 New Folder,将项目命名为所需的名称(例如 "demoContract")。

    更多技巧:在命名项目时,避免使用空格!

  6. 单击 Create,然后选择您刚刚创建的新文件夹,再单击 Save
  7. 最后,从选项列表中选择 Add to workspace

    该扩展将根据所选语言和资产名称生成一个框架合约。完成后,您可以导航到 Explorer 视图(很可能是左侧边栏中的顶部图标,它看起来像是文档图标),然后打开 src/my-asset-contract.ts 文件,查看智能合约代码框架。棒极了!您已经有了一份智能合约,现在,让我们看看它的内容……

2 理解智能合约

生成的智能合约代码框架提供了一个良好的示例,展示了与区块链账本上的数据进行交互的一些常见操作。如果很着急,可以跳过这一节,但是为什么不花点时间来学习一下智能合约的基本结构呢?

注意以 @Transaction 开头的行:这些函数定义了您的合约的交易,允许您与账本进行交互。

跳过第一个函数 (myAssetExists),我们来看看 createMyAsset 函数:

    @Transaction()
    public async createMyAsset(ctx: Context, myAssetId: string, value: string): Promise<void> {
        const exists = await this.myAssetExists(ctx, myAssetId);
        if (exists) {
            throw new Error(`The my asset ${myAssetId} already exists`);
        }
        const myAsset = new MyAsset();
        myAsset.value = value;
        const buffer = Buffer.from(JSON.stringify(myAsset));
        await ctx.stub.putState(myAssetId, buffer);
    }

@Transaction() 中的空白括号告诉您,此函数的目的是更改账本的内容。此类交易通常会提交(与评估相反),本教程后面的内容将详细介绍。该函数名为 createMyAsset,它接受 myAssetIdvalue,这两者都是字符串。 提交此交易后,将创建一个新资产,其中包含键 myAssetId 和值 value。例如,假设您要创建 "001," "A juicy delicious pineapple";然后,当您读取键 001 的值时,您将了解到特定状态的值是 A juicy delicious pineapple

现在,看看下一个交易:

    @Transaction(false)
    @Returns('MyAsset')
    public async readMyAsset(ctx: Context, myAssetId: string): Promise<MyAsset> {
        const exists = await this.myAssetExists(ctx, myAssetId);
        if (!exists) {
            throw new Error(`The my asset ${myAssetId} does not exist`);
        }
        const buffer = await ctx.stub.getState(myAssetId);
        const myAsset = JSON.parse(buffer.toString()) as MyAsset;
        return myAsset;
    }

这以 @Transaction(false) 开头,"false" 表示此函数通常并非用来更改账本的内容。此类交易通常会被评估。您经常会听到这样的交易被称为"查询"。如您所见,此函数只接受 myAssetId,并返回该键指向的任何状态的值。

闲暇时,可以看看合约中的其他交易。然后,您可以继续打包和部署该合约,这样您就能开始使用了。

3 打包智能合约

既然您已创建了智能合约并理解了其中的交易,现在该打包此合约了。智能合约项目被打包到 .CDS 文件中 - 这是一种特殊类型的文件,可以安装在 Hyperledger Fabric 对等节点上。

  1. 在左侧边栏中,单击 IBM Blockchain Platform 图标。
  2. 将鼠标悬停在 SMART CONTRACT PACKAGES 面板上,单击 "..." 菜单,然后从下拉菜单中选择 Package a Smart Contract Project

    命令面板替代选项:Package a smart contract project

  3. 如果一切顺利,您应该会在列表中看到一个新的包:demoContract@0.0.1(或者您为打包的合约提供的名称)。

    刚刚创建的包可以安装到任何 Hyperledger Fabric 对等节点上(在正确的版本上运行)。例如,您可以右键单击并选择 Export Package,然后使用 IBM BlockChain Platform 操作工具控制台将其部署到云环境中。稍后您将了解如何做到这一点;现在,您将在预配置了 VS Code 扩展的运行时中本地部署包,因此还不需要导出您的包!

4 Local Fabric Ops

通过名为 LOCAL FABRIC OPS 的面板(在 IBM BlockChain Platform 视图中),您可以使用本地计算机上的 Docker 来操作简单的 Hyperledger Fabric 运行时。起初,它将停止,并且您应该看到以下内容:

Local Fabric runtime is stopped.Click to start.

单击该消息,此扩展将开始为您启动 Docker 容器。然后,您应该看到消息 "Local Fabric runtime is starting..." 和加载旋转框,任务完成时,您将看到一组可展开/可折叠的部分,标记为 "Smart Contracts"、"Channels"、"Nodes" 和 "Organizations"。

命令面板替代选项:Start Fabric Runtime

这是您在这一步中需要执行的全部操作,但当您等待 local_fabric 启动时,这里有更多关于它的组成部分的内容。

在本教程中,我们不会介绍太多细节,但以下内容会派上用场:

  • Smart Contract 部分显示本网络上的 InstantiatedInstalled 合约。本教程中的以下几个步骤将向您展示如何安装实例化已经打包的智能合约。
  • Channels 下面,有一个名为 "mychannel" 的单独通道。要使用智能合约,它就必须在通道上实例化。在本教程的下一步中,在您首先在对等节点上安装合约之后,就会发生这种情况。
  • Nodes 部分包含单个对等节点 (peer0.org1.example.com)。命名遵循 Hyperledger Fabric 的约定,从 "org 1" 部分可以看到,此对等节点属于 Org 1。(您可能会在对等节点名称后面看到一个小的无穷大符号,这表示当前处于开发模式,可以通过右键单击菜单来打开或关闭开发模式,但您现在不用管它。)
  • 还有一个证书颁发机构 (CA) ca.org1.example.com 和一个订购者节点 orderer.example.com。同样,稍后在构建自己的网络时,您将详细了解这些节点类型;现在,只需知道它们是网络的主要部分,此扩展已经为您创建了它们。
  • 这个简单的区块链网络中只有一个组织,名为 "Org1"。回想一下,Org1 拥有您在 Nodes 部分中看到的对等节点。在真实世界中,仅包含一个组织的网络是不太现实的,因为主旨就是在多个组织之间共享一个账本,但是这样的网络对于本地开发来说已经足够。在 Organizations 下面,您将看到 Org1MSP :这是 Org1 的 MSP ID。您现在不必太担心这个问题:在以后的教程中,当您开始构建自己的网络时,将会介绍成员服务提供商 (MSP)。
  • 如果您是 Docker 的铁杆粉丝,了解要在本地机器上启动以下容器可能会很有用:订购者、证书颁发机构、CouchDB 和对等节点。

既然已经启动了本地 Fabric 运行时,现在是时候安装和实例化智能合约了……

5 安装智能合约

在真实的网络中,每一个将对交易进行背书的组织都将在其对等节点上安装智能合约,然后合约将在通道上实例化。您的基本本地 Fabric 运行时只有一个组织 (Org1),以及一个对等节点 (peer0.org1.example.com) 和一个通道 (mychannel)。

因此,您只需在单个对等节点上安装合约,然后就可以在 "myChannel" 中将其实例化。 以下是操作方式:

  1. LOCAL FABRIC OPS 面板中,查找 + Install(在 Smart Contracts > Installed 下)并单击。
  2. 将要求您选择一个对等节点。选择唯一的选项 peer0.org1.example.com
  3. 然后,将要求您选择一个要安装的包。选取 demoContract@0.0.1

    您应该会看到在 Smart Contracts > Installed 列表下面显示了 demoContract@0.0.1

    命令面板替代选项:Install Smart Contract

就这样,大功告成!接下来,将实例化智能合约……

6 实例化智能合约

已安装的智能合约还不能由客户端应用程序调用:您需要一个共享的合约实例,网络中的所有组织都可以使用该实例。在仅包含一个组织的简化版本地开发网络中,这没什么实际意义。但是,正如您在后面的教程中将会看到的那样,当涉及多个组织时,它们必须在各自的对等节点安装同一个合约,然后该组才能在其共享通道实例化。因此,即使是在早期阶段,将此部署看作是一个两阶段过程也会很有帮助:这样做会在以后为您带来一些惊喜!

不过,现在您已经将合同安装在所有(一个)参与 "myChannel" 的对等节点上了,所以您可以继续进行实例化:

  1. LOCAL FABRIC OPS 面板中,查找+ Instantiate(在 Smart Contracts > Instantiated  下)并单击。
  2. 将要求您选择一个通道。选择唯一的选项 mychannel
  3. 然后,将要求您选择一个要实例化的智能合约。选取 demoContract@0.0.1
  4. 接着,将要求您选择要调用的函数。如果您想使用特定函数作为实例化的一部分,可以在这里输入一些内容。您将在后面的教程中看到这种情况,但是现在只需按Enter 键跳过这一步。
  5. 接下来,将询问您是否要提供私有数据配置文件。对于本教程,只需单击 No,您将在后面的教程中了解更多详情。

    实例化所需时间可能比安装更长 - 注意成功消息和 Smart Contracts > Instantiated 列表中显示的 demoContract@0.0.1,以确认其是否生效!

    命令面板替代选项:Instantiate Smart Contract

7 提交和评估交易

Fabric 网关会连接到参与 Hyperledger Fabric 网络的对等节点,客户端应用程序可以使用这些连接来提交交易。如果在 LOCAL FABRIC OPS 中启动了本地运行时,也会自动为您创建一个网关。可以在 FABRIC GATEWAYS 下找到这个名为 "local_fabric" 的网关。

使用网关,您还需要一个可用于在所讨论的网络上进行交易的身份。同样,对于本地 Fabric 运行时,已经为您设置了此身份。注意,在 FABRIC WALLETS 下有一个名为 local_fabric_wallet 的钱包,其中包含一个名为 admin 的 ID。如果在 FABRIC GATEWAYS 面板中将鼠标悬停在 local_fabric  上,您将会看到消息 "Associated wallet: local_fabric_wallet"。

现在您有了一个网关和一个相关的钱包,里面只有一个身份 - 这意味着此网关已可供使用。

  1. 单击 local_fabric(在 FABRIC GATEWAYS 下)以通过该网关进行连接。您现在将看到消息 "Connected via gateway: local_fabric, Using ID: admin" 以及一个名为 Channels 的折叠部分。
  2. 展开 Channels,然后展开 mychannel demoContract@0.0.1。您将看到智能合约中定义的所有交易的列表。
  3. 现在,您需要创建一个资产。右键单击 createMyAsset,然后选择 Submit Transaction。将要求您为交易提供参数:尝试 ["001", "a juicy delicious asset"](或者您需要的任何键和值,但务必要记住您使用的键!)

    更多技巧:参数以 JSON 的形式提交,因此确保输入的内容与所示完全相同,以便按照此交易的要求提交一个由 2 个字符串组成的数组。

    命令面板替代选项:Submit Transaction

  4. 然后,将要求您为交易设置瞬态数据。现在不必担心这个问题,我们将在后面的教程中讨论。现在,只需按 Enter  键。
  5. 接下来,以类似方式提交 updateMyAsset。这一次,对于这些参数,提供相同的键和不同的值,例如 ["001", "a tremendously delicious asset"]。因此,现在您的账本上键 001 的值应该是 "a tremendously delicious asset"。让我们通过读取这个值来核实一下……
  6. readMyAsset 是用于读取而不是写入到账本,所以这次选择 Evaluate Transaction。输入 ["001"](或者您为键设置的任何内容)作为参数。您会在输出控制台中看到以下内容:
    [SUCCESS] Returned value from readMyAsset: {"value":" a tremendously delicious asset"}

    命令面板替代选项:Evaluate Transaction

现在已证明,您可以提交和评估交易,以更新和读取您的账本!

结束语

恭喜 - 您现在知道了本地智能合约开发工作流程中的关键步骤!您已经生成了一个框架合约,在本地进行了部署,并用它来提交/评估交易。

如果您想花更多的时间在本地开发自己的智能合约,这些样本(从扩展的主页访问)可以帮助您探索开发概念。如果您正在对代码进行大量迭代,则应该阅读 ReadMe 中的调试:这对于开发者非常有用!

如果您想在引入 IBM BlockChain Platform 时采取接下来的步骤,VS Code 扩展中包含了一系列教程(共三个),您可以通过主页来访问。好消息:您已经完成了该系列教程中的第一个教程!因此,您可以前往教程 2:创建云区块链部署来继续您的学习。

参考资源

本文翻译自:Develop a smart contract with the IBM Blockchain Platform VSCode extension (2019-05-16)


评论

添加或订阅评论,请先登录注册

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Cloud computing
ArticleID=1065295
ArticleTitle=使用 IBM Blockchain Platform VS Code 扩展开发智能合约
publish-date=06202019