zwallet - a CLI for Züs wallet

zwallet is a command line interface (CLI) to demonstrate the wallet functionalities of Züs. For more information on Züs Network and the system overview, refer to docs.zus.network.

The CLI utilizes the Züs GoSDK.

• zwallet - a CLI for Züs wallet
  • Architecture
  • Getting started
    • 1. Installation
    • 2. Run zwallet commands
  • Global parameters
  • Commands
    • Set up bash autocompletion - zwallet completion
    • Creating and restoring wallets
      • Creating wallet - (any command)
      • Recovering wallet - recoverwallet
    • Exploring network nodes
      • Listing all miners - ls-miners
      • Listing all sharders -ls-sharders
      • Listing all blobbers - getblobbers
      • Listing all authorizers - bridge-list-auth
      • Getting Auhorizer Configuration - bridge-auth-config
      • Getting node ID by URL - getid
      • Getting Storage Smart Contract Configuration - sc-config
      • Getting Global Configuration - global-config
      • Get Version - get-version
    • Getting and sending tokens
      • Getting tokens with Faucet smart contract - faucet
      • Checking balance - getbalance
      • Sending tokens to another wallet - send
      • Verifying a transaction - verify
      • Collect rewards - collect-reward
      • Get nonce - getnonce
      • Reset User nonce - reset-user-nonce
    • Staking on miners and sharders
      • Getting the staking config - mn-config
      • Getting a miner or sharder info for staking - mn-info
      • Locking a stake on a node - mn-lock
    • Getting the stake pools of a wallet - mn-user-info
      • Getting the stake pool info - mn-pool-info
      • Unlock a stake - mn-unlock
      • Updating staking config of a node - mn-update-settings
    • Removing/Killing nodes
      • Killing a miner - mn-kill
      • Killing a sharder - sh-kill
    • Bridge
      • Import Account
      • List Accounts
      • Burn ETH
      • Burn BNT
      • Burn EURC
      • Burn USDC
      • Burn WZCN
      • Burn ZCN
      • Get WZCN Burn
      • Get ZCN Burn
      • Mint ZCN
      • Mint WZCN
      • Verify Transaction
  • Config
    • ~/.zcn/config.yaml
    • (Optional) Override Network

Architecture

zwallet can be configured to work with any Züs network. It uses a config and a wallet file stored on the local filesystem.

For most transactions, zwallet uses the 0dns to discover the network nodes, then creates and submits transaction(s) to the miners, and finally waits for transaction confirmation on the sharders.

Getting started

1. Installation

Prerequisites

• Go: Installation instructions for Mac, Linux and Windows can be found here.

Procedures

1. Clone the zwalletcli repo and install

git clone https://github.com/0chain/zwalletcli.git
cd zwalletcli
make install

2. Add config yaml at ~/.zcn/config.yaml

The following script sets https://demo.zus.network as your network.

cat > ~/.zcn/config.yaml << EOF
block_worker: https://demo.zus.network/dns
signature_scheme: bls0chain
min_submit: 50 # in percentage
min_confirmation: 50 # in percentage
confirmation_chain_length: 3
EOF

3. Run zwallet to display the list of supported commands.

./zwallet

---

For machine requirements and pre-requisites, follow the guides below:

• How to build on Linux/Mac
• How to build on Windows

2. Run zwallet commands

The following steps assume that your terminal's working directory is inside the zwalletcli repo.

Global parameters

zwallet accept global parameters to override default configuration and can be used in any command.

Parameter	Description	Default
--h,--help	Show help/parameters for a particular command
--config	Config file and description	config.yaml
--configDir	Config directory	~/.zcn
--network	Network file	network.yaml
--silent	Do not print detailed logs	false
--wallet	Wallet file	wallet.json
--withNonce	Nonce that will be used in transaction	0
--fee	Transaction Fee for given transaction	if not set, default is blockchain min fee

Commands

Set up bash autocompletion - zwallet completion

Generate the autocompletion script for zwallet for the specified shell and instructions to enable them.

Sample Usage:

  zwallet completion [command]

commands : bash/fish/powershell/zsh based on the specified shell

See each sub-command's help for details on how to use the generated script.

Creating and restoring wallets

Creating wallet - (any command)

Simply run create-wallet command and it will create a wallet if none exist yet.

Here is a sample with create-wallet command and this creates a wallet at default location~/.zcn/wallet.json

./zwallet create-wallet

Sample Output

wallet saved in /home/ubuntu/.zcn/wallet.json
{"client_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"keys":[{"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"private_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}],
"mnemonics":"xxxx xxxx xxxx xxxxx",
"version":"1.0","date_created":"2023-05-03T12:44:46+05:30","nonce":0}

