Skip to content

Latest commit

 

History

History
491 lines (328 loc) · 14.9 KB

emd.md

File metadata and controls

491 lines (328 loc) · 14.9 KB
Raw

em-ledger Command Line Interface

Keys

Key Types

There are four types of key representations that are used:

  • emoney

    • Derived from account keys generated by emd keys add.
    • Used to receive funds.
    • e.g. emoney1a3s4dc3dnk5dqrnlk8ph4qw7q3fnqt2g66fu97.

  • emoneypub

    • Derived from account keys generated by emd keys add.
    • Can be used to construct multisig accounts.
    • e.g. emoneypub1addwnpepqtgk3y6js7ag92czg4tdxuh4hj7krugqkmhadypesu7cyvdz48x5gghef8z.

  • emoneyvaloper

    • Used by validator operators for management purposes.
    • Derived from account keys generated by emd keys add.
    • e.g. emoneyvaloper1a3s4dc3dnk5dqrnlk8ph4qw7q3fnqt2ga60gmn.

  • emoneyvalconspub

    • Used by the underlying consensus protocol ("Tendermint signing").
    • Generated when the node is created with emd init.
    • Get this value with emd tendermint show-validator.
    • e.g. emoneyvalconspub1addwnpepqtgk3y6js7ag92czg4tdxuh4hj7krugqkmhadypesu7cyvdz48x5gu767wn.

Generate Keys

You'll need an account private and public key pair to be able to receive funds and sign/send transactions.

It is highly recommended to use a Ledger Nano device to securely manage keys. See this guide for further information.

To generate a new secp256k1 key stored locally:

emd keys add <key_name>

Next, you will have to create a passphrase to protect the key on disk. The output of the above command will contain a seed phrase. It is recommended to save the seed phrase in a safe place so that in case you forget the password, you could eventually regenerate the key from the seed phrase with the following command:

emd keys add --recover

If you check your private keys, you'll now see <key_name>:

emd keys show <key_name>

View the validator operator's address via:

emd keys show <key_name> --bech=val

You can see all your available keys by typing:

emd keys list

View the validator pubkey for your node by typing:

emd tendermint show-validator

Note that this is the Tendermint signing key, not the operator key you will use in delegation transactions.

Generate Multisig Public Keys

You can generate and print a multisig public key by typing:

emd keys add --multisig=key_name_1,key_name_2,key_name_3[...] --multisig-threshold=K multisig_key_name

K is the minimum number of private keys that must have signed the transactions that carry the public key's address as signer.

The --multisig flag must contain the name of public keys that will be combined into a public key that will be generated and stored as new_key_name in the local database. All names supplied through --multisig must already exist in the local database. Unless the flag --nosort is set, the order in which the keys are supplied on the command line does not matter, i.e. the following commands generate two identical keys:

emd keys add --multisig=foo,bar,baz --multisig-threshold=2 multisig_key_name
emd keys add --multisig=baz,foo,bar --multisig-threshold=2 multisig_key_name

Multisig addresses can also be generated on-the-fly and printed using this command:

emd keys show --multisig-threshold K name1 name2 name3 [...]

For more information regarding how to generate, sign and broadcast transactions with a multi signature account see Multisig Transactions.

Transaction Broadcasting

When broadcasting transactions, emd accepts a --broadcast-mode flag. This flag can have a value of sync, async, or block (default), where sync makes the client return a CheckTx response, async makes the client return immediately, and block makes the client wait for the tx to be committed (or timing out).

As the e-Money network features on-demand block generation (it creates a new block as soon as a transaction is pending) it is recommended to use the default setting (block) to know the outcome of the transaction immediately.

Fees & Gas

Each transaction may either supply fees or gas prices, but not both.

e-Money uses network-wide minimum gas prices that validators use when determining if they should include the transaction in a block during CheckTx, where gasPrices >= minGasPrices.

The prevailing minimum gas prices, including accepted token denominations, can be queried using this command:

