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的账户余额。AccountState
的balance
中应该有 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 的工作原理有了一定的了解。不妨试试创建更多复杂资产!