Recovering wallet - recoverwallet

recoverwallet is used when restoring a lost wallet or when loading the wallet from a different computer.

Given a wallet's mnemonics, you can recover and recreate your wallet.

Parameter	Required	Description	Default	Valid Values
--mnemonic	Yes	The mnemonics of the wallet to recover
--offline	No	recover wallet without registration on blockchain	false

Sample command

./zwallet recoverwallet --wallet recovered_wallet.json --mnemonic "pull floor crop best weasel suit solid gown filter kitten loan absent noodle nation potato planet demise online ten affair rich panel rent sell"

Sample output

Wallet recovered!!

Verify recovered wallet

cat ~/.zcn/recovered_wallet.json

Exploring network nodes

Listing all miners - ls-miners

The list of miners are retrieved using the Miner smart contract.

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON
--active	No	Gets active miners only, set it false to get all miners	true	boolean
--all	No	Include all registered miners, default returns the first page of miners
--limit	No	Limits the number of miners returned	20	integer
--offset	No	Skips the number of miners mentioned		integer
--stakable	No	Gets stakable miners only if set to true	false	boolean

./zwallet ls-miners

Sample output

- ID:         cdb9b5a29cb5f48b350481694c4645c2db24500e3af210e22e2d10477a68bad2
- Host:       demo1.zus.network
- Port:       31203
- ID:         3d9a10dac6fb3903d4a5283a42ae07b29d8e5d228afcce9bfc14e3e9dbc82748
- Host:       demo2.zus.network
- Port:       31201
- ID:         aaa721d5fbf4ca83e20c8c40874ebcb144b86f57173633ff1702968677c2fa98
- Host:       demo3.zus.network
- Port:       31202

Listing all sharders -ls-sharders

The list of sharders are retrieved using the latest finalized magic block. All registered sharders can be retrieved with the --all parameter.

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON
--active	No	Gets active miners only, set it false to get all miners	true	boolean
--all	No	Include all registered miners, default returns the first page of miners
--limit	No	Limits the number of miners returned	20	integer
--offset	No	Skips the number of miners mentioned		integer
--stakable	No	Gets stakable miners only if set to true	false	boolean

./zwallet ls-sharders --all

Sample output

MagicBlock Sharders
ID: 12e317e5d7a4a0a914ec26074e28f00502c735ddf7ac7d156b34e83e39792a9d
  - N2NHost: demo1.zus.network
  - Host: demo1.zus.network
  - Port: 31102
ID: 675502b613ba1c5985636e3e92b9a857855a52155e3316bb40fe9607e14167fb
  - N2NHost: demo2.zus.network
  - Host: demo1.zus.network
  - Port: 31101

Registered Sharders
ID: 675502b613ba1c5985636e3e92b9a857855a52155e3316bb40fe9607e14167fb
  - N2NHost: demo1.zus.network
  - Host: demo1.zus.network
  - Port: 31101
ID: 12e317e5d7a4a0a914ec26074e28f00502c735ddf7ac7d156b34e83e39792a9d
  - N2NHost: demo2.zus.network
  - Host: demo2.zus.network
  - Port: 31102
ID: 43f4f011698db6f2078e6ceb1cd981ab3bd35d07b7ac6fdf7c77aec1feee09be
  - N2NHost: demo3.zus.network
  - Host: demo3.zus.network
  - Port: 31101
ID: fd02f4436692bd9f679fae809f4f140fd4daaa35769ae9c6db1ab9664f766c22
  - N2NHost: 144.76.91.241
  - Host: demo4.zus.network
  - Port: 31102

Listing all blobbers - getblobbers

The list of blobbers are retrieved using the Storage smart contract.

Parameter	Required	Description	Default	Valid Values
--all	No	Gets all blobbers, including inactive blobbers

./zwallet getblobbers

Sample output

Blobbers:
                 URL                 |                                ID                                |          CAP           |     R / W PRICE     | DEMAND
+------------------------------------+------------------------------------------------------------------+------------------------+---------------------+--------+
  http://demo1.zus.network:31305 | 011a5444c9fe53137da7c3d871f3bf4bbf3c01607b14aa95ff2de43b5537d4b6 | 271.5 GiB / 1000.0 GiB | 0.010000 / 0.010000 |    0.1
  http://demo1.zus.network:31306 | 2efc85d6a2f36380e1e77b843cd9f4fe55668271cae4925ab38a92504176e5df | 107.8 GiB / 1000.0 GiB | 0.010000 / 0.010000 |    0.1
  http://demo1.zus.network:31302 | 34934babf0781c21736023ff89bc554928d77c028a968ef7344a460611d5a8d2 | 104.3 GiB / 1000.0 GiB | 0.010000 / 0.010000 |    0.1

