Facebook:使用Libra完成第一笔交易

http://www.libradocs.com/docs/my-first-transaction/

本文档将指导你在Libra Blockchain上完成你的第一笔交易。在你按照执行第一笔交易的步骤之前，我们建议你阅读以下文档，来熟悉Libra生态系统和Libra协议：

介绍
Libra协议

我们提供了一个命令行界面（CLI）客户端来与区块链进行交互。

准备

运行文档中的命令，需要满足以下条件：

你运行的是Linux（基于Red Hat或Debian）或macOS系统。
你可以稳定地连接到互联网。
你的系统已经安装 git。
如果使用 Mac，请确定已经安装好 Homebrew。
如果使用 Linux，请确定已经安装好 yum 或者 apt-get。

提交交易的步骤

在这个例子中，我们将下载必要的Libra组件并在两个用户之间执行一个交易：A（Alice）和B（Bob）。

执行以下步骤将交易提交到Libra testnet上的验证者节点：

克隆并编译 Libra Core.
编译客户端并连接到测试网络.
创建测试账户.
充Libra币到测试账户中.
发起转账.

克隆并编译 Libra Core

在终端里找一个合适的目录下执行：

git clone https://github.com/libra/libra.git

启动 Libra Core

然后进入 libra 目录，并运行安装脚本：

cd libra
./scripts/dev_setup.sh

安装脚本主要执行以下操作：

安装 rustup - rustup是Rust编程语言的安装程序，Libra Core是在其中实现的。
安装 rust-toolchain。
安装 CMake - 管理构建过程。
安装 protoc - 协议缓冲区的编译器。
安装 Go - 用于构建协议缓冲区。

如果你安装失败，请查看错误处理

编译客户端并连接到测试网络

要连接到Libra testnet上运行的验证者节点，请执行以下命令：

./scripts/cli/start_cli_testnet.sh

这条命令会编译客户端，并把客户端连接到 Libra 测试网络中的验证节点上。

连接成功后，会看到以下的输出信息。连接过程可以使用 quit 结束退出。

usage: <command> <args>
Use the following commands:
account | a
Account operations
query | q
Query operations
transfer | transferb | t | tb
<sender_account_address>|<sender_account_ref_id> <receiver_account_address>|<receiver_account_ref_id> <number_of_coins> [gas_unit_price (default=0)] [max_gas_amount (default 10000)] Suffix 'b' is for blocking.
Transfer coins from account to another.
help | h
Prints this help
quit | q!
Exit this client
Please, input commands:
libra%

如果看到上面的信息，说明你的客户端运行正常，并且已经成功连接到 Libra 的测试网络上了，接着开始创建测试账户。如果你在编译客户端和连接到testnet时遇到问题，参考错误处理

Note: 如果要在本地运行验证者节点，请参考运行本地验证者节点. 创建帐户，造币和执行交易的说明与testnet上的节点相同。

创建测试账户

将客户端连接到testnet后，可以运行CLI命令来创建新帐户。我们将引导你为两个用户创建帐户（让我们称他们为A和B）。

Step 1: 检查CLI客户端是否在你的系统上运行

libra％命令行提示符指示你的Libra CLI客户端正在运行。要查看帐户命令的帮助信息，请输入“account”，如下所示：

account
usage: account <arg>
Use the following args for this command:
create | c
Create an account. Returns reference ID to use in other operations
list | la
Print all accounts that were created or loaded
recover | r <file path>
Recover Libra wallet from the file path
write | w <file name>
Save Libra wallet mnemonic recovery seed to disk
mint | mintb | m | mb <receiver account> <number of coins>
Mint coins to the account. Suffix 'b' is for blocking

Step 2: 创建测试账户A

请注意，使用CLI创建帐户不会更新区块链，只会创建本地密钥对。

要创建Alice的帐户，在 libra%提示符后面输入命令：：

account create

创建成功后，你会看到以下信息:

>> Creating/retrieving next account from wallet
Created/retrieved account #0 address 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8

#0 是A的账户索引, 索引是引用A帐户的一种方式，在区块链上没有意义，只是帐户地址的包装，目的是为了方便用户引用他们创建的帐户。 address后面的长字符串是A的帐户地址，你可以在CLI命令中使用十六进制地址。

当前创建的账户只是在本地，只有以下两种情况发生之后，才会真正在区块链上创建这个账户：

当通过铸币（minting）将任何一笔钱添加到A的账户时。
其他用户将钱转账（transfer）到A账户中时。

Step 3: 创建测试账户B

在libra% 后再次输入创建账户的命令：

account create

创建成功后，你会看到以下信息：

>> Creating/retrieving next account from wallet
Created/retrieved account #1 address 8337aac709a41fe6be03cad8878a0d4209740b1608f8a81566c9a7d4b95a2ec7

