LibraClient is a collection of tools which allows you interact whith Libra Network easily. It provides three ways to access Libra:
libra_shell
, an interactive shell program. It is compatible with official Libra client. For beginners, it lets you get started directly to try your first transaction with libra without requiring time-consuming downloads and compiles the huge entire Libra project source code.libra
, a command line tool. It has a modern colorful text interface and its output is the standard json format. So, it can be integrated to any programming language easily.python api
, a collection of apis for client access to libra. For Python programmers, you can call this client side api to interact with Libra Network with more control than by using libra
command.In following docuement, all command prefix with $
meants it is typed and run in standard linux shell; all command prefix with libra%
meants it is typed and run in libra_shell
.
For exmaple, $ libra
meants run libra
command in linux shell, which is different than libra%
.
Require python 3.7 or above installed.
$ python3 -m pip install libra-client
If you had a problem during installation, following command should works anyway.
$ python3 -m pip install --index-url https://pypi.org/project/ --user libra-client
To start 'libra_shell' and connect to a validator node running on the Libra testnet, just input the 'libra_shell' command on termial as shown below.
$ libra_shell
Once the client connects to a node on the testnet, you will see the following output. To quit the client at any time, use the quit
command.
This document will guide you through executing your first transaction on the Libra Blockchain. We will walk you through creating accounts for two users.
The command 'libra' contains four subcommands 'account', 'transaction', 'wallet' and 'ledger'. All subcommands have their own parameters.
For example, using 'ledger' command to query the ledger start time and latest transaction time of testnet:
$ libra ledger time
You will get the json output like this:
{
"start_time": "2019-10-03T05:19:59",
"latest_time": "2019-10-16T17:04:17"
}
To query the balance of some account by address,
$ libra account balance 000000000000000000000000000000000000000000000000000000000a550c18
You will get the balance of that address:
{
"balance": 24075309756646968
}
To query the total balance of a wallet,
$ libra wallet balance <some mnemonic file of the wallet>
You will get the total balance and balance of every accounts in that wallet:
{
"7af57a0c206fbcc846532f75f373b5d1db9333308dbc4673c5befbca5db60e2f": 123,
"f1f48f56c4deea75f4393e832edef247547eb76e1cd498c27cc972073ec4dbde": 0,
"total_balance": 123
}
libra
If you input libra
without any parameters as following,
$ libra
You will get the help message:
USAGE:
libra [options] command [command parameters ...]
Optional arguments:
-a | --host HOST Host address/name to connect to. [default:testnet]
-p | --port PORT Admission Control port to connect to. [default: 8000]
-v | --verbose Verbose output
-V | --version Show program's version number and exit
-h | --help Show this help message and exit
Use the following commands:
account | a
Account query by address
transaction | t
Transaction query
wallet | w
show account information of a wallet derived from mnemonic file
ledger | lg
show ledger info of Libra blockchain
If you input the libra subcommand without any parameter, you will get the help message of that subcommand. For example:
$ libra wallet
You will get the help message:
USAGE:
wallet <arg>
Use one of the following args for this command:
show | s <mnemonic_file_path>
Show the mnemonic words, seed and addresses of a wallet
account | a <mnemonic_file_path>
Show the keypair and address of accounts in a wallet
balance | b <mnemonic_file_path>
Get the balance of all accounts in a wallet
create | c <mnemonic_file_path>
create a new wallet and save the mnemonic file to <mnemonic_file_path>
More instructions can be found here libra command help.
You can create a wallet using WalletLibrary
class. A wallet is like your masterkey and you can create almost infinitely many Libra accounts from it. Note that LibraClient's mnemonic scheme is compatible with that of Libra's CLI, so you can import mnemonic between the two libraries.
from libra_client import WalletLibrary
# Create a new random wallet
wallet = WalletLibrary.new()
# Create a new wallet from mnemonic words
wallet = WalletLibrary.new_from_mnemonic(mnemonic, child_count)
# Recover wallet from a offical Libra CLI backup file
wallet = WalletLibrary.recover(filename)
An Account
can be created by calling new_account
function on a wallet, each Account has an integer index in wallet, start from zero. An Account
contains its address
, public_key
, and private_key
.
print(wallet.child_count)
account1 = wallet.new_account()
print(wallet.child_count)
print(account1.address)
print(account1.public_key)
print(account1.private_key)
A Client
must be created in order to send protobuf message to a Libra node. You can create a client with the following code.
from libra_client import Client
client1 = Client("testnet") # Default client connecting to the official testnet
client2 = Client.new('localhost', 8000, "validator_file_path") # Client connecting to a local node
# An account stores its data in a directory structure, for example:
# <Alice>/balance: 10
# <Alice>/a/b/mymap: {"Bob" => "abcd", "Carol" => "efgh"}
# <Alice>/a/myint: 20
# <Alice>/c/mylist: [3, 5, 7, 9]
#
# If someone needs to query the map above and find out what value associated with "Bob" is,
# `address` will be set to Alice and `path` will be set to "/a/b/mymap/Bob".
#
# On the other hand, if you want to query only <Alice>/a/*, `address` will be set to Alice and
# `path` will be set to "/a" and use the `get_prefix()` method from statedb
No longer supported in json-rpc.
If the Account has been created, you can call get_account_state
function which return a AccountState
object with 'ordered_map' field; other wise, AccountError will be thrown.
client = Client("testnet")
amap = client.get_account_state(address)
If you want to get account balance / sequence / authentication_key etc from account state, you can calling get_account_resource
function, which will deserialize the account resource from account state map.
client = Client("testnet")
resource = client.get_account_resource(address)
print(resource.sequence_number)
print(resource.balance)
print(resource.authentication_key)
If you just want to get the balance of an address, simply call get_balance
function.
client = Client("testnet")
balance = client.get_balance(address)
If you just want to get the sequence number of an address, simply call get_sequence_number
function.
client = Client("testnet")
balance = client.get_sequence_number(address)
You can mint testnet libra with mint_with_faucet
function, which sends a HTTP POST request to http://faucet.testnet.libra.org.
c = Client("testnet")
c.mint_coins_with_faucet_service(address, 12345, is_blocking=True)
Note that in the official testnet, the Libra node ONLY allows sending the official transfer transaction script. In the future, this libra can be extended to support more transaction scripts as well!
wallet = WalletLibrary.recover('test.wallet')
a0 = wallet.accounts[0]
a1 = wallet.accounts[1]
ret = c.transfer_coin(a0, a1.address, 1234, is_blocking=True)
print(ret.ac_status.code)
When is_blocking param is False, the call will return as the transaction is submit to the validator node. When is_blocking param is True, the call will not return until the tranfer is actually executed or transaction waiting timeout.
Get transaction by version:
c = Client("testnet")
signed_txn = c.get_transaction(1)
print(signed_txn.raw_txn)
above code get transaction no.1, the return type is a SignedTransaction.
class SignedTransaction(Struct):
_fields = [
('raw_txn', RawTransaction),
('public_key', [Uint8, ED25519_PUBLIC_KEY_LENGTH]),
('signature', [Uint8, ED25519_SIGNATURE_LENGTH])
]
To get a list of transactions:
c = Client("testnet")
c.get_transactions(start_version, limit)
To get the latest 2 events send by an address:
c = Client("testnet")
events = c.get_latest_events_sent(address, 2)
To get the latest 2 events received by an address:
c = Client("testnet")
events = c.get_latest_events_received(address, 2)
Query events sent from an address, start from start_sequence_number(count begin with 0), get limit number of events, direction is ascending/descending:
get_events_sent(self, address, start_sequence_number, ascending=True, limit=1)
Query events received from an address, start from start_sequence_number(count begin with 0), get limit number of events, direction is ascending/descending:
get_events_received(self, address, start_sequence_number, ascending=True, limit=1)