List Authorizers - bridge-list-auth

./zwallet bridge-list-auth command can be used to list all authorizers available to validate client transactions.

Sample Command:

./zwallet bridge-list-auth

Sample Response:

[
  {
   "id": "2f945f7310689f17afd8c8cb291e1e3ba21677243aa1d404a2293064e7983d60",
   "url": "https://demo.zus.network/authorizer01/"
  },
  {
   "id": "7b07c0489e2f35d7c13160f4da2866b4aa69aa4e8d2b2cd9c4fc002693dca5d7",
   "url": "https://demo.zus.network/authorizer02/"
  },
  {
    "id": "896c171639937a647f9e91d5ba676be580f6d2b7e0d708e4fe6ea36610a13ffd",
    "url": "https://demo.zus.network/authorizer03/"
  }
]

Getting node ID by URL - getid

Print the ID of a blockchain node.

Parameter	Required	Description	Default	Valid Values
--url	Yes	URL to the node (miner, sharder, blobber)

./zwallet getid --url http://demo1.zus.network:31101

Output

URL: http://demo1.zus.network:31101
ID: 675502b613ba1c5985636e3e92b9a857855a52155e3316bb40fe9607e14167fb

Show Storage Smart Contract Configuration - sc-config

./zwallet sc-config command displays current storage smart contract configuration

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON

Sample Command:

./zwallet sc-config

Sample Response :

.blobber_slash    0.1
block_reward.block_reward        1.8
block_reward.gamma.a     10
block_reward.gamma.alpha         0.2
block_reward.gamma.b     9
block_reward.qualifying_stake    1
block_reward.zeta.i      1
block_reward.zeta.k      0.9
block_reward.zeta.mu     0.2
cancellation_charge      0.2
challenge_enabled        true
cost.add_blobber         100
cost.add_free_storage_assigner   100
cost.add_validator       100
cost.blobber_health_check        100
cost.cancel_allocation   8400
cost.challenge_request   100
cost.challenge_response          1600
cost.collect_reward      100
cost.commit_connection   100
cost.commit_settings_changes     0
cost.finalize_allocation         9500
cost.free_allocation_request     1500
cost.free_update_allocation      2500
cost.generate_challenge          100
cost.kill_blobber        100
cost.kill_validator      100
cost.new_allocation_request      3000
cost.new_read_pool       100
cost.pay_blobber_block_rewards   100
cost.read_pool_lock      100
cost.read_pool_unlock    100
cost.read_redeem         100
cost.shutdown_blobber    100
cost.shutdown_validator          100
cost.stake_pool_lock     100
cost.stake_pool_pay_interests    100
cost.stake_pool_unlock   100
cost.update_allocation_request   2500
cost.update_blobber_settings     100
cost.update_settings     100
cost.update_validator_settings   100
cost.write_pool_lock     100
cost.write_pool_unlock   100
free_allocation_settings.data_shards     4
free_allocation_settings.parity_shards   2
free_allocation_settings.read_pool_fraction      0
free_allocation_settings.read_price_range.max    0
free_allocation_settings.read_price_range.min    0
free_allocation_settings.size    2000000000
free_allocation_settings.write_price_range.max   1
free_allocation_settings.write_price_range.min   0
health_check_period      1h0m0s
max_blobbers_per_allocation      40
max_challenge_completion_time    3m0s
max_delegates    200
max_individual_free_allocation   1e+06
max_mint         7.5e+07
max_read_price   100
max_stake        20000
max_total_free_allocation        9.223372036854776e+08
max_write_price          100
min_alloc_size   1048576
min_blobber_capacity     10737418240
min_stake        0.01
min_write_price          0.001
owner_id         1746b06bb09f55ee01b33b5e2e055d6cc7a900cb57c0a3a5eaabb8a0e7745802
readpool.min_lock        0
stakepool.kill_slash     0.5
stakepool.min_lock_period        0s
time_unit        720h0m0s
validator_reward         0.025
validators_per_challenge         2
writepool.min_lock       0.1

Get Version - version

The version of zwallet and gosdk can be fetched using the ./zwallet version command.

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON

Sample Command :

./zwallet version

Sample Response :

Version info:
        zwallet...:  v1.2.3-21-gb10c459
        gosdk.....:  v1.8.17-0.20230522160233-570f983a6283

Show global configurations - global-config