#1 是B的账户索引,address后面的长字符串是B的账户地址。有关索引的更多详细信息，请参考创建测试账户A

Step 4 (可选): 列出本地所有账户

使用下边的命令可以列出目前本地的所有账户：

account list

执行成功后，你会看到以下信息：

User account index: 0, address: 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8, sequence number: 0
User account index: 1, address: 8337aac709a41fe6be03cad8878a0d4209740b1608f8a81566c9a7d4b95a2ec7, sequence number: 0

sequence number表示从该帐户发送的交易数。每次从该帐户发送的事务被执行并存储在区块链中时，它会递增。要了解更多信息，请参考sequence-number。

充Libra币到测试账户中

在testnet上创建和添加硬币是通过Faucet完成的。Faucet是一种与testnet一起运行的服务。此服务仅用于为testnet创建钱，并且不存在主网。它只是用来测试的，在现实中并没有任何使用价值。假设你已经创建了A和B的帐户，分别为索引0和索引1，你可以按照以下步骤将Libra添加到两个帐户。

Step 1: 向A账户充值110Libra币

输入以下命令，来完成充值：

account mint 0 110

0 代表A账户的索引编号
110 代表充值的金额

A successful account mint command will also create Alice’s account on the blockchain.

执行成功后，你会看到以下信息：

>> Minting coins
Mint request submitted

请注意，提交请求时，这意味着它已成功添加到mempool（testnet上的验证者节点）。它并不一定意味着它将成功完成。稍后，我们将查询帐户余额以确认铸币是否成功。

如果你的帐户mint命令未成功提交你的请求，请参考错误处理

Step 2: 向B账户充值52Libra币

输入以下命令，来完成充值：

account mint 1 52

1 代表B账户的索引编号
52 代表充值的金额
一个成功的帐户mint命令也将在区块链上创建B帐户。在区块链上创建Bob帐户的另一种方法是将钱从A的帐户转移到B的帐户。

执行成功后，你会看到以下信息：

>> Minting coins
Mint request submitted

如果你的帐户Minting命令未成功，请参考错误处理

Step 3: 检查余额

发起转账

在我们发起转账之前，我们可以查询每个账户的sequence number ，这将有助于我们了解执行交易是如何改变每个帐户的。

查询账户的sequence number

query sequence 0
>> Getting current sequence number
Sequence number is: 0
query sequence 1
>> Getting current sequence number
Sequence number is: 0

在 query sequence 0中, 0 是A的账户索引. Sequence number等于0，意味着没有发生任何的交易。

发起转账

输入以下命令可以实现，从A账户向B账户转10个Libra币

transfer 0 1 10

0 是A的账户索引
1 是B的账户索引
10 是转账的金额

执行成功后，你会看到以下信息：

>> Transferring
Transaction submitted to validator
To query for transaction status, run: query txn_acc_seq 0 0 <fetch_events=true|false>

你可以使用命令 query txn_acc_seq 0 0 true 来查询转账状态。第一个参数0是要查询的本地账户索引, 第二个参数0是当前此笔转账的序号，要查看此命令的示例输出，请参考输出.

你刚才交易已经提交到了testnet验证者节点上，它已经在验证者节点中的mempool中。但这并不一定意味着你的交易已被执行。理论上，如果系统运行缓慢或过载，则需要一些时间才能看到结果，你可能需要通过查询帐户多次检查。要查询索引为0的帐户，可以使用命令 query account_state 0. 输出结果请参考输出.

如果出现问题，请参考错误处理.

阻止转移命令(同步转账): 你可以使用 transferb 命令替换 transfer 命令. 在使用transferb命令提交后，直到提交到blockchain后，才会返回提示信息。一个例子：

transferb 0 1 10

有关从提交到执行和存储的交易生命周期的理解，请参阅交易的生命周期。

查询交易次数

query sequence 0
>> Getting current sequence number
Sequence number is: 1
query sequence 1
>> Getting current sequence number
Sequence number is: 0

A的帐号（索引0）的sequence number为1表示到目前为止已经从A的帐户发送了一个交易。B的帐户（索引1）的sequence number为0表示到目前为止尚未从B的帐户发送任何交易。每次从帐户发送交易时，序列号都会增加1。

查询账户余额

要检查两个帐户中的最终余额，可以参考下面的命令。如果你的交易（转账）成功执行，你应该在A账户中看到100个Libra币，在B账户中看到62个Libra币。

query balance 0
Balance is: 100
query balance 1
Balance is: 62

大功告成

你已成功在Libra testnet上执行了你的交易，并将10个Libra币从A账户转移到了B账户！

错误处理

启动相关

使用下边的命令，更新 Rust:
- rustup update
重新运行安装脚本：
- ./scripts/dev_setup.sh

客户端编译与运行相关