emd query authority gas-prices

min_gas_prices:
- denom: echf
  amount: "0.530000000000000000"
- denom: eeur
  amount: "0.500000000000000000"
- denom: ungm
  amount: "1.000000000000000000"
...

Your transaction must supply fees that are greater than or equal to any of the denominations the validator requires, e.g.

emd tx send ... --fees="50000ungm"

or

emd tx send ... --gas-prices="1.0ungm"

Account

Query Account Balance

After receiving tokens to your account, you can query your balance using this command:

emd query account <key_name>

For vesting accounts, the currently spendable amount can be queried using this command:

emd query spendable <key_name>

When you query an account with zero balance, you will get this error: No account with address <address> was found in the state..

Sending Tokens

The following command could be used to send coins from one account to another:

emd tx send <sender_key_name_or_address> <recipient_address> 1000000eeur --gas-prices="0.5eeur"

You may want to cap the maximum gas that can be consumed by the transaction via the --gas flag. If you pass --gas=auto, the gas supply will be automatically estimated before executing the transaction. Gas estimate might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction, thus an adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully. The adjustment can be controlled via the --gas-adjustment flag, whose default value is 1.0.

Now, view the updated balances of the origin and destination accounts:

emd query account <sender_key_name_or_address>
emd query account <recipient_address>

You can build a transaction and print its JSON format to STDOUT by appending --generate-only to the list of the command line arguments:

emd tx send <sender_key_name_or_address> <recipient_address> 1000000eeur --generate-only > unsigned_tx.json

The --generate-only flag prevents emd from accessing the local keychain. Thus when this flag is supplied <sender_key_name_or_address> must be an address.

The transaction can now be signed:

emd tx sign --from=<key_name> unsigned_tx.json > signed_tx.json

You can validate the transaction's signatures by typing the following:

emd tx sign --validate-signatures signed_tx.json

You can broadcast the signed transaction to a node by providing the JSON file to the following command:

emd tx broadcast signed_tx.json

Slashing

Unjailing

To unjail your jailed validator

emd tx slashing unjail --from <validator_operator_key_name>

Signing Info

To retrieve a validator's signing info:

emd query slashing signing-info <validator_pubkey>

Query Parameters

You can get the current slashing parameters via:

emd query slashing params

Staking

Query Validators

You can query the list of all validators:

emd query staking validators

If you want to get the information of a single validator you can check it with:

emd query staking validator <operator_address>

Bond Tokens

On the e-Money mainnet, we delegate ungm, where 1 NGM = 1000000ungm. Here's how you can bond tokens to a testnet validator (i.e. delegate):

emd tx staking delegate --amount=10000000ungm --validator=<validator_operator_address> --from=<key_name>

While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.

Query Delegations

Once submitted a delegation to a validator, you can see it's information by using the following command:

emd query staking delegation <delegator_address> <validator_operator_address>

Or if you want to check all your current delegations with disctinct validators:

emd query staking delegations <delegator_address>

Unbond Tokens

If for any reason the validator misbehaves, or you just want to unbond a certain amount of tokens, use this following command.

emd tx staking unbond <validator_addr> 1000000ungm --from=<key_name>

The unbonding will be automatically completed when the unbonding period (21 days) has passed.

Query Unbonding-Delegations

Once you begin an unbonding-delegation, you can see it's information by using the following command:

emd query staking unbonding-delegation <delegator_address> <validator_operator_address>

Or if you want to check all your current unbonding-delegations with disctinct validators:

emd query staking unbonding-delegations <delegator_address>

Additionally, as you can get all the unbonding-delegations from a particular validator:

emd query staking unbonding-delegations-from <validator_operator_address>

Redelegate Tokens

A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another:

emd tx staking redelegate \
  <source_validator_operator_address> \
  <destination_validator_operator_address> \
  1000000ungm --from=<key_name>

The redelegation will be automatically completed when the unbonding period has passed.