./zwallet global-config command displays global chain configuration

Sample Command :

./zwallet global-config

Sample Response :

server_chain.async_blocks_fetching.max_simultaneous_from_miners          100
server_chain.async_blocks_fetching.max_simultaneous_from_sharders        30
server_chain.block.consensus.threshold_by_count          66
server_chain.block.consensus.threshold_by_stake          0
server_chain.block.generation.retry_wait_time    5
server_chain.block.generation.timeout    15
server_chain.block.generators_percent    0.2
server_chain.block.max_block_cost        10000
server_chain.block.max_block_size
server_chain.block.max_byte_size         1638400
server_chain.block.min_block_size        1
server_chain.block.min_generators        2
server_chain.block.proposal.max_wait_time        180ms
server_chain.block.proposal.wait_mode    static
server_chain.block.replicators   0
server_chain.block.reuse_txns    false
server_chain.block.sharding.min_active_replicators       25
server_chain.block.sharding.min_active_sharders          25
server_chain.block.validation.batch_size         1000
server_chain.block_rewards       true
server_chain.client.discover     true
server_chain.client.signature_scheme     bls0chain
server_chain.dbs.settings.aggregate_period       10
server_chain.dbs.settings.debug          false
server_chain.dbs.settings.page_limit     50
server_chain.dbs.settings.partition_change_period        100000
server_chain.dbs.settings.partition_keep_count   20
server_chain.dkg         true
server_chain.health_check.deep_scan.batch_size   50
server_chain.health_check.deep_scan.enabled      false
server_chain.health_check.deep_scan.repeat_interval_mins         3m
server_chain.health_check.deep_scan.report_status_mins   1m
server_chain.health_check.deep_scan.settle_secs          30s
server_chain.health_check.deep_scan.window       0
server_chain.health_check.proximity_scan.batch_size      50
server_chain.health_check.proximity_scan.enabled         true
server_chain.health_check.proximity_scan.repeat_interval_mins    1m
server_chain.health_check.proximity_scan.report_status_mins      1m
server_chain.health_check.proximity_scan.settle_secs     30s
server_chain.health_check.proximity_scan.window          100000
server_chain.health_check.show_counters          true
server_chain.lfb_ticket.ahead    5
server_chain.lfb_ticket.rebroadcast_timeout      15s
server_chain.messages.verification_tickets_to    all_miners
server_chain.owner       edb90b850f2e7e7cbd0a1fa370fdcc5cd378ffbec95363a7bc0e5a98b8ba5759
server_chain.round_range         10000000
server_chain.round_timeouts.round_restart_mult   10
server_chain.round_timeouts.softto_min   1500
server_chain.round_timeouts.softto_mult          1
server_chain.round_timeouts.timeout_cap          1
server_chain.smart_contract.faucet       true
server_chain.smart_contract.miner        true
server_chain.smart_contract.multisig     false
server_chain.smart_contract.setting_update_period        200
server_chain.smart_contract.storage      true
server_chain.smart_contract.timeout      8000ms
server_chain.smart_contract.vesting      false
server_chain.smart_contract.zcn          true
server_chain.state.enabled       true
server_chain.state.prune_below_count     100
server_chain.state.sync.timeout          10
server_chain.stuck.check_interval        10
server_chain.stuck.time_threshold        60
server_chain.transaction.cost_fee_coeff          1000000
server_chain.transaction.exempt          contributeMpk,shareSignsOrShares,wait,mint,pour
server_chain.transaction.max_fee         0.01
server_chain.transaction.min_fee         0
server_chain.transaction.payload.max_size        98304
server_chain.transaction.timeout         600
server_chain.view_change         false

Getting and sending tokens

Checking balance - getbalance

Wallet balances are retrieved from sharders.

Note: Balance would not show any locked tokens.

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON

./zwallet getbalance

Sample output

Balance: 3 (4.2299999999999995 USD)

To check the balance of another wallet, use --wallet global parameter.

./zwallet getbalance --wallet another_wallet.json

Note: When there is no token on the wallet yet, output will show Get balance failed.

Sending tokens to another wallet - send

Transferring tokens from a wallet to another is done through send

Parameter	Required	Description	Default	Valid Values
--json	No	Print output as JSON
--to_client_id	Yes	Client ID of the recipient
--tokens	Yes	Amount of tokens to send		valid number
--desc	Yes	Transfer description		any string
--fee	No	Amount of tokens to use as fee	0.0	valid number

The following sends 0.2 token from the default wallet to the specified client ID.

./zwallet send --to_client_id e7ebb698213b6bda097c0a14ccbe574356e99e9b666e4baeae540da1d9b51e7e --tokens .2 --desc "gift"