如果编译失败，请先删除锁定文件

rm Cargo.lock

如果客户端无法连接到testnet：

检查网络
确保是最新版本的客户端，从线上pull最新代码后，重新运行客户端：
- ./scripts/cli/start_cli_testnet.sh

造币(Minting)与充值相关

如果你在testnet上连接的验证者节点不可用，你将收到““Server unavailable””消息，如下所示：
1. account mint 0 110
2. >> Minting coins
3. [ERROR] Error minting coins: Server unavailable, please retry and/or check **if** host passed to the client is running
如果你在提交交易后未更新余额，请稍等片刻再次查询余额。如果区块链正在经历非常大量的交易，则可能会有延迟。如果你的余额仍未更新，请再次尝试minting。
要检查帐户是否存在，请查询帐户状态。对于索引为0的帐户，输入以下命令：

query account_state 0

transfer 0 1 10
>> Transferring
[ERROR] Failed to perform transaction: Server unavailable, please retry and/or check if host passed to the client is running

解决此错误的步骤：

检查与testnet的连接。
查询发起人帐户是否存在。对索引为0的帐户可以使用以下命令查询：
- query account_state 0
尝试使用quit或q！退出客户端，然后重新运行以下命令以连接到testnet：
- ./scripts/cli/start_cli_testnet.sh

查询命令的输出信息示例

根据账户索引与Sequence Number查询交易的输出信息示例

query txn_acc_seq 0 0 true
>> Getting committed transaction by account and sequence number
Committed transaction: SignedTransaction {
{ raw_txn: RawTransaction {
sender: 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8,
sequence_number: 0,
payload: {,
transaction: peer_to_peer_transaction,
args: [
{ADDRESS: 8337aac709a41fe6be03cad8878a0d4209740b1608f8a81566c9a7d4b95a2ec7},
{U64: 10000000},
]
},
max_gas_amount: 10000,
gas_unit_price: 0,
expiration_time: 1560466424s,
},
public_key: 55af3fe3f28550a2f1e5ebf073ef193feda44344d94c463b48be202aa0b3255d,
signature: Signature( R: CompressedEdwardsY: [210, 23, 214, 62, 228, 179, 64, 147, 81, 159, 180, 138, 100, 211, 111, 139, 178, 148, 81, 1, 240, 135, 148, 145, 104, 234, 227, 239, 198, 153, 13, 199], s: Scalar{
bytes: [203, 76, 105, 49, 64, 130, 162, 81, 22, 237, 159, 26, 80, 181, 111, 94, 84, 6, 152, 126, 181, 192, 62, 103, 130, 94, 246, 174, 139, 214, 3, 15],
} ),
}
}
Events:
ContractEvent { access_path: AccessPath { address: 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8, type: Resource, hash: "217da6c6b3e19f1825cfb2676daecce3bf3de03cf26647c78df00b371b25cc97", suffix: "/sent_events_count/" } , index: 0, event_data: AccountEvent { account: 8337aac709a41fe6be03cad8878a0d4209740b1608f8a81566c9a7d4b95a2ec7, amount: 10000000 } }
ContractEvent { access_path: AccessPath { address: 8337aac709a41fe6be03cad8878a0d4209740b1608f8a81566c9a7d4b95a2ec7, type: Resource, hash: "217da6c6b3e19f1825cfb2676daecce3bf3de03cf26647c78df00b371b25cc97", suffix: "/received_events_count/" } , index: 0, event_data: AccountEvent { account: 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8, amount: 10000000 } }

请注意，交易金额以microlibra显示。

查询结果的输出信息示例

在下面示例中，我们从索引0的帐户查询“已发送”结果。注意：因为只发送了一个交易，所以只有一个结果。结果中还有验证信息，可以用来验证是否有丢失的内容 - this is done when the query does not return “limit” events。

