zwallet Commands

The following assumes your terminal’s working directory is inside the zwalletcli repo.

Global parameters

zwallet accepts global flags that override defaults and can be used with any command.

Parameter	Description	Default
-h, --help	Show help/parameters for the invoked command	—
--config	Config file name	config.yaml
--configDir	Config directory	~/.zcn
--network	Network override file name	network.yaml
--silent	Do not print detailed logs	false
--wallet	Wallet file name	wallet.json
--withNonce	Nonce to use for the transaction	0
--fee	Transaction fee to use	chain min if not set

Tip: add --json on commands that support it, and --verbose to see transaction hashes and diagnostic details.

---

Shell autocompletion

Command: zwallet completion [bash|zsh|fish|powershell] Generates completion scripts and prints enablement instructions for your shell.

Example:

zwallet completion bash    # or zsh / fish / powershell

See the sub‑command’s help for the exact enablement steps per shell.

---

Creating and restoring wallets

Create a wallet — create-wallet

Creates a wallet at the default location if none exists (~/.zcn/wallet.json).

./zwallet create-wallet

Sample output

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

Recover a wallet — recoverwallet

Restore a wallet from its mnemonics. Useful when moving to a new machine or after loss.

Parameters

Flag	Required	Description	Default
--mnemonic	Yes	The full mnemonic phrase for the wallet to recover	—
--offline	No	Recover without registering on chain	false

Example

./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"

Verify recovered file

cat ~/.zcn/recovered_wallet.json

---

Exploring network nodes

List miners — ls-miners

Lists miners using the Miner smart contract.

Parameters

Flag	Required	Description	Default	Values
--json	No	Print as JSON	—	—
--active	No	Only active miners	true	boolean
--all	No	Include all registered miners (page 1 by default)	—	—
--limit	No	Limit number returned	20	integer
--offset	No	Skip first N	—	integer
--stakable	No	Only miners accepting new delegates	false	boolean

Example

./zwallet ls-miners

Sample output

- ID:   cdb9b5a2...77a68bad2
- Host: demo1.zus.network
- Port: 31203
...

List sharders — ls-sharders

Lists sharders from the latest finalized Magic Block; use --all for all registered.

Parameters (same shape as miners)

Flag	Required	Description	Default	Values
--json	No	Print as JSON	—	—
--active	No	Only active sharders	true	boolean
--all	No	Include all registered sharders	—	—
--limit	No	Limit number returned	20	integer
--offset	No	Skip first N	—	integer
--stakable	No	Only sharders accepting new delegates	false	boolean

Example

./zwallet ls-sharders --all

Sample output (abridged)

MagicBlock Sharders
ID: 12e317e5...
  - N2NHost: demo1.zus.network
  - Host:    demo1.zus.network
  - Port:    31102
...

Registered Sharders
ID: 675502b6...
  - N2NHost: demo1.zus.network
  - Host:    demo1.zus.network
  - Port:    31101
...

List blobbers — getblobbers

Lists blobbers via the Storage smart contract.

Parameters

Flag	Required	Description
--all	No	Include inactive blobbers (if any)

Example

./zwallet getblobbers

Sample output (abridged)

Blobbers:
 URL                              | ID                                  | CAP                 | R / W PRICE     | DEMAND
 http://demo1.zus.network:31305   | 011a5444...                         | 271.5/1000.0 GiB    | 0.010/0.010     | 0.1
...

---

List authorizers — bridge-list-auth

Lists authorizers that validate client transactions.

./zwallet bridge-list-auth

Sample response

[
  {"id":"2f945f73...","url":"https://demo.zus.network/authorizer01/"},
  {"id":"7b07c048...","url":"https://demo.zus.network/authorizer02/"},
  {"id":"896c1716...","url":"https://demo.zus.network/authorizer03/"}
]

Get node ID by URL — getid

Prints a node’s ID from its URL (miner/sharder/blobber).

Parameter: --url <NODE_URL>

Example

./zwallet getid --url http://demo1.zus.network:31101
# URL: http://demo1.zus.network:31101
# ID:  675502b613ba1c59...

Storage SC config — sc-config

Displays current Storage smart contract configuration.

Parameter: --json (optional)

./zwallet sc-config

Sample output (abridged)

.blobber_slash 0.1
cost.new_allocation_request 3000
free_allocation_settings.data_shards 4
...
validators_per_challenge 2
writepool.min_lock 0.1

Version — version

Prints zwallet and GoSDK versions.

Parameter: --json (optional)

./zwallet version

Sample

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

Global chain configuration — global-config

Shows chain‑wide configuration (server_chain, tx, SC toggles, etc.).

./zwallet global-config

Sample output (abridged)

server_chain.block.consensus.threshold_by_count 66
server_chain.client.signature_scheme bls0chain
server_chain.smart_contract.storage true
server_chain.transaction.max_fee 0.01
server_chain.transaction.timeout 600
...

---

Getting and sending tokens

Faucet — faucet

(Where enabled) requests tokens from the Faucet smart contract.

./zwallet faucet

Check balance — getbalance

Retrieves wallet balances from sharders. (Locked tokens are not included.)

Parameter: --json (optional)

./zwallet getbalance
# Balance: 3 (4.2299999999999995 USD)

Use another wallet file:

./zwallet getbalance --wallet another_wallet.json

If the wallet has no tokens yet, the command will output Get balance failed.