Output

Send tokens success

To use a different wallet as sender, use --wallet global parameter.

./zwallet send --to_client_id e7ebb698213b6bda097c0a14ccbe574356e99e9b666e4baeae540da1d9b51e7e --tokens .2 --desc "gift" --wallet another_wallet.json

Verifying a transaction - verify

verify checks whether a given transaction hash was confirmed on the blockchain.

Parameter	Required	Description	Default	Valid Values
--hash	Yes	Hash of transaction to verify		valid transaction hash

Note: Not all zwallet commands (eg. send) prints the transaction hash created. To see more details printed including the hashes, use --verbose global parameter.

Sample command

./zwallet verify --hash 867c240b640e3d128643330af383cb3a0a229ebce08cae667edd7766c7ccc850

Output

Transaction verification success

To see more details about the transaction on verify, use --verbose global parameter.

./zwallet verify --hash 867c240b640e3d128643330af383cb3a0a229ebce08cae667edd7766c7ccc850 --verbose

Collect rewards - collect-reward

Use collect-reward to transfer reward tokens from a stake pool.The stake pool keeps an account for all stakeholders to maintain accrued rewards. You earn rewards for: Sharders and Miners

• Miners produce blocks.
• Sharders stores the blockchain and other related data, such as the event database. They also support a query REST API.

Parameter	Required	Description	Valid values
provider_type	yes	miner or sharder or authorizer	miner/sharder/authorizer
provider_id	yes	miner or sharder id	string

Sample Command :

./zwallet collect-reward --provider_type miner --provider_id $MINER/SHARDER_ID

The output would print the stake pool id.

locked with: b488738546d84aed9d3dcb2bbe24c161bc4338638669e64e814631efd430fd85

Get Nonce - getnonce

Use getnonce to get nonce of the default wallet

Sample Command :

./zwallet getnonce

The output would print the stake pool id.

Nonce: 58

Reset Nonce - reset-user-nonce

Use reset-user-nonce to reset the nonce value of the user wallet

Parameter	Required	Description	Default	Valid Values
--chain_config	No	Chain config file name	config.yaml
--path	No	Config home folder	~/.zcn

Sample Command :

Command required ethereum_node_url to be set in config

./zwallet reset-user-nonce

Staking on miners and sharders

Miner smart contract allows staking on the miner and sharder nodes.

The maximum number of stake pools per node is limited to the number of delegates allowed. To find out the number of delegates and the minimum and maximum tokens allowed, query the staking config.

Getting the staking config - mn-config

mn-config display the global info of Miner SC for staking.

./zwallet mn-config

Sample output

view_change:           0
max_n:                 8
min_n:                 2
max_s:                 3
min_s:                 1
t_percent:             0.51
k_percent:             0.75
last_round:            5527098
max_stake:             100
min_stake:             0
interest_rate:         5.55e-07
reward_rate:           1
share_ratio:           0.8
block_reward:          0.21
max_charge:            0.5
epoch:                 15000000
reward_decline_rate:   0.1
interest_decline_rate: 0.1
max_mint:              4000000
minted:                928552.464
max_delegates:         200

Getting a miner or sharder info for staking - mn-info

Node stats for staking are retrieved from Miner SC.

Parameter	Required	Description	Default	Valid Values
--id	Yes	Node ID of a miner or sharder (get at ls-miners or ls-sharders)

Sample command

./zwallet mn-info --id 68ed8f16e1d50e3217425b3e98fb7a39e5d7201fe4b1dccfe8477b5c54761b24

Sample output

{"simple_miner":{"id":"68ed8f16e1d50e3217425b3e98fb7a39e5d7201fe4b1dccfe8477b5c54761b24","n2n_host":"five.devnet-0chain.net","host":"five.devnet-0chain.net","port":31102,"path":"sharder02","public_key":"458170c28496333426f9866989f7b335564d13d00f50db503275e7ec50a008031764ba5df42c20c85d76e7fe7eda43f39afdb650b8ffa9ed340e6fc50c35ae22","short_name":"localhost.s02","build_tag":"50fb047353c4c3d268c0e0ebfd8e63f1d10c6813","total_stake":0,"delegate_wallet":"68ed8f16e1d50e3217425b3e98fb7a39e5d7201fe4b1dccfe8477b5c54761b24","service_charge":0.1,"number_of_delegates":10,"min_stake":0,"max_stake":1000000000000,"stat":{"sharder_rewards":1160553450000000},"node_type":"sharder","last_health_check":1619554377},"pending":{"01978379a586de2882638345e215baaf8382093609d910da5ac1a833e2814f6f":{"stats":{"delegate_id":"133807913c66ec0b4342612f23fecd1852b456152433b8380cd2abcd411d4c07","high":0,"low":-1,"interest_paid":0,"reward_paid":0,"number_rounds":0,"status":"PENDING"},"pool":{"pool":{"id":"01978379a586de2882638345e215baaf8382093609d910da5ac1a833e2814f6f","balance":10000000000},"lock":{"delete_view_change_set":false,"delete_after_view_change":0,"owner":"ff12c78ee4a985b4fc2ac52ec8a24e9df2bd912636da15437b0eb7707b99abf4"}}}}}

