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

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

Print as JSON

—

--active

Only active miners

true

boolean

--all

Include all registered miners (page 1 by default)

—

--limit

Limit number returned

20

integer

--offset

Skip first N

—

integer

--stakable

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

Print as JSON

—

--active

Only active sharders

true

boolean

--all

Include all registered sharders

—

--limit

Limit number returned

20

integer

--offset

Skip first N

—

integer

--stakable

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

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

Print as JSON

--to_client_id

Yes

Recipient’s client ID

--tokens

Yes

Amount to send

--desc

Yes

Transfer description

--fee

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

Client ID to query

wallet at ~/.zcn/wallet.json

--json

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.

PreviousWallet Configuration NextGuides and Workflows

Last updated 3 months ago

Global parameters

Shell autocompletion

Creating and restoring wallets

Create a wallet — create-wallet

Recover a wallet — recoverwallet

Exploring network nodes

List miners — ls-miners

List sharders — ls-sharders

List blobbers — getblobbers

List authorizers — bridge-list-auth

Get node ID by URL — getid

Storage SC config — sc-config

Version — version

Global chain configuration — global-config

Getting and sending tokens

Faucet — faucet

Check balance — getbalance

Send tokens — send

Verify a transaction — verify

Collect rewards — collect-reward

Get nonce — getnonce

Staking on miners and sharders

Staking config — mn-config

Node info for staking — mn-info

Lock stake — mn-lock

Your stake pools — mn-user-info

Stake pool info — mn-pool-info

Unlock stake — mn-unlock

Killing / deleting nodes

Kill a miner — mn-kill

Kill a sharder — sh-kill

Notes & tips

Create a wallet — `create-wallet`

Recover a wallet — `recoverwallet`

List miners — `ls-miners`

List sharders — `ls-sharders`

List blobbers — `getblobbers`

List authorizers — `bridge-list-auth`

Get node ID by URL — `getid`

Storage SC config — `sc-config`

Version — `version`

Global chain configuration — `global-config`

Faucet — `faucet`

Check balance — `getbalance`

Send tokens — `send`

Verify a transaction — `verify`

Collect rewards — `collect-reward`

Get nonce — `getnonce`

Staking config — `mn-config`

Node info for staking — `mn-info`

Lock stake — `mn-lock`

Your stake pools — `mn-user-info`

Stake pool info — `mn-pool-info`

Unlock stake — `mn-unlock`

Kill a miner — `mn-kill`

Kill a sharder — `sh-kill`