query event 0 sent 0 true 10
>> Getting events by account and event type.
EventWithProof {
transaction_version: 3,
event_index: 0,
event: ContractEvent { access_path: AccessPath { address: e7460e02058b36d28e8eef03f0834c605d3d6c57455b8ec9c3f0a3c8b89f248b, type: Resource, hash: "217da6c6b3e19f1825cfb2676daecce3bf3de03cf26647c78df00b371b25cc97", suffix: "/sent_events_count/" } , index: 0, event_data: AccountEvent { account: 46efbad798a739c088e0e98dd9d592c27c7eb45ba1f8ccbdfc00bd4d7f2947f3, amount: 10000000 } },
proof: EventProof { ledger_info_to_transaction_info_proof: AccumulatorProof { siblings: [HashValue(62570ae9a994bcb20c03c055667a4966fa50d0f17867dd5819465072fd2c58ba), HashValue(cce2cf325714511e7d04fa5b48babacd5af943198e6c1ac3bdd39c53c87cb84c)] }, transaction_info: TransactionInfo { signed_transaction_hash: HashValue(69bed01473e0a64140d96e46f594bc4b463e88e244b694e962b7e19fde17f30d), state_root_hash: HashValue(5809605d5eed94c73e57f615190c165b11c5e26873012285cc6b131e0817c430), event_root_hash: HashValue(645df3dee8f53a0d018449392b8e9da814d258da7346cf64cd96824f914e68f9), gas_used: 0 }, transaction_info_to_event_proof: AccumulatorProof { siblings: [HashValue(5d0e2ebf0952f0989cb5b38b2a9b52a09e8d804e893cb99bf9fa2c74ab304bb1)] } }
}
Last event state: Some(
AccountStateWithProof {
version: 3,
blob: Some(
AccountStateBlob {
Raw: 0x010000002100000001217da6c6b3e19f1825cfb2676daecce3bf3de03cf26647c78df00b371b25cc974400000020000000e7460e02058b36d28e8eef03f0834c605d3d6c57455b8ec9c3f0a3c8b89f248b00e1f50500000000000000000000000001000000000000000100000000000000
Decoded: Ok(
AccountResource {
balance: 100000000,
sequence_number: 1,
authentication_key: 0xe7460e02058b36d28e8eef03f0834c605d3d6c57455b8ec9c3f0a3c8b89f248b,
sent_events_count: 1,
received_events_count: 0,
},
)
},
),
proof: AccountStateProof {
ledger_info_to_transaction_info_proof: AccumulatorProof {
siblings: [
HashValue(62570ae9a994bcb20c03c055667a4966fa50d0f17867dd5819465072fd2c58ba),
HashValue(cce2cf325714511e7d04fa5b48babacd5af943198e6c1ac3bdd39c53c87cb84c),
],
},
transaction_info: TransactionInfo {
signed_transaction_hash: HashValue(69bed01473e0a64140d96e46f594bc4b463e88e244b694e962b7e19fde17f30d),
state_root_hash: HashValue(5809605d5eed94c73e57f615190c165b11c5e26873012285cc6b131e0817c430),
event_root_hash: HashValue(645df3dee8f53a0d018449392b8e9da814d258da7346cf64cd96824f914e68f9),
gas_used: 0,
},
transaction_info_to_account_proof: SparseMerkleProof {
leaf: Some(
(
HashValue(c0fbd63b0ae4abfe57c8f24f912f164ba0537741e948a65f00d3fae0f9373981),
HashValue(fc45057fd64606c7ca40256b48fbe486660930bfef1a9e941cafcae380c25871),
),
),
siblings: [
HashValue(4136803b3ba779bb2c1daae7360f3f839e6fef16ae742590a6698b350a5fc376),
HashValue(5350415253455f4d45524b4c455f504c414345484f4c4445525f484153480000),
HashValue(a9a6bda22dd6ee78ddd3a42da152b9bd39797b7da738e9d6023f407741810378),
],
},
},
},
)

查询账户状态的输出信息示例

在下面示例中，我们可以看到单个帐户的状态。

query account_state 0
>> Getting latest account state
Latest account state is:
Account: 3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8
State: Some(
AccountStateBlob {
Raw: 0x010000002100000001217da6c6b3e19f1825cfb2676daecce3bf3de03cf26647c78df00b371b25cc9744000000200000003ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a800e1f50500000000000000000000000001000000000000000100000000000000
Decoded: Ok(
AccountResource {
balance: 100000000,
sequence_number: 1,
authentication_key: 0x3ed8e5fafae4147b2a105a0be2f81972883441cfaaadf93fc0868e7a0253c4a8,
sent_events_count: 1,
received_events_count: 0,
},
)
},
)
Blockchain Version: 3

运行本地验证者节点

要在你的计算机上本地启动验证者节点并创建你自己的本地区块链网络（未连接到Libra testnet），请确保已按照Setup Libra Core中的说明运行编译脚本，并切换到Libra Core存储库的根目录后运行libra_swarm，如下所示：

$ cd ~/libra
$ cargo run -p libra_swarm -- -s

-p libra_swarm - causes cargo to run the libra_swarm package, which starts a local blockchain consisting of one node.

-s option starts a local client to connect to the local blockchain.

要查看所有的参数，可增加-h命令：

$ cargo run -p libra_swarm -- -h

The cargo run command may take some time to run. If the execution of this command completes without errors, an instance of the Libra CLI client and a Libra validator node is running on your system. Upon successful execution, you should see an output containing the CLI client menu and the libra% prompt.

交易的生命周期

当执行了第一笔交易，可以参考交易的生命周期：

从提交到执行的交易生命周期中的“under the hood”。
了解Libra验证器的每个逻辑组件之间的交互。