Reformatted output

{
  "simple_miner":{
    "id":"68ed8f16e1d50e3217425b3e98fb7a39e5d7201fe4b1dccfe8477b5c54761b24",
    "n2n_host":"demo1.zus.network",
    "host":"demo1.zus.network",
    "port":31102,
    "path":"sharder02",
    "public_key":"458170c28496333426f9866989f7b335564d13d00f50db503275e7ec50a008031764ba5df42c20c85d76e7fe7eda43f39afdb650b8ffa9ed340e6fc50c35ae22",
    "short_name":"localhost.s02",
    "build_tag":"50fb047353c4c3d268c0e0ebfd8e63f1d10c6813",
    "total_stake":0,
    "delegate_wallet":"68ed8f16e1d50e3217425b3e98fb7a39e5d7201fe4b1dccfe8477b5c54761b24",
    "service_charge":0.1,
    "number_of_delegates":10,
    "min_stake":0,
    "max_stake":1000000000000,
    "stat":{
      "sharder_rewards":1160553450000000
    },
    "node_type":"sharder",
    "last_health_check":1619554377
  },
  "pending":{
    "01978379a586de2882638345e215baaf8382093609d910da5ac1a833e2814f6f":{
      "stats":{
        "delegate_id":"133807913c66ec0b4342612f23fecd1852b456152433b8380cd2abcd411d4c07",
        "high":0,
        "low":-1,
        "interest_paid":0,
        "reward_paid":0,
        "number_rounds":0,
        "status":"PENDING"
      },
      "pool":{
        "pool":{
          "id":"01978379a586de2882638345e215baaf8382093609d910da5ac1a833e2814f6f",
          "balance":10000000000
        },
        "lock":{
          "delete_view_change_set":false,
          "delete_after_view_change":0,
          "owner":"ff12c78ee4a985b4fc2ac52ec8a24e9df2bd912636da15437b0eb7707b99abf4"
        }
      }
    }
  }
}

Locking a stake on a node - mn-lock

Staking tokens on a node gains additional tokens over time. Tokens locked for staking can be unlocked anytime although have to wait for the next view change cycle.

Note however that if a node becomes offline, all stake pools are automatically unlocked and tokens are returned to wallets.

Parameter	Required	Description	Default	Valid Values
--miner_id	Yes*	Node ID of a miner to stake for (get at ls-miners)
--sharder_id	Yes*	Node ID of a sharder to stake for (get at ls-sharders)
--tokens	Yes	Amounts of token to stake		1000 - 1997000

At most one of miner_id / sharder_id needs to be passed.

You can use sp-lock command from zboxcli to stake tokens against a blobber, validator ot authorizer.

Sample command

./zwallet mn-lock --id dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a --tokens 1

The output would print the stake pool id.

locked with: b488738546d84aed9d3dcb2bbe24c161bc4338638669e64e814631efd430fd85

If the locking of stakes is failing, verify the following.

1. Wallet has enough tokens
2. Node ID is valid
3. Node has available delegate

Getting the stake pools of a wallet - mn-user-info

Parameter	Required	Description	Default	Valid Values
--client_id	No	Client ID of the wallet	Wallet at ~/.zcn/wallet.json
--json	No	Print output as JSON

Sample command

./zwallet mn-user-info

Sample output

- node: dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a (sharder)
  - pool_id:        b488738546d84aed9d3dcb2bbe24c161bc4338638669e64e814631efd430fd85
    balance:        1
    interests paid: 0
    rewards paid:   0
    status:         pending
    stake %:        100 %

Sample reformatted JSON output

{
  "pools":{
    "sharder":{
      "dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a":[
        {
          "id":"b488738546d84aed9d3dcb2bbe24c161bc4338638669e64e814631efd430fd85",
          "balance":10000000000,
          "interest_paid":0,
          "reward_paid":0,
          "status":"PENDING",
          "high":0,
          "low":-1
        }
      ]
    }
  }
}

