# 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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zus.network/zus-docs/clis/zwalletcli/zwallet-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.