> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/clis/zwalletcli/zwallet-commands.md).

# 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:

```bash
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`).

```bash
./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**

```bash
./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**

```bash
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**

```bash
./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**

```bash
./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**

```bash
./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.

```bash
./zwallet bridge-list-auth
```

**Sample response**

```json
[
  {"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**

```bash
./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)

```bash
./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)

```bash
./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.).

```bash
./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.

```bash
./zwallet faucet
```

#### Check balance — `getbalance`

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

**Parameter**: `--json` (optional)

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

Use another wallet file:

```bash
./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**

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

Use a different sender wallet:

```bash
./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**

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

Verbose:

```bash
./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**

```bash
./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.

```bash
./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.

```bash
./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**

```bash
./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**

```bash
./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**

```bash
./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)**

```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**

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

**Sample (single)**

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

**Sample (list)**

```json
[{"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**

```bash
./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`

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

#### Kill a sharder — `sh-kill`

```bash
./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`.