Getting the stake pool info - mn-pool-info

Parameter	Required	Description	Default	Valid Values
--id	Yes	Node ID of a miner or sharder (get at ls-miners or ls-sharders)

Sample command

./zwallet mn-pool-info --id dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a

Sample output

{"pool_id":"4db8e916a7fa73f79097adf11d47bd535ac5fe3566e26b0e71d205c0171181df","balance":1000000000,"reward":152712000000,"status":0,"round_created":632,"delegate_id":"c542815b92849bae60032761e71eab2ba0c703589252cabbc38d48b5846e38bf","staked_at":1658695083}

Reformatted output

{
  "pool_id":"4db8e916a7fa73f79097adf11d47bd535ac5fe3566e26b0e71d205c0171181df",
  "balance":1000000000,
  "reward":152712000000,
  "status":0,
  "round_created":632,
  "delegate_id":"c542815b92849bae60032761e71eab2ba0c703589252cabbc38d48b5846e38bf",
  "staked_at":1658695083
}

If the pool-id flag is not present, a list of pools will be returned. Sample command

./zwallet mn-pool-info --id dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a

Sample output

[{"pool_id":"4db8e916a7fa73f79097adf11d47bd535ac5fe3566e26b0e71d205c0171181df","balance":1000000000,"reward":12096000000,"status":1,"round_created":632,"delegate_id":"c542815b92849bae60032761e71eab2ba0c703589252cabbc38d48b5846e38bf","staked_at":1658695083}]

Reformatted output

[
  {
    "pool_id":"4db8e916a7fa73f79097adf11d47bd535ac5fe3566e26b0e71d205c0171181df",
    "balance":1000000000,
    "reward":12096000000,
    "status":1,
    "round_created":632,
    "delegate_id":"c542815b92849bae60032761e71eab2ba0c703589252cabbc38d48b5846e38bf",
    "staked_at":1658695083
  }
]

Unlock a stake - mn-unlock

Parameter	Required	Description	Default	Valid Values
--miner_id	Yes*	Node ID of a miner to stake for (get at ls-miners)
--sharder_id	Yes*	Node ID of a sharder to stake for (get at ls-sharders)

At most one of miner_id / sharder_id needs to be passed

./zwallet mn-unlock --id dc8c6c93fb42e7f6d1c0f93baf66cc77e52725f79c3428a37da28e294aa2319a

Output

tokens will be unlocked next VC

Tokens are released on the next view change cycle or at the next reward round.

Killing/Deleting a node

Killing a miner - mn-kill

Miners can only be killed by the node's delegate wallet / owner

Parameter	Required	Description	Default	Valid Values
--id	Yes	Node ID of a miner

Sample command

./zwallet mn-kill --id 860498ec586ef5122efbca77d1d9c215167913d0477830a5aab6a2eb106cb6c2

Killing a sharder - sh-kill

Sharders can only be killed by the node's delegate wallet / owner

Parameter	Required	Description	Default	Valid Values
--id	Yes	Node ID of a sharder

Sample command

./zwallet sh-kill --id 860498ec586ef5122efbca77d1d9c215167913d0477830a5aab6a2eb106cb6c2

Bridge Commands

Bridge Protocol is used to exchange tokens between Züs Network and Ethereum Network tokens.

Import Account - bridge-import-account

Import account to local key storage using mnemonic, protected with password

Parameter	Required	Description	Default	Valid Values
--account_index	No	Index of the account to use	0	int
--address_index	No	Index of the address to use	0	int
--bip32	No	Use BIP32 derivation path	false	boolean
--mnemonic	Yes	Ethereum mnemonic	0	string
--password	Yes	Password to lock and unlock account to sign transaction	0	string
--path	No	Home config directory	~/.zcn	string

Sample Command :

./zwallet bridge-import-account --mnemonic "{MNEMONIC}" --password {WALLET_PASSWORD}

Sample Response :

Imported account 0x7503125Cf087E20Ac07dd323513c9A6a6312DE56 to path: /Users/gaurboysm3pro/.zcn/wallets/UTC--2024-04-29T16-40-28.126055000Z--7503125cf087e9a6a6312de5620ac07dd323513c

List Accounts - bridge-list-accounts

List available ethereum accounts

Parameter	Required	Description	Default	Valid Values
--path	No	Home config directory	~/.zcn	string

Sample Command :

./zwallet bridge-list-accounts

Sample Response :

Ethereum available account:
0x7503125Cf087E9A6a6312DE5620Ac07dd323513c

Burn ETH - bridge-burn-eth

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--amount	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string
--retries	No	Num of seconds a transaction status check should run	60	int