Send tokens — send

Transfers tokens to another wallet.

Parameters

Flag	Required	Description
--json	No	Print as JSON
--to_client_id	Yes	Recipient’s client ID
--tokens	Yes	Amount to send
--desc	Yes	Transfer description
--fee	No	Optional tx fee (defaults to chain)

Example

./zwallet send \
  --to_client_id e7ebb698213b6bda097c0a14ccbe574356e99e9b666e4baeae540da1d9b51e7e \
  --tokens 0.2 \
  --desc "gift"
# Send tokens success

Use a different sender wallet:

./zwallet send --to_client_id <ID> --tokens 0.2 --desc "gift" --wallet another_wallet.json

Verify a transaction — verify

Checks whether a transaction hash is confirmed on chain.

Parameter

Flag	Required	Description
--hash	Yes	Transaction hash to verify

Not all commands print the transaction hash. Re‑run with --verbose to see hashes.

Example

./zwallet verify --hash 867c240b640e3d128643330af383cb3a0a229ebce08cae667edd7766c7ccc850
# Transaction verification success

Verbose:

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

Collect rewards — collect-reward

Transfers accrued stake‑pool rewards to your wallet. Rewards accrue for miners and sharders (and authorizers where applicable).

Parameters

Flag	Required	Description	Values
--provider_type	Yes	Provider type	miner / sharder / authorizer
--provider_id	Yes	Provider node ID	string

Example

./zwallet collect-reward --provider_type miner --provider_id <MINER_OR_SHARDER_ID>
# locked with: b4887385... (stake pool id)

Get nonce — getnonce

Shows the current nonce of the default wallet.

./zwallet getnonce
# Nonce: 58

---

Staking on miners and sharders

The Miner smart contract allows staking on miner and sharder nodes. The maximum number of stake pools per node is limited by the node’s delegates setting. Use mn-config to discover limits (min/max stake, delegates, etc.).

Staking config — mn-config

Displays global staking parameters of the Miner SC.

./zwallet mn-config

Sample output (abridged)

max_n: 8   min_n: 2   max_s: 3   min_s: 1
max_stake: 100  min_stake: 0  max_delegates: 200
interest_rate: 5.55e-07  reward_rate: 1  share_ratio: 0.8
...

Node info for staking — mn-info

Shows staking‑related stats for a miner or sharder.

Parameter

Flag	Required	Description
--id	Yes	Node ID (see ls-miners / ls-sharders)

Example

./zwallet mn-info --id 68ed8f16e1d50e32...

(See your output for JSON fields like service_charge, number_of_delegates, total_stake, pending pools, etc.)

Lock stake — mn-lock

Stake tokens on a node to earn rewards. If a node goes offline, stake pools are auto‑unlocked and funds are returned.

Parameters

Flag	Required	Description
--miner_id	Yes*	Miner node ID (alternative to --sharder_id)
--sharder_id	Yes*	Sharder node ID (alternative to --miner_id)
--tokens	Yes	Amount to stake (must meet min/max constraints)

*Pass either --miner_id or --sharder_id.

Some builds also accept --id <NODE_ID> as shown below.

Example

./zwallet mn-lock --id dc8c6c93fb42e7f6... --tokens 1
# locked with: b4887385... (stake pool id)

If locking fails, check:

• Wallet has sufficient tokens

• Node ID is valid

• Node has delegate capacity available

Your stake pools — mn-user-info

Shows the wallet’s stake pools.

Parameters

Flag	Required	Description	Default
--client_id	No	Client ID to query	wallet at ~/.zcn/wallet.json
--json	No	Print as JSON	—

Example

./zwallet mn-user-info

Sample output (text)

- node: dc8c6c93... (sharder)
  - pool_id: b4887385...
    balance: 1
    interests paid: 0
    rewards paid: 0
    status: pending
    stake %: 100 %

Sample (JSON)

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

Stake pool info — mn-pool-info

Shows stake pool info for a given node. Without a pool flag, returns the list.

Parameter

Flag	Required	Description
--id	Yes	Node ID (miner or sharder)

Example

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

Sample (single)

{"pool_id":"4db8e916...","balance":1000000000,"reward":152712000000,"status":0,"round_created":632,"delegate_id":"c542815b...","staked_at":1658695083}

Sample (list)

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

Unlock stake — mn-unlock

Requests unlock of a stake from a node; tokens are released at the next view change or reward round.

Parameters

Flag	Required	Description
--miner_id	Yes*	Miner node ID
--sharder_id	Yes*	Sharder node ID

*Pass either --miner_id or --sharder_id.

Example

./zwallet mn-unlock --id dc8c6c93fb42e7f6...
# tokens will be unlocked next VC

---

Killing / deleting nodes

Requires the node’s delegate wallet / owner.

Kill a miner — mn-kill

./zwallet mn-kill --id 860498ec586ef5122efb...

Kill a sharder — sh-kill

./zwallet sh-kill --id 860498ec586ef5122efb...

---

Notes & tips

• For transaction hashes, use --verbose if a command doesn’t print the hash by default.

• Staking unlocks occur at the next view change or reward round—tokens won’t be immediately liquid.

• Some staking commands accept --id <NODE_ID> interchangeably with --miner_id / --sharder_id as shown above.

• When using Faucet or Bridge, ensure the target network supports those smart contracts in global-config / sc-config.