Query Redelegations

Once you begin an redelegation, you can see it's information by using the following command:

emd query staking redelegation \
  <delegator_address> \
  <source_validator_operator_address> \
  <destination_validator_operator_address>

Or if you want to check all your current unbonding-delegations with distinct validators:

emd query staking redelegations <delegator_address>

Additionally, as you can get all the outgoing redelegations from a particular validator:

  emd query staking redelegations-from <validator_operator_address>

Query Parameters

Parameters define high level settings for staking. You can get the current values by using:

emd query staking params

With the above command you will get the values for:

  • Unbonding time
  • Maximum numbers of validators
  • Coin denomination for staking

Query Pool

A staking pool defines the dynamic parameters of the current state. You can query them with the following command:

emd query staking pool

With the pool command you will get the values for not-bonded and bonded tokens.

Query Delegations To Validator

You can also query all of the delegations to a particular validator:

  emd query delegations-to <validator_operator_address>

Multisig Transactions

Multisig transactions require signatures of multiple private keys. Thus, generating and signing a transaction from a multisig account involve cooperation among the parties involved. A multisig transaction can be initiated by any of the key holders, and at least one of them would need to import other parties' public keys into their keychain and generate a multisig public key in order to finalize and broadcast the transaction.

For example, given a multisig key comprising the keys key_name_1, key_name_2, and key_name_3, each of which is held by a distinct party, the user holding key_name_1 would require to import the public keys of both key_name_2 and key_name_2 in order to generate the multisig account public key:

emd keys add <key_name_2> --pubkey=emoneypub1...
emd keys add <key_name_3> --pubkey=emoneypub1...
emd keys add <multisig_key_name> --multisig-threshold=2 --multisig=<key_name_1>,<key_name_2>,<key_name_3>ß

A new multisig public key has been stored, and its address multisig_address can now be extracted:

emd keys show --address <multisig_key_name>

The multisig_address will be used as signer of multisig transactions explained below.

The first step to create a multisig transaction is to initiate it on behalf of the multisig address created above:

emd tx send <recipient_address> 1000000ungm --from=<multisig_address> --generate-only > unsigned_tx.json

The file unsigned_tx.json contains the unsigned transaction encoded in JSON. key_name_1 can now sign the transaction with its own private key:

emd tx sign unsigned_tx.json --multisig=<multisig_address> --from=<key_name_1> --output-document=signature_1.json

Once the signature is generated, unsigned_tx.json and signature_1.json to the either of the parties holding key_name_2 or key_name_3.

They will in turn will generate their respective signature:

emd tx sign unsigned_tx.json --multisig=<multisig_address> --from=<key_name_2> --output-document=signature_1.json

multisig_address is a 2-of-3 multisig key, therefore one additional signature is sufficient. Any the key holders can now generate the multisig transaction by combining the required signature files:

emd tx multisign unsigned_tx.json <multisig_address> signature_1.json signature_2.json > signed_tx.json

The transaction can now be sent to the node:

emd tx broadcast signed_tx.json

Inflation

To query for the current inflation information:

emd query inflation

Retrieving Historical Data

Matching a Set of Events

You can use the transaction search command to query for transactions that match a specific set of events, which are added on every transaction.

Each event is composed by a key-value pair in the form of {eventType}.{eventAttribute}={value}. Events can also be combined to query for a more specific result using the & symbol.

You can query transactions by events as follows:

emd query txs --events='message.sender=emoney1...'

And for using multiple events:

emd query txs --events='message.sender=emoney1...&message.action=withdraw_delegator_reward'

The pagination is supported as well via page and limit:

emd query txs --events='message.sender=emoney1...' --page=1 --limit=20

The action tag always equals the message type returned by the Type() function of the relevant message.

You can find a list of available events on each of the SDK modules:

Matching a Transaction's Hash

You can also query a single transaction by its hash using the following command:

emd query tx <transaction_hash>