Forge SDK

为了在 forge 上开发应用程序,您可以用一个 SDK。Forge SDK 的目的是,使所有由 Forge 构建的与链的互动尽可能简单。所有的 SDK API 都按照以下类别分类:

  • 链 API:提供客户封装,供链相关 gRPC 使用
  • 钱包 API:提供客户封装,供钱包相关 gRPC 使用
  • 状态 APIs:提供客户封装,供状态相关 gRPC 使用
  • 订阅 API:提供客户封装,供订阅相关 gRPC 使用
  • 交易 API:交易 gRPC 是 send_tx,这一组 API 提供帮助者功能,使 tx 的构建和发送变得简单。
  • 杂项 API:解析配置、初始化 sdk 等。

GitHub 链接,请查看:

如需获取更多文件,请查看:

安装

对于每个新发布,我们都搭配 OSX 和 Ubuntu 二进制。如果您使用这两个平台,您可以按照最新的 forge-cli:

npm install -g @arcblock/forge-cli

然后运行:

forge init
forge start
forge web start

Forge 启动后,您可以在浏览器开启http://localhost:8210。因为您的链上没有任何数据(如果是您第一次运行),您可以运行我们的模拟器以注入一些随机数据:

forge simulator start

使用

第 0 步

首先,在本地搭配Forge CLI运行 Forge。

第 1 步

查看配置 forge 由forge config使用

第 2 步

FORGE_CONFIG设置为您的环境变量,指向您 forge 运行的配置。

教程

1 级:转移金钱

场景:Alice想给Bob转移 10TBA。

TBA是 Forge 链上的默认货币。1 TBA 有 16 个数位,所以,显示为10000000000000000

第 1 步:为Alice和Bob创建钱包

w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice_wallet"), wallet: w1)
w2 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "bob_wallet"), wallet: w2)

moniker是 Forge 上该钱包的昵称。passphrase由 Forge 使用,以将钱包加密为一个 keystore 文件。如需了解钱包声明规则的更多信息,请点击此处

我们看看Alice的钱包和账户详情

ForgeSdk.get_account_state(address: w1.address)

第 2 步:帮助Alice发出报到交易以获得一些钱

现在,您已为Alice和Bob创建了钱包,但是他们的账户里没有钱。让我们发出一次报到交易,帮助Alice得到一些钱。

ForgeSdk.checkin(wallet: w1)

收到哈希意味着交易被转移到 Forge,但不意味着交易成功。为了确认交易成功发出,让我们深入了解交易详情。

ForgeSdk.get_tx(hash: "89FA6DAF67C8F54870599313079DC6F8D7CD483864FE7A7BCDFB9DF4D8ECDAD1")

如果TransactionInfo中的code返回0,则意味着交易成功执行。现在,Alice的账户中应该有 25 TBA。

现在,我们查看一下Alice的账户余额。AccountStatebalance中应该有 25 TBA。

ForgeSdk.get_account_state(address: w2.address)

报到每个账户可每天发出一次报到交易以获得 25 TBA。 哈希:已签署交易所计算的哈希。每笔交易应有其独特的哈希

第 3 步:从Alice向Bob转移钱

现在Alice的账户中有 25 TBA,Bob的账户中什么也没有。我们可以发出转移交易,帮助Alice将 10 TBA 转移给Bob。

itx = ForgeAbi.TransferTx.new(to: w2.address, value: ForgeSdk.token_to_unit(10))
# sign with alice's wallet
tx1 = ForgeSdk.transfer(itx, wallet: w1)
ForgeSdk.get_tx(hash: tx1)
ForgeSdk.get_account_state(address: w1.address)

现在我们可以看到,Alice刚刚成功地将 10 TBA 转移到了Bob的账户!

🎉 祝贺您!您已完成 1 级教程!现在,您应该对 Forge 的工作原理有了基本的了解。如果您想迎接更多挑战,请查看 2 级和 3 级教程。

2 级:出售二手笔记本电脑

场景:Bob想向Alice出售一台二手笔记本电脑。

第 1 步:为Alice和Bob创建账户

w1 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "alice_wallet"), wallet: w1)
w2 = ForgeSdk.create_wallet()
ForgeSdk.declare(ForgeAbi.DeclareTx.new(moniker: "bob_wallet"), wallet: w2)

在帮助Alice和Bob创建账户后,我们帮助Alice获得一些购买Bob笔记本所需的钱

ForgeSdk.checkin(wallet: w1)

第 2 步:为Bob创建笔记本资产

在现实世界,Bob可以简单地向Alice出售他的笔记本。通过 Forge SDK,任何物理项目都能以资产形式存在。

我们试试帮Bob通过CreateAssetTx创建笔记本资产。用户可在data字段输入项目相关的信息,type_url代表如何解码序列化的value字段。在本教程中,为了简便,我们只填写笔记本的名称。

asset_data = Google.Protobuf.Any.new(type_url: "laotop", value: "brand new")
hash = ForgeSdk.create_asset(ForgeAbi.CreateAssetTx.new(data: asset_data), wallet: w2)
asset_address = ForgeSdk.get_address(hash)

然后我们可以看看这个资产到底是什么样的。

ForgeSdk.get_asset_state(address: asset_address)

最后一个字段是data字段,我们可以看到type_url: "laotop", value: "brand new"。您也可以在其中加入更为复杂的信息,如序列化的 protobuf 消息。

第 3 步:用钱交换资产

现在,Alice的账户里有 25 TBA,Bob有一个笔记本资产。如果Bob想以 10 TBA 的价格出售笔记本,应该怎么做?他可以发起ExchangeTx

因为Bob将是发出者,我们将笔记本asset_address作为他将交换的对象。相似的,Alice将交换 10 TBA。

sender_info = ForgeAbi.ExchangeInfo.new(assets: [asset_address])
receiver_info = ForgeAbi.ExchangeInfo.new(value: ForgeSdk.token_to_unit(10))
itx = ForgeAbi.ExchangeTx.new(to: w1.address, sender: sender_info, receiver: receiver_info)
# bob generate the tx
tx = ForgeSdk.prepare_exchange(itx, wallet: w2)
# bob gave the tx to alice to multi-sign
tx1 = ForgeSdk.finalize_exchange(tx, wallet: w1)
hash = ForgeSdk.send_tx(tx: tx1)

现在,如果我们查看笔记本的所有者,AssetState 中的owner应为Alice的地址。

ForgeSdk.get_asset_state(address: asset_address)

在购买笔记本后,Alice 的账户中应只有 15 TBA。

ForgeSdk.get_account_state(address: w1.address)

🎉 🎉 祝贺您!您已完成 2 级教程!现在,您应该对如何通过 Forge SDK 创建资产和交换资产 Forge 的工作原理有了一定的了解。不妨试试创建更多复杂资产!