Sample Command :

./zwallet bridge-burn-eth --amount 10

Sample Response :

Starting IncreaseBurnerAllowance transaction
Verification: IncreaseBurnerAllowance [OK]: 0xe9b7d008e1469e8256a62b571b43af29fac933e51b0f2cc715224ebc50948a23
Starting WZCN burn transaction
Verification: WZCN burn [OK]: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Burn BNT - bridge-burn-bnt

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--amount	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string
--retries	No	Num of seconds a transaction status check should run	60	int

Sample Command :

./zwallet bridge-burn-bnt --amount 10

Sample Response :

Starting IncreaseBurnerAllowance transaction
Verification: IncreaseBurnerAllowance [OK]: 0xe9b7d008e1469e8256a62b571b43af29fac933e51b0f2cc715224ebc50948a23
Starting WZCN burn transaction
Verification: WZCN burn [OK]: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Burn EURC - bridge-burn-eurc

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--amount	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string
--retries	No	Num of seconds a transaction status check should run	60	int

Sample Command :

./zwallet bridge-burn-eurc --amount 10

Sample Response :

Starting IncreaseBurnerAllowance transaction
Verification: IncreaseBurnerAllowance [OK]: 0xe9b7d008e1469e8256a62b571b43af29fac933e51b0f2cc715224ebc50948a23
Starting WZCN burn transaction
Verification: WZCN burn [OK]: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Burn USDC - bridge-burn-usdc

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--amount	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string
--retries	No	Num of seconds a transaction status check should run	60	int

Sample Command :

./zwallet bridge-burn-usdc --amount 10

Sample Response :

Starting IncreaseBurnerAllowance transaction
Verification: IncreaseBurnerAllowance [OK]: 0xe9b7d008e1469e8256a62b571b43af29fac933e51b0f2cc715224ebc50948a23
Starting WZCN burn transaction
Verification: WZCN burn [OK]: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Burn WZCN - bridge-burn-wzcn

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--amount	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string
--retries	No	Num of seconds a transaction status check should run	60	int

Sample Command :

./zwallet bridge-burn-wzcn --amount 10

Sample Response :

Starting IncreaseBurnerAllowance transaction
Verification: IncreaseBurnerAllowance [OK]: 0xe9b7d008e1469e8256a62b571b43af29fac933e51b0f2cc715224ebc50948a23
Starting WZCN burn transaction
Verification: WZCN burn [OK]: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Burn ZCN - bridge-burn-zcn

Burn eth tokens that will be minted on ZCN chain

Parameter	Required	Description	Default	Valid Values
--token	Yes	WZCN token amount to be burned		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string

Sample Command :

./zwallet bridge-burn-zcn --amount 10

Sample Response :

Executed smart contract successfully with txn:  1133e973106fdb953f10810836ad5f7435bf39acf3c302780a9299ab2202c6f2
Transaction completed successfully: 1133e973106fdb953f10810836ad5f7435bf39acf3c302780a9299ab2202c6f2

Verify Transaction - bridge-verify

Verify Ethereum transaction

Parameter	Required	Description	Default	Valid Values
--hash	Yes	Ethereum transaction hash		int
--chain_config	No	Chain config file name	config.yaml	string
--path	No	Home config directory	~/.zcn	string

Sample Command :

./zwallet bridge-verify --hash 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Sample Response :

Transaction verification success: 0xd64ef7e7d4d5e18a6f04221a9431ebba13fc06b16fbd03e86b4c6f0603aa10b3

Config

~/.zcn/config.yaml

~/.zcn/config.yaml is a required zwallet config.

Field	Description	Value type
block_worker	The URL to chain network DNS that provides the lists of miners and sharders	string
signature_scheme	The signature scheme used in the network. This would be bls0chain for most networks	string
min_submit	The desired minimum success ratio (in percent) to meet when submitting transactions to miners	integer
min_confirmation	The desired minimum success ratio (in percent) to meet when verifying transactions on sharders	integer
confirmation_chain_length	The desired chain length to meet when verifying transactions	integer

Override Network

Network nodes are automatically discovered using the block_worker provided on config file.

To override/limit the nodes used on zwallet, create ~/.zcn/network.yaml as shown below.

cat > ~/.zcn/network.yaml << EOF
miners:
  - http://demo1.zus.network:31201
  - http://demo1.zus.network:31202
  - http://demo1.zus.network:31203
sharders:
  - http://demo1.zus.network:31101
EOF

Overriding the nodes can be useful in local chain setup. In some cases, the block worker might return URLs with IP/alias only accessible within the docker network.