# Verus Wiki — Full Content

> This file contains the complete content of every page on the Verus Wiki.
> Site: https://wiki.autobb.app
> Generated: 2026-05-15

--- PAGE: command-reference/addressindex.md ---

---
label: Address Index
icon: terminal
---


# Address Index Commands

> **Placeholder convention:** Examples in this reference use `<R-address>` for the queried address and `i...` to mark a placeholder currency i-address (substitute the real one from `getcurrency`). Commands shown were tested on VRSCTEST — only project-specific values have been genericized.

---

## getaddressbalance

> **Category:** Addressindex | **Version:** v1.2.14+

Returns the balance for one or more addresses. Requires `-addressindex=1` to be enabled.

**Syntax**

```
getaddressbalance {"addresses": ["address", ...], "friendlynames": bool}
```

**Parameters**

| Parameter     | Type    | Required | Description |
|---------------|---------|----------|-------------|
| addresses     | array   | Yes      | Array of base58check encoded addresses |
| friendlynames | boolean | No       | Include friendly names keyed by currency i-addresses |

**Result**

```json
{
  "balance": 0,
  "received": 0,
  "currencybalance": {
    "iCurrencyID": 0.00000000
  },
  "currencyreceived": {
    "iCurrencyID": 0.00000000
  }
}
```

| Field    | Type    | Description |
|----------|---------|-------------|
| balance  | numeric | Current balance in satoshis |
| received | numeric | Total satoshis received (including change) |
| currencybalance | object | Per-currency balances keyed by currency i-address (values in currency units, not satoshis) |
| currencyreceived | object | Per-currency total received keyed by currency i-address (values in currency units) |

**Examples**

```bash
verus -testnet getaddressbalance '{"addresses": ["<R-address>"]}'
```

**Testnet output (address with multi-currency balance):**
```json
{
  "balance": 5288370000,
  "received": 52814070000,
  "currencybalance": {
    "i...": 109.99000000,
    "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 52.88370000
  },
  "currencyreceived": {
    "i...": 109.99000000,
    "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 528.14070000
  }
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |
| `Invalid address` | Malformed address string |

**Related Commands**

- [`getaddressutxos`](#getaddressutxos) — Get unspent outputs for an address
- [`getaddressdeltas`](#getaddressdeltas) — Get all changes for an address
- [`getaddresstxids`](#getaddresstxids) — Get transaction IDs for an address

**Notes**

- Requires the daemon to be started with `-addressindex=1`.
- Balance is returned in satoshis (1 VRSC = 100,000,000 satoshis).
- Can query multiple addresses at once — balances are aggregated.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (addressindex enabled)

---

## getaddressdeltas

> **Category:** Addressindex | **Version:** v1.2.14+

Returns all changes (deltas) for an address. Requires `-addressindex=1`.

**Syntax**

```
getaddressdeltas {"addresses": ["address"], "start": n, "end": n, "chaininfo": bool, "friendlynames": bool, "verbosity": n, "vdxftag": "string"}
```

**Parameters**

| Parameter     | Type    | Required | Description |
|---------------|---------|----------|-------------|
| addresses     | array   | Yes      | Array of base58check encoded addresses |
| start         | number  | No       | Start block height |
| end           | number  | No       | End block height |
| chaininfo     | boolean | No       | Include chain info (only with start/end) |
| friendlynames | boolean | No       | Include friendly names keyed by currency i-addresses |
| verbosity     | number  | No       | 0 (default) or 1 (include output info with reserve amounts) |
| vdxftag       | string  | No       | Optional X-address (indexId) to filter by VDXF tag |

**Result**

```json
[
  {
    "satoshis": 0,
    "txid": "...",
    "index": 0,
    "height": 0,
    "address": "..."
  }
]
```

**Examples**

```bash
verus -testnet getaddressdeltas '{"addresses": ["<R-address>"], "start": 926980, "end": 926990}'
```

**Testnet output:**
```json
[]
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |

**Related Commands**

- [`getaddressbalance`](#getaddressbalance) — Current balance
- [`getaddresstxids`](#getaddresstxids) — Just transaction IDs
- [`getaddressmempool`](#getaddressmempool) — Mempool-only deltas

**Notes**

- Use `start` and `end` to limit the block range and improve performance.
- Positive `satoshis` = received, negative = spent.
- The `vdxftag` filter is useful for querying VDXF-tagged outputs.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getaddressmempool

> **Category:** Addressindex | **Version:** v1.2.14+

Returns all mempool deltas for an address. Requires `-addressindex=1`.

**Syntax**

```
getaddressmempool {"addresses": ["address"], "friendlynames": bool, "verbosity": n}
```

**Parameters**

| Parameter     | Type    | Required | Description |
|---------------|---------|----------|-------------|
| addresses     | array   | Yes      | Array of base58check encoded addresses |
| friendlynames | boolean | No       | Include friendly names keyed by currency i-addresses |
| verbosity     | number  | No       | 0 (default) or 1 (include output info) |

**Result**

```json
[
  {
    "address": "...",
    "txid": "...",
    "index": 0,
    "satoshis": 0,
    "timestamp": 0,
    "prevtxid": "...",
    "prevout": "..."
  }
]
```

**Examples**

```bash
verus -testnet getaddressmempool '{"addresses": ["<R-address>"]}'
```

**Testnet output:**
```json
[]
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |

**Related Commands**

- [`getaddressdeltas`](#getaddressdeltas) — Confirmed deltas
- [`getaddressbalance`](#getaddressbalance) — Current confirmed balance

**Notes**

- Only shows unconfirmed (mempool) transactions.
- `prevtxid` and `prevout` are present for spending transactions.
- Empty result means no pending mempool transactions for the address.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getaddresstxids

> **Category:** Addressindex | **Version:** v1.2.14+

Returns the transaction IDs for one or more addresses. Requires `-addressindex=1`.

**Syntax**

```
getaddresstxids {"addresses": ["address"], "start": n, "end": n}
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| addresses | array  | Yes      | Array of base58check encoded addresses |
| start     | number | No       | Start block height |
| end       | number | No       | End block height |

**Result**

```json
[
  "transactionid",
  ...
]
```

**Examples**

```bash
verus -testnet getaddresstxids '{"addresses": ["<R-address>"]}'
```

**Testnet output:**
```json
[]
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |

**Related Commands**

- [`getaddressbalance`](#getaddressbalance) — Balance summary
- [`getaddressdeltas`](#getaddressdeltas) — Full delta details
- [`getaddressutxos`](#getaddressutxos) — Unspent outputs

**Notes**

- Use `start`/`end` to limit the block range for large address histories.
- Returns deduplicated transaction IDs.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getaddressutxos

> **Category:** Addressindex | **Version:** v1.2.14+

Returns all unspent outputs for one or more addresses. Requires `-addressindex=1`.

**Syntax**

```
getaddressutxos {"addresses": ["address"], "chaininfo": bool, "friendlynames": bool, "verbosity": n}
```

**Parameters**

| Parameter     | Type    | Required | Description |
|---------------|---------|----------|-------------|
| addresses     | array   | Yes      | Array of base58check encoded addresses |
| chaininfo     | boolean | No       | Include chain info with results |
| friendlynames | boolean | No       | Include friendly names keyed by currency i-addresses |
| verbosity     | number  | No       | 0 (default) or 1 (include detailed output info) |

**Result**

```json
[
  {
    "address": "...",
    "txid": "...",
    "height": 0,
    "outputIndex": 0,
    "script": "...",
    "satoshis": 0
  }
]
```

**Examples**

```bash
verus -testnet getaddressutxos '{"addresses": ["<R-address>"]}'
```

**Testnet output:**
```json
[]
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |

**Related Commands**

- [`getaddressbalance`](#getaddressbalance) — Aggregated balance
- [`getaddresstxids`](#getaddresstxids) — Transaction IDs only
- [`getaddressdeltas`](#getaddressdeltas) — All changes including spent

**Notes**

- Returns only unspent outputs (UTXOs), not spent ones.
- `script` is the hex-encoded scriptPubKey.
- `satoshis` values can be used to construct raw transactions.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getsnapshot

> **Category:** Addressindex | **Version:** v1.2.14+

Returns a snapshot of (address, amount) pairs at the current height. Requires `-addressindex=1`.

**Syntax**

```
getsnapshot (top)
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| top       | number  | No       | Only return this many addresses (top N richlist) |

**Result**

```json
{
  "addresses": [
    {
      "addr": "RMEBhzvATA8mrfVK82E5TgPzzjtaggRGN3",
      "amount": "100.0"
    }
  ],
  "total": 123.45,
  "average": 61.7,
  "utxos": 14,
  "total_addresses": 2,
  "start_height": 91,
  "ending_height": 91,
  "start_time": 1531982752,
  "end_time": 1531982752
}
```

| Field           | Type    | Description |
|-----------------|---------|-------------|
| addresses       | array   | List of address/amount pairs |
| total           | numeric | Total amount in snapshot |
| average         | numeric | Average amount per address |
| utxos           | number  | Total number of UTXOs |
| total_addresses | number  | Total number of addresses |
| start_height    | number  | Block height when snapshot began |
| ending_height   | number  | Block height when snapshot finished |
| start_time      | number  | Unix epoch time snapshot started |
| end_time        | number  | Unix epoch time snapshot finished |

**Examples**

```bash
## Get top 5 addresses by balance
verus -testnet getsnapshot 5

## Get full snapshot (can be very slow on large chains)
verus -testnet getsnapshot
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Addressindex not enabled` | Node not started with `-addressindex=1` |

**Related Commands**

- [`getaddressbalance`](#getaddressbalance) — Balance for specific addresses
- [`getaddressutxos`](#getaddressutxos) — UTXOs for specific addresses

**Notes**

- ⚠️ **Performance warning**: Without the `top` parameter, this scans the entire UTXO set and can take a very long time on chains with many addresses.
- Useful for generating richlist data or distribution analysis.
- The snapshot is taken at the current block height.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2
- Note: Full snapshot timed out due to large UTXO set; use `top` parameter for practical use.

--- PAGE: command-reference/blockchain.md ---

---
label: Blockchain
icon: terminal
---


# Blockchain Commands


---

## coinsupply

> **Category:** Blockchain | **Version:** v1.2.x+

Returns coin supply information at a given block height, including transparent, shielded, and total supply.

**Syntax**

```
coinsupply <height>
```

**Parameters**

| Parameter | Type    | Required | Description                                      |
|-----------|---------|----------|--------------------------------------------------|
| height    | integer | No       | Block height to query. Defaults to current height |

**Result**

```json
{
  "result": "success",    // (string) If the request was successful
  "coin": "VRSC",         // (string) The currency symbol of the native coin
  "height": 420,           // (integer) The height of this coin supply data
  "supply": "777.0",      // (float) The transparent coin supply
  "zfunds": "0.777",      // (float) The shielded coin supply (in zaddrs)
  "total": "777.777"      // (float) The total coin supply (supply + zfunds)
}
```

**Examples**

**Basic Usage**

```bash
verus coinsupply
verus coinsupply 420
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "coinsupply", "params": [420]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Check total supply** — verify circulating supply at any block height
- **Audit shielded vs transparent** — compare `supply` vs `zfunds`
- **Historical supply analysis** — query at specific heights to track emission

**Common Errors**

| Error | Cause |
|-------|-------|
| Block height out of range | Height exceeds current chain tip |

> **Note:** Querying `coinsupply` at the current height on a large chain can be slow as it iterates blocks.

**Related Commands**

- [`getblockcount`](#getblockcount) — get current block height
- [`getblockchaininfo`](#getblockchaininfo) — general chain state info

**Notes**

- When called without a height parameter, uses the current chain tip
- The `total` field equals `supply` + `zfunds`
- Can be slow on chains with many blocks as it scans the full UTXO set

**Tested On**

- **VRSCTEST** testnet, block ~926992, Verus v1.2.14-2
- Note: Command caused RPC lock during heavy load testing; help-only documentation

---

## getbestblockhash

> **Category:** Blockchain | **Version:** v1.2.x+

Returns the hash of the best (tip) block in the longest block chain.

**Syntax**

```
getbestblockhash
```

**Parameters**

None.

**Result**

```
"hex"      (string) the block hash hex encoded
```

**Examples**

**Basic Usage**

```bash
verus getbestblockhash
```

**Testnet output:**
```
0000000107058c677dbae2fa57cfde4f2ffc7dd82d157f208bcdd4d33f800741
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getbestblockhash", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Check chain tip** — quickly verify what block the node considers the best
- **Monitor sync** — compare with other nodes or explorers
- **Input to getblock** — use returned hash to fetch full block data

**Common Errors**

None typical — this is a simple read-only query.

**Related Commands**

- [`getblockcount`](#getblockcount) — get the height of the best chain
- [`getblock`](#getblock) — get full block details by hash
- [`getblockhash`](#getblockhash) — get hash at a specific height

**Notes**

- Returns the hash of the tip of the chain with the most work (not necessarily most blocks)
- Very fast, no parameters needed

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getblock

> **Category:** Blockchain | **Version:** v1.2.x+

Returns data about a block by hash or height, with configurable verbosity levels.

**Syntax**

```
getblock "hash|height" ( verbosity )
```

**Parameters**

| Parameter   | Type             | Required | Description                                                  |
|-------------|------------------|----------|--------------------------------------------------------------|
| hash\|height | string/numeric  | Yes      | The block hash or block height                               |
| verbosity   | numeric          | No       | 0 = hex data, 1 = JSON object (default), 2 = JSON with tx data |

**Result**

**Verbosity 0**

```
"data"    (string) Serialized, hex-encoded block data
```

**Verbosity 1 (default)**

```json
{
  "hash": "hash",                    // (string) the block hash
  "confirmations": n,                // (numeric) number of confirmations, -1 if not on main chain
  "size": n,                         // (numeric) block size
  "height": n,                       // (numeric) block height
  "version": n,                      // (numeric) block version
  "merkleroot": "xxxx",             // (string) merkle root
  "finalsaplingroot": "xxxx",       // (string) Sapling commitment tree root
  "tx": ["transactionid", ...],     // (array) transaction ids
  "time": ttt,                       // (numeric) block time (epoch)
  "nonce": n,                        // (numeric) the nonce
  "bits": "1d00ffff",               // (string) the bits
  "difficulty": x.xxx,              // (numeric) the difficulty
  "previousblockhash": "hash",      // (string) previous block hash
  "nextblockhash": "hash"           // (string) next block hash
}
```

**Verbosity 2**

Same as verbosity 1, but `tx` contains full transaction objects (as from `getrawtransaction`).

**Examples**

**Basic Usage**

```bash
## By height (verbosity 1, default)
verus getblock 1000
```

**Testnet output (trimmed):**
```json
{
  "hash": "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0",
  "validationtype": "stake",
  "confirmations": 925997,
  "size": 3988,
  "height": 1000,
  "version": 65540,
  "merkleroot": "ee99aaccd5d98bcc5ce537294bb006e8d947b583fc6e2d0b3b3998ae9e4cd7d0",
  "finalsaplingroot": "3e49b5f954aa9d3545bc6c37744661eea48d7c34e3000d82b7f0010c30f4c2fb",
  "tx": [
    "cbd974e07c3ea76af60f2a4eac5135a8a248df701797f4072890f43c496897cc",
    "db63760e392d230939622994599b94066e5a914e2aad327c4d5de4678ad362e1"
  ],
  "time": 1713100429,
  "bits": "1d01681a",
  "difficulty": 179608081.3173367,
  "blocktype": "minted",
  "previousblockhash": "0000000042c11594856f338aac51f5b9199c3fb9a684506f00c53df29338b152",
  "nextblockhash": "00000000f014cd16d8b3746e277e96357910e4544281d7f5517b1d5ccf757830"
}
```

```bash
## By hash
verus getblock "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0"

## Hex-encoded (verbosity 0)
verus getblock 1000 0

## With full transaction data (verbosity 2)
verus getblock 1000 2
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblock", "params": ["1000"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Block explorer functionality** — retrieve all data about a block
- **Transaction listing** — get all txids in a block (verbosity 1) or full tx data (verbosity 2)
- **Chain analysis** — walk the chain via `previousblockhash`/`nextblockhash`

**Common Errors**

| Error | Cause |
|-------|-------|
| Block not found | Invalid hash or height beyond chain tip |
| Block height out of range | Negative or too-large height value |

**Related Commands**

- [`getblockhash`](#getblockhash) — get hash at a specific height
- [`getblockheader`](#getblockheader) — lighter weight, header only
- [`getbestblockhash`](#getbestblockhash) — get tip block hash

**Notes**

- Accepts both hash strings and numeric heights
- Verbosity 2 can return very large responses for blocks with many transactions
- The `finalsaplingroot` field is Verus/Zcash-specific (Sapling commitment tree)

**Tested On**

- **VRSCTEST** testnet, block ~926992, Verus v1.2.14-2
- Live tested with block 1000 (staked block)

---

## getblockchaininfo

> **Category:** Blockchain | **Version:** v1.2.x+

Returns an object containing various state info regarding block chain processing.

**Syntax**

```
getblockchaininfo
```

**Parameters**

None.

**Result**

```json
{
  "chain": "xxxx",                    // (string) network type (main, test, regtest)
  "name": "xxxx",                     // (string) network name (VRSC, VRSCTEST, PBAASNAME)
  "chainid": "xxxx",                  // (string) blockchain ID (i-address)
  "blocks": 926992,                   // (numeric) blocks processed
  "headers": 926992,                  // (numeric) headers validated
  "bestblockhash": "...",             // (string) best block hash
  "difficulty": 72291476.38,          // (numeric) current difficulty
  "verificationprogress": 0.999,      // (numeric) verification progress [0..1]
  "chainwork": "xxxx",               // (string) total chain work (hex)
  "size_on_disk": 12345678,          // (numeric) estimated block data size on disk
  "commitments": 123456,             // (numeric) number of note commitments in the commitment tree
  "softforks": [                      // (array) softfork status
    {
      "id": "xxxx",                   // (string) softfork name
      "version": 4,                   // (numeric) block version
      "enforce": {
        "status": true,               // (boolean) threshold reached
        "found": 100,                 // (numeric) blocks with new version found
        "required": 51,               // (numeric) blocks required to trigger
        "window": 100                 // (numeric) window size
      },
      "reject": { }                   // (object) same fields as enforce
    }
  ],
  "upgrades": {                       // (object) network upgrade status
    "xxxxxxxx": {                     // (string) branch ID
      "name": "xxxx",                // (string) upgrade name
      "activationheight": 100,        // (numeric) activation height
      "status": "active",            // (string) upgrade status
      "info": "xxxx"                 // (string) additional info
    }
  },
  "pruned": false,                     // (boolean) if the blocks are subject to pruning
  "valuePools": [                      // (array) shielded pool chain values
    {
      "id": "sprout",                  // (string) pool name
      "chainValue": 0.00000000         // (numeric) total value held in pool
    }
  ],
  "consensus": {                      // (object) consensus branch IDs
    "chaintip": "xxxxxxxx",          // (string) current chain tip branch ID
    "nextblock": "xxxxxxxx"          // (string) next block branch ID
  }
}
```

**Examples**

**Basic Usage**

```bash
verus getblockchaininfo
```

**Testnet output (trimmed):**
```json
{
  "chain": "test",
  "name": "VRSCTEST",
  "chainid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "blocks": 926996,
  "headers": 926996,
  "bestblockhash": "00000003a59f522a082e4c34f921c2e5ef44ebe8db410b1d6484787e271df2a2",
  "difficulty": 53500896.94362766,
  "verificationprogress": 1,
  "chainwork": "00000000000000000000000000000000000000000000000000070a060d324f5b",
  "pruned": false,
  "size_on_disk": 4206361361,
  "valuePools": [
    { "id": "sprout", "chainValue": 0.00000000 },
    { "id": "sapling", "chainValue": 3880.68540983 }
  ],
  "softforks": [
    { "id": "bip34", "version": 2, "enforce": { "status": true } },
    { "id": "bip66", "version": 3, "enforce": { "status": true } },
    { "id": "bip65", "version": 4, "enforce": { "status": true } }
  ],
  "upgrades": {
    "5ba81b19": { "name": "Overwinter", "activationheight": 1, "status": "active" },
    "76b809bb": { "name": "Sapling", "activationheight": 1, "status": "active" }
  },
  "consensus": { "chaintip": "76b809bb", "nextblock": "76b809bb" }
}
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Check sync status** — compare `blocks` vs `headers`, check `verificationprogress`
- **Network identification** — verify `chain`, `name`, `chainid`
- **Upgrade monitoring** — check `upgrades` for activation status
- **Consensus tracking** — monitor `consensus.chaintip` vs `consensus.nextblock`

**Common Errors**

None typical — read-only query.

**Related Commands**

- [`getblockcount`](#getblockcount) — just the block count
- [`getbestblockhash`](#getbestblockhash) — just the tip hash
- [`getdifficulty`](#getdifficulty) — just the difficulty
- [`getchaintips`](#getchaintips) — all chain tips including forks

**Notes**

- When the chain tip is at the last block before a network upgrade activation, `consensus.chaintip != consensus.nextblock`
- The `chainid` is the i-address of the native blockchain currency
- `verificationprogress` is an estimate; 1.0 means fully synced
- PBaaS chain names appear in the `name` field

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getblockcount

> **Category:** Blockchain | **Version:** v1.2.x+

Returns the number of blocks in the best valid block chain.

**Syntax**

```
getblockcount
```

**Parameters**

None.

**Result**

```
n    (numeric) The current block count
```

**Examples**

**Basic Usage**

```bash
verus getblockcount
```

**Testnet output:**
```
926992
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockcount", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Monitor sync progress** — compare with known chain height
- **Input to other commands** — use as height for `getblockhash`, `coinsupply`, etc.
- **Script automation** — check if node is caught up before running operations

**Common Errors**

None typical.

**Related Commands**

- [`getbestblockhash`](#getbestblockhash) — hash of the tip block
- [`getblockhash`](#getblockhash) — get hash at a specific height
- [`getblockchaininfo`](#getblockchaininfo) — comprehensive chain state

**Notes**

- Returns the height of the tip of the best (most-work) chain
- Very fast, lightweight query

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getblockdeltas

> **Category:** Blockchain | **Version:** v1.2.x+

Returns information about the given block and its transactions, including input/output deltas per transaction.

**Syntax**

```
getblockdeltas "blockhash"
```

**Parameters**

| Parameter | Type   | Required | Description    |
|-----------|--------|----------|----------------|
| blockhash | string | Yes      | The block hash |

**Prerequisites**

⚠️ **This command requires experimental features.** You must restart the daemon with:

```
-experimentalfeatures -insightexplorer
```

Or add to config file:
```
experimentalfeatures=1
insightexplorer=1
```

**Result**

```json
{
  "hash": "hash",              // (string) block ID
  "confirmations": n,          // (numeric) confirmations
  "size": n,                   // (numeric) block size in bytes
  "height": n,                 // (numeric) block height
  "version": n,                // (numeric) block version
  "merkleroot": "hash",       // (string) Merkle root
  "deltas": [
    {
      "txid": "hash",         // (string) transaction ID
      "index": n,              // (numeric) tx offset in block
      "inputs": [
        {
          "address": "taddr", // (string) transparent address
          "satoshis": n,       // (numeric) negative of spend amount
          "index": n,          // (numeric) vin index
          "prevtxid": "hash", // (string) source utxo tx ID
          "prevout": n         // (numeric) source utxo index
        }
      ],
      "outputs": [
        {
          "address": "taddr", // (string) transparent address
          "satoshis": n,       // (numeric) amount
          "index": n           // (numeric) vout index
        }
      ]
    }
  ],
  "time": n,                   // (numeric) block time
  "mediantime": n,             // (numeric) median time of recent blocks
  "nonce": "nonce",           // (string) nonce
  "bits": "1d00ffff",         // (string) bits
  "difficulty": n,             // (numeric) difficulty
  "chainwork": "xxxx",        // (string) total chain work (hex)
  "previousblockhash": "hash",// (string) previous block hash
  "nextblockhash": "hash"     // (string) next block hash
}
```

**Examples**

**Basic Usage**

```bash
verus getblockdeltas "00227e566682aebd6a7a5b772c96d7a999cadaebeaf1ce96f4191a3aad58b00b"
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockdeltas", "params": ["00227e566682aebd6a7a5b772c96d7a999cadaebeaf1ce96f4191a3aad58b00b"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Block explorer backends** — get per-transaction input/output details
- **Address tracking** — see which addresses were involved in a block
- **Balance auditing** — track satoshi-level flows

**Common Errors**

| Error | Cause |
|-------|-------|
| `getblockdeltas is disabled` | Daemon not started with `-experimentalfeatures -insightexplorer` |
| Block not found | Invalid block hash |

**Related Commands**

- [`getblock`](#getblock) — standard block data (no deltas)
- [`getblockheader`](#getblockheader) — header only

**Notes**

- Requires Insight Explorer experimental feature to be enabled
- Input satoshis are negative values (representing spends)
- Only shows transparent transaction data; shielded data not included in deltas

**Tested On**

- **VRSCTEST** testnet, Verus v1.2.14-2
- Help-only documentation (requires `-insightexplorer` flag)

---

## getblockhash

> **Category:** Blockchain | **Version:** v1.2.x+

Returns hash of block in best-block-chain at the given height.

**Syntax**

```
getblockhash index
```

**Parameters**

| Parameter | Type    | Required | Description     |
|-----------|---------|----------|-----------------|
| index     | numeric | Yes      | The block height |

**Result**

```
"hash"    (string) The block hash
```

**Examples**

**Basic Usage**

```bash
verus getblockhash 1000
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhash", "params": [1000]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Get block hash from height** — convert a known height to a hash for use with `getblock`
- **Chain walking** — iterate through blocks by height
- **Verification** — confirm a block at a given height matches expectations

**Common Errors**

| Error | Cause |
|-------|-------|
| Block height out of range | Height exceeds current chain tip or is negative |

**Related Commands**

- [`getblock`](#getblock) — get full block data (also accepts height directly)
- [`getblockcount`](#getblockcount) — get current chain height
- [`getbestblockhash`](#getbestblockhash) — get tip block hash

**Notes**

- Returns the hash for the block on the main (best) chain at the specified height
- Use with `getblock` or `getblockheader` for detailed block info

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getblockhashes

> **Category:** Blockchain | **Version:** v1.2.x+

Returns array of hashes of blocks within a timestamp range.

**Syntax**

```
getblockhashes high low ( options )
```

**Parameters**

| Parameter | Type    | Required | Description                     |
|-----------|---------|----------|---------------------------------|
| high      | numeric | Yes      | The newer block timestamp (unix epoch) |
| low       | numeric | Yes      | The older block timestamp (unix epoch) |
| options   | object  | No       | JSON options object             |

**Options Object**

| Field        | Type    | Description                                  |
|--------------|---------|----------------------------------------------|
| noOrphans    | boolean | Only include blocks on the main chain        |
| logicalTimes | boolean | Include logical timestamps with hashes       |

**Result**

Without `logicalTimes`:
```json
["hash", "hash", ...]
```

With `logicalTimes`:
```json
[
  {
    "blockhash": "hash",
    "logicalts": 12345
  }
]
```

**Examples**

**Basic Usage**

```bash
verus getblockhashes 1231614698 1231024505
```

**With Options**

```bash
verus getblockhashes 1231614698 1231024505 '{"noOrphans":false, "logicalTimes":true}'
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhashes", "params": [1231614698, 1231024505]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Time-based block queries** — find blocks within a specific time window
- **Historical analysis** — locate blocks around a particular event
- **Explorer backends** — support time-based block browsing

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid timestamps | `high` must be greater than `low` |
| No blocks found | No blocks exist in the given time range |

**Related Commands**

- [`getblockhash`](#getblockhash) — get hash by height (not time)
- [`getblock`](#getblock) — get full block data from hash

**Notes**

- Timestamps are Unix epoch seconds
- The `high` parameter is the more recent timestamp, `low` is the older one
- Large time ranges may return many results

**Tested On**

- **VRSCTEST** testnet, Verus v1.2.14-2
- Help-only documentation

---

## getblockheader

> **Category:** Blockchain | **Version:** v1.2.x+

Returns data about a block header by hash. Lighter weight than `getblock`.

**Syntax**

```
getblockheader "hash" ( verbose )
```

**Parameters**

| Parameter | Type    | Required | Description                                        |
|-----------|---------|----------|----------------------------------------------------|
| hash      | string  | Yes      | The block hash                                     |
| verbose   | boolean | No       | true for JSON object (default), false for hex data |

**Result (verbose = true)**

```json
{
  "hash": "hash",                    // (string) the block hash
  "confirmations": n,                // (numeric) confirmations, -1 if not on main chain
  "height": n,                       // (numeric) block height
  "version": n,                      // (numeric) block version
  "merkleroot": "xxxx",             // (string) merkle root
  "finalsaplingroot": "xxxx",       // (string) Sapling commitment tree root
  "time": ttt,                       // (numeric) block time (epoch seconds)
  "nonce": n,                        // (numeric) nonce
  "bits": "1d00ffff",               // (string) bits
  "difficulty": x.xxx,              // (numeric) difficulty
  "previousblockhash": "hash",      // (string) previous block hash
  "nextblockhash": "hash"           // (string) next block hash
}
```

**Result (verbose = false)**

```
"data"    (string) Serialized, hex-encoded header data
```

**Examples**

**Basic Usage**

```bash
verus getblockheader "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0"
```

**Testnet output (trimmed):**
```json
{
  "hash": "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0",
  "validationtype": "stake",
  "confirmations": 925997,
  "height": 1000,
  "version": 65540,
  "merkleroot": "ee99aaccd5d98bcc5ce537294bb006e8d947b583fc6e2d0b3b3998ae9e4cd7d0",
  "finalsaplingroot": "3e49b5f954aa9d3545bc6c37744661eea48d7c34e3000d82b7f0010c30f4c2fb",
  "time": 1713100429,
  "bits": "1d01681a",
  "difficulty": 179608081.3173367,
  "previousblockhash": "0000000042c11594856f338aac51f5b9199c3fb9a684506f00c53df29338b152",
  "nextblockhash": "00000000f014cd16d8b3746e277e96357910e4544281d7f5517b1d5ccf757830"
}
```

**Hex Output**

```bash
verus getblockheader "0000000107058c677dbae2fa57cfde4f2ffc7dd82d157f208bcdd4d33f800741" false
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockheader", "params": ["0000000107058c677dbae2fa57cfde4f2ffc7dd82d157f208bcdd4d33f800741"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Quick block info** — header data without full transaction list
- **Difficulty tracking** — monitor difficulty changes across blocks
- **Chain navigation** — walk the chain via `previousblockhash`/`nextblockhash`

**Common Errors**

| Error | Cause |
|-------|-------|
| Block not found | Invalid block hash |

**Related Commands**

- [`getblock`](#getblock) — full block data including transactions
- [`getblockhash`](#getblockhash) — get hash from height

**Notes**

- Much lighter than `getblock` — no transaction data included
- Unlike `getblock`, only accepts hash (not height) as input
- `finalsaplingroot` is the Sapling note commitment tree root after this block

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getchaintips

> **Category:** Blockchain | **Version:** v1.2.x+

Returns information about all known tips in the block tree, including the main chain and orphaned branches.

**Syntax**

```
getchaintips
```

**Parameters**

None.

**Result**

```json
[
  {
    "height": 926992,          // (numeric) height of the chain tip
    "hash": "xxxx",            // (string) block hash of the tip
    "branchlen": 0,            // (numeric) 0 for main chain
    "status": "active"         // (string) tip status
  },
  {
    "height": 926900,
    "hash": "xxxx",
    "branchlen": 1,            // (numeric) branch length to main chain
    "status": "valid-fork"     // (string) tip status
  }
]
```

**Status Values**

| Status | Description |
|--------|-------------|
| `active` | Tip of the active main chain |
| `valid-fork` | Fully validated branch, not active |
| `valid-headers` | All blocks available, never fully validated |
| `headers-only` | Not all blocks available, headers valid |
| `invalid` | Branch contains at least one invalid block |

**Examples**

**Basic Usage**

```bash
verus getchaintips
```

**Testnet output (trimmed):**
```json
[
  {
    "height": 926996,
    "hash": "00000003a59f522a082e4c34f921c2e5ef44ebe8db410b1d6484787e271df2a2",
    "branchlen": 0,
    "status": "active"
  },
  {
    "height": 926989,
    "hash": "6bd5bca95c134bbd8c021f5eb07c08dcb9ec21cf0f15ca675c4edfdaa371ff31",
    "branchlen": 1,
    "status": "valid-fork"
  },
  {
    "height": 926962,
    "hash": "000000027c1dc37b3f085c564ae1e58e7e72840cda64171b17abecec40020d6e",
    "branchlen": 1,
    "status": "headers-only"
  }
]
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getchaintips", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Fork detection** — identify competing chain branches
- **Network health** — monitor for invalid forks or stale tips
- **Debugging** — understand chain reorganizations

**Common Errors**

None typical.

**Related Commands**

- [`getblockchaininfo`](#getblockchaininfo) — general chain state
- [`getbestblockhash`](#getbestblockhash) — tip of active chain only

**Notes**

- The active tip always has `branchlen: 0` and `status: "active"`
- Multiple tips indicate forks have been seen by the node
- `valid-fork` branches were fully validated but have less work than the active chain

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getchaintxstats

> **Category:** Blockchain | **Version:** v1.2.x+

Computes statistics about the total number and rate of transactions in the chain.

**Syntax**

```
getchaintxstats ( nblocks blockhash )
```

**Parameters**

| Parameter | Type    | Required | Description                                  |
|-----------|---------|----------|----------------------------------------------|
| nblocks   | numeric | No       | Number of blocks in averaging window         |
| blockhash | string  | No       | Hash of the block which ends the window      |

**Result**

```json
{
  "time": 1770449655,                        // (numeric) timestamp of final block (epoch)
  "txcount": 1234567,                        // (numeric) total transactions in chain
  "window_final_block_hash": "...",          // (string) hash of final block in window
  "window_block_count": 2016,                // (numeric) window size in blocks
  "window_tx_count": 5000,                   // (numeric) transactions in window
  "window_interval": 120000,                 // (numeric) elapsed time in window (seconds)
  "txrate": 0.042                            // (numeric) average tx/second in window
}
```

**Examples**

**Basic Usage**

```bash
verus getchaintxstats
```

**Testnet output:**
```json
{
  "time": 1770450217,
  "txcount": 2275130,
  "window_final_block_hash": "00000003a59f522a082e4c34f921c2e5ef44ebe8db410b1d6484787e271df2a2",
  "window_block_count": 43200,
  "window_tx_count": 99691,
  "window_interval": 2674964,
  "txrate": 0.03726816510427804
}
```

```bash
verus getchaintxstats 2016
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getchaintxstats", "params": [2016]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Network activity monitoring** — track transaction throughput over time
- **Performance analysis** — measure tx rate across different windows
- **Dashboard metrics** — feed into monitoring/alerting systems

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid block hash | Specified blockhash not found |
| Block count out of range | nblocks larger than chain height |

**Related Commands**

- [`getblockchaininfo`](#getblockchaininfo) — general chain state
- [`getmempoolinfo`](#getmempoolinfo) — pending transaction stats

**Notes**

- `window_tx_count`, `window_interval`, and `txrate` only returned when `window_block_count > 0`
- Default window size depends on implementation; specify `nblocks` for consistent results

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getdifficulty

> **Category:** Blockchain | **Version:** v1.2.x+

Returns the proof-of-work difficulty as a multiple of the minimum difficulty.

**Syntax**

```
getdifficulty
```

**Parameters**

None.

**Result**

```
n.nnn    (numeric) the proof-of-work difficulty
```

**Examples**

**Basic Usage**

```bash
verus getdifficulty
```

**Testnet output:**
```
53500896.94362766
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getdifficulty", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Mining monitoring** — track difficulty changes
- **Hash rate estimation** — derive approximate network hash rate
- **Dashboard metrics** — display current mining difficulty

**Common Errors**

None typical.

**Related Commands**

- [`getblockchaininfo`](#getblockchaininfo) — includes difficulty plus more
- [`getblock`](#getblock) — per-block difficulty

**Notes**

- Value is relative to the minimum difficulty (difficulty 1)
- Changes based on Verus's difficulty adjustment algorithm
- Verus uses VerusHash 2.2 for proof-of-work

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getmempoolinfo

> **Category:** Blockchain | **Version:** v1.2.x+

Returns details on the active state of the TX memory pool.

**Syntax**

```
getmempoolinfo
```

**Parameters**

None.

**Result**

```json
{
  "size": 5,          // (numeric) Current tx count
  "bytes": 1234,      // (numeric) Sum of all tx sizes
  "usage": 5678       // (numeric) Total memory usage for the mempool
}
```

**Examples**

**Basic Usage**

```bash
verus getmempoolinfo
```

**Testnet output:**
```json
{
  "size": 0,
  "bytes": 0,
  "usage": 0
}
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmempoolinfo", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Mempool monitoring** — check if transactions are pending
- **Network congestion** — assess mempool size/usage
- **Node health** — verify mempool is functioning normally

**Common Errors**

None typical.

**Related Commands**

- [`getrawmempool`](#getrawmempool) — list actual transactions in mempool
- [`clearrawmempool`](multichain.md#clearrawmempool) — clear the mempool

**Notes**

- `size` is the number of transactions, not bytes
- `bytes` is the total serialized size of all transactions
- `usage` reflects actual memory consumed (may differ from `bytes` due to overhead)

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getrawmempool

> **Category:** Blockchain | **Version:** v1.2.x+

Returns all transaction ids in the memory pool as a JSON array, with optional verbose details.

**Syntax**

```
getrawmempool ( verbose ) '{"include":[],"exclude":[]}'
```

**Parameters**

| Parameter  | Type    | Required | Description                                           |
|------------|---------|----------|-------------------------------------------------------|
| verbose    | boolean | No       | true for detailed JSON, false for txid array (default) |
| qualifiers | object  | No       | Filter by transaction type: `{"include":["type",...],"exclude":["type",...]}` |

**Result (verbose = false)**

```json
["txid1", "txid2", ...]
```

**Result (verbose = true)**

```json
{
  "txid": {
    "size": 250,                // (numeric) transaction size in bytes
    "fee": 0.0001,              // (numeric) transaction fee in VRSC
    "time": 1770449655,         // (numeric) time entered pool (epoch)
    "height": 926990,           // (numeric) block height when entered pool
    "startingpriority": 1000,   // (numeric) priority when entered pool
    "currentpriority": 1000,    // (numeric) current priority
    "depends": ["txid", ...]    // (array) unconfirmed parent txids
  }
}
```

**Examples**

**Basic Usage**

```bash
verus getrawmempool
verus getrawmempool true
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getrawmempool", "params": [true]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Monitor pending transactions** — see what's waiting to be mined
- **Fee analysis** — check fees of pending transactions
- **Dependency tracking** — identify chains of unconfirmed transactions

**Common Errors**

None typical.

**Related Commands**

- [`getmempoolinfo`](#getmempoolinfo) — summary stats about mempool
- [`clearrawmempool`](multichain.md#clearrawmempool) — clear the mempool

**Notes**

- The `qualifiers` parameter allows filtering by transaction type with `include`/`exclude` arrays
- `depends` shows unconfirmed transactions that this tx relies on
- Empty array `[]` when mempool has no pending transactions

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## getspentinfo

> **Category:** Blockchain | **Version:** v1.2.x+

Returns the txid and index where a specific transaction output was spent.

**Syntax**

```
getspentinfo {"txid":"hex","index":n}
```

**Parameters**

| Parameter | Type   | Required | Description                    |
|-----------|--------|----------|--------------------------------|
| txid      | string | Yes      | The transaction id (hex)       |
| index     | number | Yes      | The output index (vout number) |

Passed as a single JSON object argument.

**Result**

```json
{
  "txid": "hash",    // (string) The spending transaction id
  "index": n         // (number) The spending input index
}
```

**Examples**

**Basic Usage**

```bash
verus getspentinfo '{"txid": "0437cd7f8525ceed2324359c2d0ba26006d92d856a9c20fa0241106ee5a597c9", "index": 0}'
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getspentinfo", "params": [{"txid": "0437cd7f8525ceed2324359c2d0ba26006d92d856a9c20fa0241106ee5a597c9", "index": 0}]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **UTXO tracking** — determine if and where an output was spent
- **Transaction tracing** — follow the flow of funds
- **Wallet debugging** — verify spend status of specific outputs

**Common Errors**

| Error | Cause |
|-------|-------|
| Unable to get spent info | Output is unspent or txid not found |

**Related Commands**

- [`gettxout`](#gettxout) — get details of an unspent output
- [`gettxoutproof`](#gettxoutproof) — prove a tx was included in a block

**Notes**

- Only works for spent outputs; use `gettxout` for unspent outputs
- May require `-txindex` or `-spentindex` for full coverage
- The input is a JSON object, not separate parameters

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Help-only documentation

---

## gettxout

> **Category:** Blockchain | **Version:** v1.2.x+

Returns details about an unspent transaction output (UTXO).

**Syntax**

```
gettxout "txid" n ( includemempool )
```

**Parameters**

| Parameter      | Type    | Required | Description                          |
|----------------|---------|----------|--------------------------------------|
| txid           | string  | Yes      | The transaction id                   |
| n              | numeric | Yes      | The vout index                       |
| includemempool | boolean | No       | Whether to include the mempool       |

**Result**

```json
{
  "bestblock": "hash",        // (string) the block hash
  "confirmations": n,          // (numeric) number of confirmations
  "value": 10.0,               // (numeric) transaction value in VRSC
  "scriptPubKey": {
    "asm": "code",             // (string) script assembly
    "hex": "hex",              // (string) script hex
    "reqSigs": 1,              // (numeric) required signatures
    "type": "pubkeyhash",      // (string) script type
    "addresses": [             // (array) Verus addresses
      "RAddress..."
    ]
  },
  "version": n,                // (numeric) tx version
  "coinbase": false            // (boolean) whether this is a coinbase output
}
```

Returns `null` if the output is already spent.

**Examples**

**Basic Usage**

```bash
verus gettxout "txid" 1
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "gettxout", "params": ["txid", 1]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **UTXO verification** — check if a specific output is still unspent
- **Balance checking** — verify output value and ownership
- **Coinbase detection** — check if output is from mining/staking reward

**Common Errors**

| Error | Cause |
|-------|-------|
| Returns `null` | Output is already spent or txid not found |

**Related Commands**

- [`getspentinfo`](#getspentinfo) — find where an output was spent
- [`gettxoutsetinfo`](#gettxoutsetinfo) — aggregate UTXO set statistics
- [`gettxoutproof`](#gettxoutproof) — prove inclusion in a block

**Notes**

- Returns `null` (not an error) if the output has been spent
- `includemempool` defaults to checking the UTXO set only; set `true` to also check mempool
- Useful for wallet implementations to verify UTXO availability

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## gettxoutproof

> **Category:** Blockchain | **Version:** v1.2.x+

Returns a hex-encoded proof that a transaction was included in a block.

**Syntax**

```
gettxoutproof ["txid",...] ( blockhash )
```

**Parameters**

| Parameter | Type   | Required | Description                                    |
|-----------|--------|----------|------------------------------------------------|
| txids     | array  | Yes      | JSON array of txids to create proof for        |
| blockhash | string | No       | If specified, looks for txid in this block     |

**Result**

```
"data"    (string) Serialized, hex-encoded Merkle proof data
```

**Examples**

**Basic Usage**

```bash
verus gettxoutproof '["txid1"]'
verus gettxoutproof '["txid1"]' "blockhash"
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "gettxoutproof", "params": [["txid1"]]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **SPV verification** — prove transaction inclusion without full block data
- **Cross-chain proofs** — provide evidence of a transaction to another system
- **Audit trails** — cryptographic proof that a tx exists in a specific block

**Common Errors**

| Error | Cause |
|-------|-------|
| Transaction not yet in block | Tx is in mempool but not confirmed |
| Not all transactions found | Tx not in UTXO set and no blockhash specified |

**Related Commands**

- [`verifytxoutproof`](#verifytxoutproof) — verify a proof created by this command
- [`gettxout`](#gettxout) — check if output is unspent

**Notes**

- By default only works when the transaction has an unspent output in the UTXO set
- For spent transactions, you must either use `-txindex` or specify the `blockhash` manually
- The proof is a Merkle branch proving inclusion in the block's Merkle tree
- Verify proofs with `verifytxoutproof`

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Help-only documentation

---

## gettxoutsetinfo

> **Category:** Blockchain | **Version:** v1.2.x+

Returns statistics about the unspent transaction output (UTXO) set.

**Syntax**

```
gettxoutsetinfo
```

**Parameters**

None.

**Result**

```json
{
  "height": 926992,                    // (numeric) current block height
  "bestblock": "hex",                  // (string) best block hash
  "transactions": 500000,             // (numeric) number of transactions with UTXOs
  "txouts": 750000,                   // (numeric) number of unspent outputs
  "bytes_serialized": 12345678,       // (numeric) serialized size
  "hash_serialized": "hash",          // (string) serialized hash
  "total_amount": 55000000.00         // (numeric) total amount in UTXO set
}
```

**Examples**

**Basic Usage**

```bash
verus gettxoutsetinfo
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "gettxoutsetinfo", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **UTXO set audit** — get aggregate statistics about all unspent outputs
- **Supply verification** — `total_amount` shows total coins in transparent UTXOs
- **Database health** — check UTXO database size and consistency

**Common Errors**

None typical, but note this call may take significant time on large chains.

**Related Commands**

- [`gettxout`](#gettxout) — get a specific UTXO
- [`coinsupply`](#coinsupply) — coin supply including shielded funds

**Notes**

- ⚠️ **This call may take some time** — it scans the entire UTXO set
- `total_amount` only includes transparent outputs (not shielded)
- Use `coinsupply` for a complete picture including shielded funds

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Help-only documentation (can be slow on large chains)

---

## minerids

> **Category:** Blockchain | **Version:** v1.2.x+

Returns miner IDs for a given block height.

**Syntax**

```
minerids height
```

**Parameters**

| Parameter | Type    | Required | Description     |
|-----------|---------|----------|-----------------|
| height    | numeric | Yes      | The block height |

**Result**

Returns information about miners/stakers at the specified height.

**Examples**

**Basic Usage**

```bash
verus minerids 926996
```

**Testnet output (trimmed):**
```json
{
  "mined": [
    {
      "notaryid": 0,
      "KMDaddress": "RJdoxr1CeY2wXobq59VJbMrBMcsm7ZxuB1",
      "pubkey": "0237e0d3268cebfa235958808db1efc20cc43b31100813b1f3e15cc5aa647ad2c3",
      "blocks": 0
    },
    ...
    {
      "pubkey": "external miners",
      "blocks": 2000
    }
  ],
  "numnotaries": 64
}
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "minerids", "params": [926992]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Mining analysis** — identify who mined a specific block
- **Network decentralization** — track miner distribution
- **Staking verification** — check staker identity at a height

**Common Errors**

| Error | Cause |
|-------|-------|
| `minerids needs height` | Height parameter not provided |
| Block height out of range | Height exceeds chain tip |

**Related Commands**

- [`notaries`](#notaries) — notary information at a height
- [`getblock`](#getblock) — full block data

**Notes**

- Height parameter is required (not optional)
- Related to Komodo/Verus notarization infrastructure

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Live tested with height 926996

---

## notaries

> **Category:** Blockchain | **Version:** v1.2.x+

Returns notary information for a given block height and timestamp.

**Syntax**

```
notaries height timestamp
```

**Parameters**

| Parameter | Type    | Required | Description              |
|-----------|---------|----------|--------------------------|
| height    | numeric | Yes      | The block height         |
| timestamp | numeric | Yes      | The block timestamp (epoch) |

**Result**

Returns information about notaries active at the specified height and timestamp.

**Examples**

**Basic Usage**

```bash
verus notaries 926996 1770450217
```

**Testnet output (trimmed):**
```json
{
  "notaries": [
    {
      "pubkey": "0237e0d3268cebfa235958808db1efc20cc43b31100813b1f3e15cc5aa647ad2c3",
      "BTCaddress": "1AMctL7v3iENToEdbyWBVqWybMRASwSH4C",
      "KMDaddress": "RJdoxr1CeY2wXobq59VJbMrBMcsm7ZxuB1"
    },
    ... // 64 notary entries total
  ],
  "numnotaries": 64,
  "height": 926996,
  "timestamp": 1770450217
}
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "notaries", "params": [926992, 1770449655]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Notarization tracking** — identify active notary nodes
- **Network governance** — monitor notary participation
- **Cross-chain verification** — check notarization status

**Common Errors**

| Error | Cause |
|-------|-------|
| Missing parameters | Both height and timestamp are required |

**Related Commands**

- [`minerids`](#minerids) — miner identity at a height
- [`getblock`](#getblock) — block data including timestamp

**Notes**

- Both parameters (height and timestamp) are required
- Related to the Komodo notarization system inherited by Verus
- Notaries are responsible for cross-chain security via notarization transactions

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Live tested with height 926996

---

## processupgradedata

> **Category:** Blockchain | **Version:** v1.2.x+

Processes upgrade data for network upgrades. Used internally for managing protocol upgrades.

**Syntax**

```
processupgradedata {upgradedata}
```

**Parameters**

| Parameter              | Type   | Required | Description                                  |
|------------------------|--------|----------|----------------------------------------------|
| upgradeid              | string | Yes      | The VDXF key identifier                     |
| minimumdaemonversion   | string | Yes      | Minimum daemon version required for upgrade   |
| activationheight       | number | Yes      | Block height to activate the upgrade          |
| activationtime         | number | Yes      | Epoch time to activate (upgrade-dependent)    |

Passed as a single JSON object.

**Result**

```json
{
  "txid": "hash",    // (string) The transaction id
  "index": n         // (number) The spending input index
}
```

**Examples**

**Basic Usage**

```bash
verus processupgradedata '{"upgradeid": "vdxf-key", "minimumdaemonversion": "1.2.0", "activationheight": 100000, "activationtime": 1700000000}'
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "processupgradedata", "params": [{"upgradeid": "vdxf-key", "minimumdaemonversion": "1.2.0", "activationheight": 100000, "activationtime": 1700000000}]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Network upgrades** — process and validate upgrade definitions
- **Protocol management** — handle consensus rule changes

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid upgrade data | Malformed JSON or missing required fields |

**Related Commands**

- [`getblockchaininfo`](#getblockchaininfo) — shows active upgrades and consensus info

**Notes**

- ⚠️ **Advanced/internal command** — used for protocol upgrade management
- Uses VDXF (Verus Data eXchange Format) key identifiers
- Do not use in production without understanding the upgrade process
- The `activationtime` behavior depends on the specific upgrade type

**Tested On**

- **VRSCTEST** testnet, Verus v1.2.14-2
- **Help-only documentation** — not safe to test without valid upgrade data

---

## verifychain

> **Category:** Blockchain | **Version:** v1.2.x+

Verifies the blockchain database integrity.

**Syntax**

```
verifychain ( checklevel numblocks )
```

**Parameters**

| Parameter  | Type    | Required | Description                                    |
|------------|---------|----------|------------------------------------------------|
| checklevel | numeric | No       | Verification thoroughness, 0-4 (default: 3)   |
| numblocks  | numeric | No       | Number of blocks to check (default: 288, 0=all) |

**Result**

```
true|false    (boolean) Whether verification passed
```

**Examples**

**Basic Usage**

```bash
verus verifychain
```

**Testnet output:**
```
true
```

```bash
verus verifychain 4 100
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "verifychain", "params": []}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Database integrity** — verify blockchain data hasn't been corrupted
- **Post-crash recovery** — check chain validity after unexpected shutdown
- **Routine maintenance** — periodic health checks

**Common Errors**

| Error | Cause |
|-------|-------|
| Returns `false` | Chain verification failed — data corruption detected |

**Related Commands**

- [`getblockchaininfo`](#getblockchaininfo) — general chain state
- [`gettxoutsetinfo`](#gettxoutsetinfo) — UTXO set statistics

**Notes**

- Higher `checklevel` values are more thorough but slower
- Default checks the last 288 blocks (~1 day at 1 min blocks)
- Set `numblocks` to 0 to verify the entire chain (very slow)
- Level 0: Read blocks from disk
- Level 1: Verify block validity
- Level 2: Verify undo data
- Level 3: Check disconnection of tip blocks (default)
- Level 4: Try reconnecting blocks

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2

---

## verifytxoutproof

> **Category:** Blockchain | **Version:** v1.2.x+

Verifies that a proof points to a transaction in a block, returning the transaction it commits to.

**Syntax**

```
verifytxoutproof "proof"
```

**Parameters**

| Parameter | Type   | Required | Description                                        |
|-----------|--------|----------|----------------------------------------------------|
| proof     | string | Yes      | The hex-encoded proof generated by `gettxoutproof` |

**Result**

```json
["txid"]    // (array of strings) The txid(s) the proof commits to, or empty array if invalid
```

**Examples**

**Basic Usage**

```bash
verus verifytxoutproof "hexproofdata..."
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "verifytxoutproof", "params": ["hexproofdata..."]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **SPV verification** — verify Merkle proofs from `gettxoutproof`
- **Cross-chain validation** — confirm transaction inclusion on another system
- **Audit verification** — validate proof artifacts

**Common Errors**

| Error | Cause |
|-------|-------|
| Empty array returned | Proof is invalid |
| RPC error | Block referenced by proof is not in the best chain |

**Related Commands**

- [`gettxoutproof`](#gettxoutproof) — generate the proof this command verifies

**Notes**

- Throws an RPC error if the block referenced is not in the node's best chain
- Returns an empty array (not an error) for invalid proofs
- The proof is a Merkle branch encoded in hex

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Help-only documentation

---

## z_gettreestate

> **Category:** Blockchain | **Version:** v1.2.x+

Returns information about the given block's Sprout and Sapling commitment tree state.

**Syntax**

```
z_gettreestate "hash|height"
```

**Parameters**

| Parameter   | Type   | Required | Description                                                      |
|-------------|--------|----------|------------------------------------------------------------------|
| hash\|height | string | Yes      | Block hash or height. Height can be negative (-1 = last valid block) |

**Result**

```json
{
  "hash": "hash",             // (string) hex block hash
  "height": 1000,             // (numeric) block height
  "sprout": {
    "skipHash": "hash",       // (string) hash of most recent block with more info
    "commitments": {
      "finalRoot": "hex",     // (string) Sprout commitment tree root
      "finalState": "hex"     // (string) Sprout commitment tree state
    }
  },
  "sapling": {
    "skipHash": "hash",       // (string) hash of most recent block with more info
    "commitments": {
      "finalRoot": "hex",     // (string) Sapling commitment tree root
      "finalState": "hex"     // (string) Sapling commitment tree state
    }
  }
}
```

**Examples**

**Basic Usage**

```bash
verus z_gettreestate 1000
```

**Testnet output:**
```json
{
  "hash": "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0",
  "height": 1000,
  "time": 1713100429,
  "sprout": {
    "commitments": {
      "finalRoot": "59d2cde5e65c1414c32ba54f0fe4bdb3d67618125286e6a191317917c812c6d7",
      "finalState": "000000"
    }
  },
  "sapling": {
    "commitments": {
      "finalRoot": "3e49b5f954aa9d3545bc6c37744661eea48d7c34e3000d82b7f0010c30f4c2fb",
      "finalState": "000000"
    }
  }
}
```

```bash
## By hash
verus z_gettreestate "a35c8b82c49e55117328385515dc68b5468306ba11997bea89b7069e267b7ab0"

## Latest block
verus z_gettreestate -1
```

**RPC (curl)**

```bash
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "z_gettreestate", "params": ["12800"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**

- **Shielded transaction verification** — check commitment tree roots
- **Wallet sync** — obtain tree state for scanning shielded notes
- **Chain state debugging** — verify Sprout/Sapling commitment trees

**Common Errors**

| Error | Cause |
|-------|-------|
| Block not found | Invalid hash or height beyond chain tip |

**Related Commands**

- [`getblock`](#getblock) — includes `finalsaplingroot` in output
- [`getblockheader`](#getblockheader) — also includes `finalsaplingroot`

**Notes**

- Supports negative heights: `-1` is the last known valid block
- The `skipHash` field points to the most recent block with commitment tree changes
- Both Sprout and Sapling tree states are included
- Essential for light wallet implementations and shielded transaction scanning

**Tested On**

- **VRSCTEST** testnet, block 926992, Verus v1.2.14-2
- Live tested with height 1000

--- PAGE: command-reference/control.md ---

---
label: Control
icon: terminal
---


# Control Commands


---

## getinfo

> **Category:** Control | **Version:** v1.2.14+

Returns an object containing various state info about the node and wallet.

**Syntax**

```
getinfo
```

**Parameters**

None.

**Result**

| Field           | Type    | Description |
|-----------------|---------|-------------|
| VRSCversion     | string  | The Verus-specific version string |
| version         | numeric | The server version number |
| protocolversion | numeric | The protocol version |
| chainid         | string  | Blockchain currency i-address |
| notarychainid   | string  | Notary chain i-address |
| name            | string  | Chain name (e.g., VRSCTEST) |
| walletversion   | numeric | The wallet version |
| blocks          | numeric | Current number of blocks processed |
| longestchain    | numeric | Longest known chain height |
| timeoffset      | numeric | Time offset |
| proxy           | string  | Proxy used (empty if none) |
| connections     | numeric | Number of connections |
| tls_established | numeric | Number of TLS connections established |
| tls_verified    | numeric | Number of TLS connections with validated certificates |
| difficulty      | numeric | Current mining difficulty |
| testnet         | boolean | Whether the server is on testnet |
| keypoololdest   | numeric | Timestamp of oldest pre-generated key |
| keypoolsize     | numeric | Number of pre-generated keys |
| paytxfee        | numeric | Transaction fee in VRSC/kB |
| relayfee        | numeric | Minimum relay fee in VRSC/kB |
| unlocked_until  | numeric | Wallet unlock expiry timestamp (0 = locked, absent if unencrypted) |
| errors          | string  | Any error messages |
| tiptime         | numeric | Timestamp of current chain tip |
| nextblocktime   | numeric | Expected timestamp for next block |
| CCid            | numeric | Currency/chain ID number (1 for VRSC) |
| p2pport         | numeric | Peer-to-peer network port |
| rpcport         | numeric | RPC server port |
| magic           | numeric | Network magic number |
| premine         | numeric | Premine amount (0 for VRSC) |
| eras            | numeric | Number of emission eras |
| reward          | string  | Comma-separated reward per era (satoshis) |
| halving         | string  | Comma-separated halving interval per era (blocks) |
| decay           | string  | Comma-separated decay rate per era |
| endsubsidy      | string  | Comma-separated era end blocks |
| veruspos        | numeric | Percentage of blocks that are proof-of-stake |

**Examples**

```bash
verus -testnet getinfo
```

**Testnet output:**
```json
{
  "VRSCversion": "1.2.14-2",
  "version": 2000753,
  "protocolversion": 170010,
  "chainid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "notarychainid": "iCtawpxUiCc2sEupt7Z4u8SDAncGZpgSKm",
  "name": "VRSCTEST",
  "walletversion": 60000,
  "blocks": 926996,
  "longestchain": 926996,
  "timeoffset": 0,
  "connections": 5,
  "tls_established": 5,
  "tls_verified": 0,
  "difficulty": 49081785917.1893,
  "testnet": true,
  "keypoololdest": 1770405903,
  "keypoolsize": 101,
  "paytxfee": 0.00000000,
  "relayfee": 0.00000100,
  "errors": ""
}
```

**Common Errors**

None typical.

**Related Commands**

- [`getnetworkinfo`](network.md#getnetworkinfo) — Detailed network info
- [`getdeprecationinfo`](network.md#getdeprecationinfo) — Version/deprecation info
- [`help`](#help) — List available commands

**Notes**

- This is one of the most useful commands for a quick status check.
- `blocks` vs `longestchain` — if they differ, the node is still syncing.
- `chainid` and `name` identify the chain (VRSCTEST for testnet).
- Includes PBaaS-specific fields like `notarizedroot` with cross-chain state info.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## help

> **Category:** Control | **Version:** v1.2.14+

List all commands, or get help for a specified command.

**Syntax**

```
help ("command")
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| command   | string | No       | The command to get help on |

**Result**

| Type   | Description |
|--------|-------------|
| string | The help text |

**Examples**

```bash
## List all available commands
verus -testnet help

## Get help for a specific command
verus -testnet help getinfo
```

**Common Errors**

None typical. Unknown commands return an error message.

**Related Commands**

- [`getinfo`](#getinfo) — General node info
- [`stop`](#stop) — Stop the server

**Notes**

- Without arguments, lists all available RPC commands grouped by category.
- With a command name, returns detailed usage information including syntax, parameters, and examples.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## stop

> **Category:** Control | **Version:** v1.2.14+

Stop the Verus daemon server.

**Syntax**

```
stop
```

**Parameters**

None.

**Result**

The server begins shutting down. Returns a confirmation message.

**Examples**

```bash
verus -testnet stop
```

**Common Errors**

None typical.

**Related Commands**

- [`getinfo`](#getinfo) — Check server status before stopping
- [`help`](#help) — List available commands

**Notes**

- ⚠️ **This will shut down the daemon**. The node will stop processing blocks and all RPC calls will fail.
- Ensure all pending operations are complete before stopping.
- The daemon performs a graceful shutdown, saving state to disk.
- Restart with `verusd` or the appropriate startup command.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only; **not executed**)

--- PAGE: command-reference/disclosure.md ---

---
label: Disclosure
icon: terminal
---


# Disclosure Commands


---

## z_getpaymentdisclosure

> **Category:** Disclosure | **Version:** v1.2.14+

> ⚠️ **EXPERIMENTAL** — Disabled by default. Requires `-experimentalfeatures` and `-paymentdisclosure` flags.

Generate a payment disclosure for a given joinsplit output.

**Syntax**

```
z_getpaymentdisclosure "txid" "js_index" "output_index" ("message")
```

**Parameters**

| Parameter    | Type   | Required | Description |
|--------------|--------|----------|-------------|
| txid         | string | Yes      | The transaction id |
| js_index     | string | Yes      | The joinsplit index |
| output_index | string | Yes      | The output index within the joinsplit |
| message      | string | No       | Optional message (e.g., "refund") |

**Result**

| Type   | Description |
|--------|-------------|
| string | Payment disclosure hex data with "zpd:" prefix |

**Examples**

```bash
verus -testnet z_getpaymentdisclosure "96f12882450429324d5f3b48630e3168220e49ab7b0f066e5c2935a6b88bb0f2" 0 0 "refund"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `z_getpaymentdisclosure is disabled` | Feature not enabled at startup |

**Related Commands**

- [`z_validatepaymentdisclosure`](#z_validatepaymentdisclosure) — Validate a payment disclosure

**Notes**

- **Disabled by default**. To enable, add to `VRSC.conf` or use startup flags:
  ```
  experimentalfeatures=1
  paymentdisclosure=1
  ```
- Only works with joinsplit (sprout) transactions, not sapling.
- Payment disclosures allow proving that a shielded payment was made without revealing other transaction details.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only; feature disabled)

---

## z_validatepaymentdisclosure

> **Category:** Disclosure | **Version:** v1.2.14+

> ⚠️ **EXPERIMENTAL** — Disabled by default. Requires `-experimentalfeatures` and `-paymentdisclosure` flags.

Validates a payment disclosure.

**Syntax**

```
z_validatepaymentdisclosure "paymentdisclosure"
```

**Parameters**

| Parameter         | Type   | Required | Description |
|-------------------|--------|----------|-------------|
| paymentdisclosure | string | Yes      | Hex data string with "zpd:" prefix |

**Result**

Validation result object.

**Examples**

```bash
verus -testnet z_validatepaymentdisclosure "zpd:706462ff004c561a0447ba2ec51184e6c204..."
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `z_validatepaymentdisclosure is disabled` | Feature not enabled at startup |

**Related Commands**

- [`z_getpaymentdisclosure`](#z_getpaymentdisclosure) — Generate a payment disclosure

**Notes**

- **Disabled by default**. To enable, add to `VRSC.conf` or use startup flags:
  ```
  experimentalfeatures=1
  paymentdisclosure=1
  ```
- Verifies that a payment disclosure is valid and the claimed payment was actually made.
- The disclosure string must have the `zpd:` prefix.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only; feature disabled)

--- PAGE: command-reference/generating.md ---

---
label: Generating
icon: terminal
---


# Generating Commands


---

## generate

> **Category:** Generating | **Version:** v1.2.14+

Mine blocks immediately (before the RPC call returns). **Only available on regtest network.**

**Syntax**
```bash
verus generate numblocks
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| numblocks | numeric | Yes | How many blocks to generate immediately |

**Result**
```json
["blockhash1", "blockhash2", ...]    // (array of strings) Hashes of generated blocks
```

**Examples**

**Basic Usage**
```bash
./verus -testnet generate 1

## Actual Output (tested on VRSCTEST)
error code: -32601
error message:
This method can only be used on regtest
```

**Regtest Usage**
```bash
## On regtest network only
./verus -regtest generate 11
```

**RPC (curl)**
```bash
curl --user user:pass \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"generate","params":[11]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Development and testing on regtest
- Generating blocks on demand for automated tests
- Confirming transactions in test environments

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `This method can only be used on regtest` | Called on testnet or mainnet | Use regtest network, or use `setgenerate` for testnet/mainnet mining |

**Related Commands**
- [`setgenerate`](#setgenerate) — enable continuous mining/staking (works on all networks)
- [`getgenerate`](#getgenerate) — check generation status

**Notes**
- This is a synchronous call — it blocks until all requested blocks are mined
- For testnet/mainnet mining, use `setgenerate` instead
- Useful for automated testing where you need deterministic block production

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getgenerate

> **Category:** Generating | **Version:** v1.2.14+

Returns whether the server is set to mine and/or stake coins. Can be configured via command line (`-gen`, `-mint`), config file, or `setgenerate`.

**Syntax**
```bash
verus getgenerate
```

**Parameters**
None.

**Result**
```json
{
  "staking": true|false,     // (boolean) If staking is on or off
  "generate": true|false,    // (boolean) If mining is on or off
  "numthreads": n            // (numeric) Processor limit for mining
}
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getgenerate

## Actual Output (tested on VRSCTEST) — default state
{
  "staking": false,
  "generate": false,
  "numthreads": 0
}
```

**After Enabling Staking**
```bash
## First enable staking
./verus -testnet setgenerate true 0

## Then check
./verus -testnet getgenerate

## Actual Output (tested on VRSCTEST)
{
  "staking": true,
  "generate": true,
  "numthreads": 0
}
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getgenerate","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Verify mining/staking is active after configuration
- Monitor node generation state in scripts
- Confirm `setgenerate` took effect

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| None typical | — | — |

**Related Commands**
- [`setgenerate`](#setgenerate) — enable/disable mining and staking
- [`getmininginfo`](mining.md#getmininginfo) — comprehensive mining status

**Notes**
- `generate: true` with `numthreads: 0` means staking only (no CPU mining)
- `generate: true` with `numthreads: N` (N > 0) means CPU mining with N threads
- The default state is false/false/0 unless configured via CLI args or config file

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## setgenerate

> **Category:** Generating | **Version:** v1.2.14+

Enable or disable mining (generation) and staking. Mining is limited to a specified number of processor threads.

**Syntax**
```bash
verus setgenerate generate [genproclimit]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| generate | boolean | Yes | `true` to turn on generation, `false` to turn off both mining and staking |
| genproclimit | numeric | No | Processor limit. `-1` = unlimited, `0` = staking only, `N` = N threads for mining |

**Result**
No return value on success.

**Examples**

**Enable Staking Only**
```bash
./verus -testnet setgenerate true 0

## Verify
./verus -testnet getgenerate

## Actual Output (tested on VRSCTEST)
{
  "staking": true,
  "generate": true,
  "numthreads": 0
}
```

**Enable Mining with 1 Thread**
```bash
./verus -testnet setgenerate true 1
```

**Disable All Generation**
```bash
./verus -testnet setgenerate false

## Verify
./verus -testnet getgenerate

## Actual Output (tested on VRSCTEST)
{
  "staking": false,
  "generate": false,
  "numthreads": 0
}
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setgenerate","params":[true,1]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Start staking with `setgenerate true 0`
- Start CPU mining with `setgenerate true 1` (or more threads)
- Stop all mining/staking with `setgenerate false`
- Adjust thread count without restarting the node

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| None typical | — | — |

**Related Commands**
- [`getgenerate`](#getgenerate) — check current generation status
- [`getmininginfo`](mining.md#getmininginfo) — comprehensive mining status
- [`getlocalsolps`](mining.md#getlocalsolps) — monitor local hashrate after enabling

**Notes**
- `setgenerate true` without `genproclimit` defaults to staking mode (0 threads)
- Staking requires a wallet with mature coins (100+ confirmations)
- `setgenerate false` stops **both** mining and staking
- Changes take effect immediately — no restart required
- On Verus, staking uses the VerusHash algorithm and doesn't consume significant CPU

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

--- PAGE: command-reference/identity.md ---

---
label: Identity
icon: terminal
---

# Identity Commands

> **Placeholder convention:** Examples in this reference use `myid@` as your own identity, `recovery@` / `revocation@` as authority-role identities, `yourapp@` as an application namespace, `i...` to mark a placeholder i-address (substitute your own from `getidentity`), `<R-address>` / `<your-R-address>` for transparent R-addresses, and `<block-height>` for a placeholder block number. Commands shown were tested on VRSCTEST — only these project-specific values have been genericized.

---

## getidentitieswithaddress

> **Category:** Identity | **Version:** v1.2.x+

Returns all identities that contain a specified address in their primary addresses. Requires the daemon to be started with `-idindex=1`.

**Syntax**
```bash
verus getidentitieswithaddress '{"address":"validprimaryaddress","fromheight":height,"toheight":height,"unspent":false}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | A valid primary address — returns all identities containing this address |
| fromheight | number | No | Default = 0. Search from this height forward only |
| toheight | number | No | Default = 0 (no limit). Search up to this height only |
| unspent | bool | No | Default = false. If true, only return active (unspent) ID UTXOs as of current block |

**Result**
```json
[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]
```

An array of matching identity objects, each with an additional `txout` field containing the transaction hash and output index.

**Examples**

**Basic Usage**
```bash
./verus -testnet getidentitieswithaddress '{"address":"<your-R-address>"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon
```

> **⚠️ This command requires the daemon to be started with `-idindex=1`.** Without this flag, the command returns an error. The identity index is not enabled by default because it increases disk usage and sync time.

**With Height Range and Unspent Filter**
```bash
./verus -testnet getidentitieswithaddress '{"address":"<your-R-address>","fromheight":920000,"toheight":930000,"unspent":true}'
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithaddress","params":[{"address":"<your-R-address>"}]}'
```

**Common Use Cases**
- **Reverse lookup**: Find which identities are controlled by a specific address
- **Audit**: Discover all identities a particular key controls
- **Multi-sig investigation**: Find identities that include a specific co-signer address

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `requires -idindex=1 when starting the daemon` | Daemon not started with identity index | Restart daemon with `-idindex=1` flag |
| Invalid address format | Not a valid R-address | Provide a valid transparent address |

**Related Commands**
- [getidentitieswithrecovery](identity.md#getidentitieswithrecovery) — Find identities by recovery authority
- [getidentitieswithrevocation](identity.md#getidentitieswithrevocation) — Find identities by revocation authority
- [getidentity](identity.md#getidentity) — Look up a specific identity by name or i-address

**Notes**
- **Requires `-idindex=1`** daemon flag. This builds an address-to-identity index on disk. Without it, the command cannot function.
- To enable: stop the daemon, restart with `verusd -testnet -idindex=1`. This may require a reindex on first run.
- The `unspent` parameter is useful for filtering out historical (spent) identity UTXOs and showing only the current active state.
- This is a "reverse lookup" — instead of looking up an identity by name, you find identities by one of their constituent addresses.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2
- **Note:** Testing returned error because daemon was not started with `-idindex=1`

---

## getidentitieswithrecovery

> **Category:** Identity | **Version:** v1.2.x+

Returns all identities where a specified identity is set as the recovery authority. Requires the daemon to be started with `-idindex=1`.

**Syntax**
```bash
verus getidentitieswithrecovery '{"identityid":"idori-address","fromheight":height,"toheight":height,"unspent":false}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| identityid | string | Yes | Name (e.g., `"recovery@"`) or i-address — returns all identities where this is the recovery authority |
| fromheight | number | No | Default = 0. Search from this height forward only |
| toheight | number | No | Default = 0 (no limit). Search up to this height only |
| unspent | bool | No | Default = false. If true, only return active (unspent) ID UTXOs |

**Result**
```json
[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]
```

An array of identity objects where the specified ID is the recovery authority.

**Examples**

**Basic Usage**
```bash
./verus -testnet getidentitieswithrecovery '{"identityid":"recovery@"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon
```

> **⚠️ Requires `-idindex=1` daemon flag.**

**Only Active Identities**
```bash
./verus -testnet getidentitieswithrecovery '{"identityid":"recovery@","unspent":true}'
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithrecovery","params":[{"identityid":"recovery@"}]}'
```

**Common Use Cases**
- **Recovery authority audit**: Find all identities you are responsible for recovering
- **Security review**: Check which identities depend on a specific recovery authority
- **Identity management**: Inventory all IDs under your recovery umbrella

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `requires -idindex=1 when starting the daemon` | Daemon not started with identity index | Restart daemon with `-idindex=1` |
| `Identity not found` | The specified recovery identity doesn't exist | Verify the identity name or i-address |

**Related Commands**
- [getidentitieswithrevocation](identity.md#getidentitieswithrevocation) — Find identities by revocation authority
- [getidentitieswithaddress](identity.md#getidentitieswithaddress) — Find identities by primary address
- [getidentity](identity.md#getidentity) — Look up a specific identity

**Notes**
- **Requires `-idindex=1`** daemon flag. See [getidentitieswithaddress](identity.md#getidentitieswithaddress) for details.
- By default, an identity's recovery authority is set to itself. This means querying an identity like `"recovery@"` will return that identity itself, plus any others that have explicitly set it as their recovery authority.
- Recovery authority is the identity that can recover (regain control of) an identity if primary keys are compromised.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2
- **Note:** Testing returned error because daemon was not started with `-idindex=1`

---

## getidentitieswithrevocation

> **Category:** Identity | **Version:** v1.2.x+

Returns all identities where a specified identity is set as the revocation authority. Requires the daemon to be started with `-idindex=1`.

**Syntax**
```bash
verus getidentitieswithrevocation '{"identityid":"idori-address","fromheight":height,"toheight":height,"unspent":false}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| identityid | string | Yes | Name (e.g., `"revocation@"`) or i-address — returns all identities where this is the revocation authority |
| fromheight | number | No | Default = 0. Search from this height forward only |
| toheight | number | No | Default = 0 (no limit). Search up to this height only |
| unspent | bool | No | Default = false. If true, only return active (unspent) ID UTXOs |

**Result**
```json
[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]
```

An array of identity objects where the specified ID is the revocation authority.

**Examples**

**Basic Usage**
```bash
./verus -testnet getidentitieswithrevocation '{"identityid":"revocation@"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon
```

> **⚠️ Requires `-idindex=1` daemon flag.**

**Only Active Identities**
```bash
./verus -testnet getidentitieswithrevocation '{"identityid":"revocation@","unspent":true}'
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithrevocation","params":[{"identityid":"revocation@"}]}'
```

**Common Use Cases**
- **Revocation authority audit**: Find all identities you can revoke
- **Security review**: Understand the scope of a revocation authority's power
- **Key rotation planning**: Before changing a revocation authority, identify all affected identities

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `requires -idindex=1 when starting the daemon` | Daemon not started with identity index | Restart daemon with `-idindex=1` |
| `Identity not found` | The specified identity doesn't exist | Verify the identity name or i-address |

**Related Commands**
- [getidentitieswithrecovery](identity.md#getidentitieswithrecovery) — Find identities by recovery authority
- [getidentitieswithaddress](identity.md#getidentitieswithaddress) — Find identities by primary address
- [getidentity](identity.md#getidentity) — Look up a specific identity

**Notes**
- **Requires `-idindex=1`** daemon flag.
- Revocation authority is the identity that can *revoke* (disable) an identity. This is a critical security role.
- By default, an identity's revocation authority is set to itself. This means querying an identity like `"revocation@"` will return that identity itself, plus any others that have explicitly set it as their revocation authority.
- Revoking an identity prevents it from being used for signing or spending until it is recovered by the recovery authority.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2
- **Note:** Testing returned error because daemon was not started with `-idindex=1`

---

## getidentity

> **Category:** Identity | **Version:** v1.2.x+

Retrieves the full identity object for a given VerusID name or i-address, optionally at a specific block height and with transaction proof.

**Syntax**
```bash
verus getidentity "name@ || iid" (height) (txproof) (txproofheight)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name@ \|\| iid | string | Yes | Name followed by "@" or i-address of an identity |
| height | number | No | Return identity as of this height. Default = current height. Use `-1` to include mempool. |
| txproof | bool | No | Default = false. If true, returns proof of the identity transaction. |
| txproofheight | number | No | Default = same as `height`. Height from which to generate a proof. |

**Result**
Returns a JSON object containing the full identity definition, status, and metadata.

```json
{
  "friendlyname": "myid.VRSCTEST@",
  "fullyqualifiedname": "myid.VRSCTEST@",
  "identity": {
    "version": 3,
    "flags": 0,
    "primaryaddresses": [
      "<R-address>"
    ],
    "minimumsignatures": 1,
    "name": "myid",
    "identityaddress": "i...",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "contentmap": {},
    "contentmultimap": { ... },
    "revocationauthority": "i...",
    "recoveryauthority": "i...",
    "timelock": 0
  },
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0
}
```

**Key Fields**
| Field | Description |
|-------|-------------|
| `friendlyname` | Human-readable fully-qualified name |
| `identity.version` | Identity protocol version (3 = current) |
| `identity.flags` | Bitfield: 0 = normal, 1 = activecurrency (can issue subIDs) |
| `identity.primaryaddresses` | Addresses that control spending |
| `identity.minimumsignatures` | Required signatures for multi-sig |
| `identity.identityaddress` | The i-address of this identity |
| `identity.parent` | Parent namespace i-address |
| `identity.contentmap` | Key-value content stored on the identity |
| `identity.contentmultimap` | Multi-value content (hex-encoded VDXF data) |
| `identity.revocationauthority` | Identity that can revoke this ID |
| `identity.recoveryauthority` | Identity that can recover this ID |
| `identity.timelock` | Block height before which the ID cannot be updated |
| `status` | "active" or "revoked" |
| `canspendfor` | Whether this wallet can spend for this identity |
| `cansignfor` | Whether this wallet can sign for this identity |
| `blockheight` | Block height of the latest identity transaction |
| `txid` | Transaction ID of the latest identity update |

**Examples**

**Basic Usage — Lookup by Name**
```bash
./verus -testnet getidentity "myid@"
```

**Lookup by i-Address**
```bash
./verus -testnet getidentity "i..."
```

**Lookup at a Specific Block Height**
```bash
## Get identity as it was at a specific block height (before any updates)
./verus -testnet getidentity "myid@" <block-height>

## Output shows empty contentmultimap (identity was freshly registered)
{
  "friendlyname": "myid.VRSCTEST@",
  "identity": {
    "version": 3,
    "primaryaddresses": ["<R-address>"],
    "name": "myid",
    "contentmultimap": {},
    ...
  },
  "blockheight": <block-height>,
  ...
}
```

**Include Mempool (Unconfirmed Updates)**
```bash
./verus -testnet getidentity "myid@" -1
```

**With Transaction Proof**
```bash
./verus -testnet getidentity "myid@" <block-height> true
```

**Lookup a SubID**
```bash
./verus -testnet getidentity "alice.yourapp@"
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentity","params":["myid@"]}'
```

**Common Use Cases**
- **Verify an identity exists** before sending funds
- **Check primary addresses** to confirm ownership
- **Inspect contentmultimap** for on-chain metadata (e.g., agent profiles, VDXF data)
- **Historical lookups** to see an identity's state at a past block height
- **Proof generation** for cross-chain or SPV verification

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Identity not found` | Name doesn't exist or is misspelled | Verify the name; remember to include `@` suffix |
| `Invalid identity` | Malformed i-address | Check the i-address format |

**Related Commands**
- [getidentityhistory](identity.md#getidentityhistory) — Get all historical versions of an identity
- [getidentitycontent](identity.md#getidentitycontent) — Get aggregated content across identity history
- [listidentities](identity.md#listidentities) — List identities in the local wallet
- [registernamecommitment](identity.md#registernamecommitment) — First step to registering a new identity

**Name Qualification**

Be careful with name qualification — it's the most common source of "Identity not found" errors:

- `"alice@"` → looks for a **top-level** identity called "alice"
- `"alice.yourapp@"` → looks for a **SubID** "alice" under the "yourapp" namespace
- `"alice.VRSCTEST@"` → fully qualified top-level name on testnet

These are different identities! If alice only exists as a SubID under yourapp, then `getidentity "alice@"` will return "Identity not found" while `getidentity "alice.yourapp@"` succeeds.

**Notes**
- The `@` suffix is required when looking up by name (e.g., `"myid@"` not `"myid"`).
- On VRSCTEST, names are displayed as `name.VRSCTEST@` in `fullyqualifiedname`.
- The `contentmultimap` stores hex-encoded data keyed by VDXF i-addresses. Decode the hex to see the actual content.
- When `flags` = 1, the identity can issue subIDs (has the `activecurrency` flag set).
- `canspendfor` and `cansignfor` are wallet-relative — they indicate whether the *current wallet* has the keys.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## getidentitycontent

> **Category:** Identity | **Version:** v1.2.x+

Retrieves the aggregated content stored on an identity across all its historical updates, combining contentmap and contentmultimap values within a specified block range.

**Syntax**
```bash
verus getidentitycontent "name@ || iid" (heightstart) (heightend) (txproofs) (txproofheight) (vdxfkey) (keepdeleted)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name@ \|\| iid | string | Yes | Name followed by "@" or i-address of an identity |
| heightstart | number | No | Default = 0. Only return content from this height forward (inclusive). |
| heightend | number | No | Default = 0 (max height). Only return content up to this height (inclusive). Use `-1` to include mempool. |
| txproofs | bool | No | Default = false. If true, returns proof of the identity transaction. |
| txproofheight | number | No | Default = "height". Height from which to generate a proof. |
| vdxfkey | string | No | Default = null. Filter for specific VDXF key content only. |
| keepdeleted | bool | No | Default = false. If true, also returns deleted content items. |

**Result**
Returns identity metadata plus a combined `contentmultimap` aggregated from all identity updates in the specified range. Unlike `getidentity` which shows only the latest state, this command collects *all* content values ever written across updates.

```json
{
  "fullyqualifiedname": "myid.VRSCTEST@",
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "fromheight": 0,
  "toheight": 926957,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0,
  "identity": {
    "version": 3,
    "name": "myid",
    "identityaddress": "i...",
    "contentmultimap": {
      "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo": [
        "7b2276657273696f6e223a22312e30222c2274797065223a224149204167656e74227d",
        "7b2276657273696f6e223a22312e30222c2274797065223a224149204167656e74227d",
        "..."
      ]
    },
    "..."
  }
}
```

**Important:** The `contentmultimap` in this response aggregates values from *every* identity update in the height range. This means duplicate entries appear if the same key was included in multiple updates. The `fromheight` and `toheight` fields confirm the search range.

**Examples**

**Basic Usage**
```bash
./verus -testnet getidentitycontent "myid@"
```

**Content from a Specific Height Range**
```bash
## Only get content added between blocks 925000 and 926000
./verus -testnet getidentitycontent "myid@" 925000 926000
```

**Include Mempool Content**
```bash
./verus -testnet getidentitycontent "myid@" 0 -1
```

**Filter by VDXF Key**
```bash
## iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo is the i-address of `vrsc::system.agent.profile`, a built-in Verus system VDXF key — `getvdxfid` produces the same hash for everyone
./verus -testnet getidentitycontent "myid@" 0 0 false 0 "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo"
```

**Include Deleted Content**
```bash
./verus -testnet getidentitycontent "myid@" 0 0 false 0 "*" true
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitycontent","params":["myid@"]}'
```

**Common Use Cases**
- **Audit trail**: See all content ever written to an identity across all updates
- **Content aggregation**: Collect all service listings, profile data, or VDXF records
- **Selective queries**: Use `vdxfkey` to search for specific content types
- **Forensic analysis**: Use `keepdeleted` to recover removed content

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Identity not found` | Name doesn't exist | Verify the name with `@` suffix |
| Empty contentmultimap | Identity has no on-chain content | This is valid — the identity simply has no stored data |

**Related Commands**
- [getidentity](identity.md#getidentity) — Get current state of an identity (latest update only)
- [getidentityhistory](identity.md#getidentityhistory) — Get full identity objects at each update point

**Notes**
- Unlike `getidentity` which returns only the *current* content, `getidentitycontent` aggregates across all updates. This means you'll see duplicate entries for content that was present in multiple updates.
- Content values are hex-encoded. Decode with standard hex-to-string conversion.
- The `vdxfkey` parameter is useful for efficiently querying a specific data type without downloading all content.
- `keepdeleted` is valuable for auditing — content that was removed in a later update can still be retrieved.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## getidentityhistory

> **Category:** Identity | **Version:** v1.2.x+

Retrieves the complete history of an identity, returning the full identity object at each update point within a specified block range.

**Syntax**
```bash
verus getidentityhistory "name@ || iid" (heightstart) (heightend) (txproofs) (txproofheight)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name@ \|\| iid | string | Yes | Name followed by "@" or i-address of an identity |
| heightstart | number | No | Default = 0. Only return history from this height forward (inclusive). |
| heightend | number | No | Default = 0 (max height). Only return history up to this height (inclusive). Use `-1` to include mempool. |
| txproofs | bool | No | Default = false. If true, returns proof of each identity transaction. |
| txproofheight | number | No | Default = "height". Height from which to generate proofs. |

**Result**
Returns identity metadata plus a `history` array containing the full identity object at each update, in chronological order.

```json
{
  "fullyqualifiedname": "myid.VRSCTEST@",
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0,
  "history": [
    {
      "identity": {
        "version": 3,
        "name": "myid",
        "contentmultimap": {}
      },
      "blockhash": "208172af9b283a1f06e5775f532134d6858393b076808fe415ea960dcca74125",
      "height": <block-height>,
      "output": {
        "txid": "b4af174d4bee117a8f6bd4fa47e5f0195d1409302aca4aeba08acd391e5c9954",
        "voutnum": 0
      }
    },
    {
      "identity": {
        "version": 3,
        "name": "myid",
        "contentmultimap": {
          "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo": ["..."]
        }
      },
      "blockhash": "00000000e60e18baa0daa50c6d55186face08c2f6d39ddc2557021cef7ef1130",
      "height": <block-height>,
      "output": { "txid": "edcfe0a06a...", "voutnum": 0 }
    }
  ]
}
```
*(Output truncated — example identity had multiple historical updates across a range of blocks)*

**History Entry Fields**
| Field | Description |
|-------|-------------|
| `identity` | Full identity object at that point in time |
| `blockhash` | Hash of the block containing this update |
| `height` | Block height of this update |
| `output.txid` | Transaction ID of the identity UTXO |
| `output.voutnum` | Output index in the transaction |

**Examples**

**Full History**
```bash
./verus -testnet getidentityhistory "myid@"
```

**History in a Block Range**
```bash
## Only show updates between blocks 925000 and 926000
./verus -testnet getidentityhistory "myid@" 925000 926000
```

**Include Mempool**
```bash
./verus -testnet getidentityhistory "myid@" 0 -1
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentityhistory","params":["myid@"]}'
```

**Common Use Cases**
- **Track identity changes** over time (address changes, content updates, authority changes)
- **Audit revocation/recovery authority changes** for security analysis
- **Reconstruct timeline** of content updates to an identity
- **Detect unauthorized modifications** by comparing expected vs. actual state at each point

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Identity not found` | Name doesn't exist | Verify name with `@` suffix |
| Empty history array | No updates in the specified range | Widen the block range |

**Related Commands**
- [getidentity](identity.md#getidentity) — Get current identity state only
- [getidentitycontent](identity.md#getidentitycontent) — Get aggregated content across updates

**Notes**
- Each entry in the `history` array represents a complete snapshot of the identity at that block height. You can see exactly what changed between updates by diffing consecutive entries.
- The first entry is always the identity registration (creation) transaction.
- Multiple updates can occur at the same block height — for example, if an identity has a key rotation and a content update in the same block.
- For identities with many updates, the response can be large. Use `heightstart`/`heightend` to limit scope.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## getidentitytrust

> **Category:** Identity | **Version:** v1.2.x+

Retrieves identity trust/rating settings for the local node. These settings control which identities the node will sync data for, acting as a local allowlist/blocklist system.

**Syntax**
```bash
verus getidentitytrust '["id",...]'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| ids | string array | No | If specified, only returns rating values for the listed IDs. If omitted or empty, returns all ratings. |

**Result**
```json
{
  "setratings": { "id": JSONRatingObject, ... },
  "identitytrustmode": 0
}
```

| Field | Description |
|-------|-------------|
| `setratings` | Key-value object mapping identity IDs to their rating objects |
| `identitytrustmode` | `0` = no restriction on sync, `1` = only sync IDs rated approved, `2` = sync all IDs except those on block list |

**Examples**

**Get All Trust Settings**
```bash
./verus -testnet getidentitytrust '[]'

## Actual Output (tested on VRSCTEST)
## (empty output — no trust ratings configured on this node)
```

**Query Specific Identity**
```bash
./verus -testnet getidentitytrust '["myid@"]'

## Actual Output (tested on VRSCTEST)
## (empty output — no rating set for myid@)
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitytrust","params":[["myid@"]]}'
```

**Common Use Cases**
- **Check trust configuration**: See which identities are allowed/blocked for sync
- **Audit node settings**: Verify trust mode before deploying
- **Content filtering**: Use in conjunction with `setidentitytrust` to control what data your node syncs

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Parse error | Malformed JSON array | Ensure proper JSON: `'["id1","id2"]'` |
| Empty result | No trust ratings configured | This is normal for a default node — trust mode 0 means no restrictions |

**Related Commands**
- [setidentitytrust](identity.md#setidentitytrust) — Set trust ratings for identities
- [getidentity](identity.md#getidentity) — Look up an identity

**Notes**
- When no trust ratings are configured and `identitytrustmode` is 0, the node syncs all identity data without restriction.
- Trust mode 1 (allowlist) is the most restrictive — only explicitly approved IDs sync.
- Trust mode 2 (blocklist) syncs everything except blocked IDs.
- This is a **local node setting** — it does not affect the blockchain or other nodes.
- The command returns empty output (not an error) when no ratings are set.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## listidentities

> **Category:** Identity | **Version:** v1.2.x+

Lists all identities in the local wallet, with options to filter by spending, signing, or watch-only capability.

**Syntax**
```bash
verus listidentities (includecanspend) (includecansign) (includewatchonly)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| includecanspend | bool | No | Default = true. Include identities the wallet can spend/authorize for. |
| includecansign | bool | No | Default = true. Include identities the wallet can only sign for (but not spend). |
| includewatchonly | bool | No | Default = false. Include identities the wallet can neither sign nor spend, but watches or co-signs for. |

**Result**
Returns an array of identity objects with wallet-specific status fields.

```json
[
  {
    "identity": {
      "version": 3,
      "flags": 0,
      "primaryaddresses": ["<R-address>"],
      "minimumsignatures": 1,
      "name": "myid",
      "identityaddress": "i...",
      "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "contentmap": {},
      "contentmultimap": { "..." },
      "revocationauthority": "i...",
      "recoveryauthority": "i...",
      "timelock": 0
    },
    "blockheight": <block-height>,
    "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
    "status": "active",
    "canspendfor": true,
    "cansignfor": true
  },
  {
    "identity": {
      "name": "yourapp",
      "flags": 1,
      "identityaddress": "i...",
      "..."
    },
    "blockheight": 926587,
    "status": "active",
    "canspendfor": true,
    "cansignfor": true
  },
  {
    "identity": {
      "name": "mymultisig",
      "primaryaddresses": [
        "<R-address-1>",
        "<R-address-2>"
      ],
      "minimumsignatures": 2,
      "..."
    },
    "status": "active",
    "canspendfor": false,
    "cansignfor": true
  }
]
```
*(Output truncated — test wallet contained 10 identities including myid@, yourapp@, alice.yourapp@, bob.yourapp@, and others)*

**Notable Observations from Testing**
- `canspendfor: true` — wallet has enough keys to meet `minimumsignatures`
- `canspendfor: false, cansignfor: true` — wallet has *some* keys but not enough (e.g., `mymultisig@` requires 2 of 2 sigs, wallet only has 1 key)
- SubIDs (like `alice.yourapp@`) appear alongside top-level IDs

**Examples**

**List All Spendable Identities (Default)**
```bash
./verus -testnet listidentities
```

**Only Signable (Not Spendable)**
```bash
./verus -testnet listidentities false true false
```

**Include Watch-Only**
```bash
./verus -testnet listidentities true true true
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"listidentities","params":[true]}'
```

**Common Use Cases**
- **Wallet inventory**: See all identities controlled by this wallet
- **Multi-sig audit**: Identify which identities the wallet can sign for but not fully spend
- **Application startup**: Enumerate available identities for a user interface

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty array `[]` | No identities in wallet | Register an identity or import keys |
| Wallet not loaded | Wallet is encrypted/locked | Unlock wallet with `walletpassphrase` |

**Related Commands**
- [getidentity](identity.md#getidentity) — Get details for a specific identity
- [registernamecommitment](identity.md#registernamecommitment) — Begin registering a new identity
- [registeridentity](identity.md#registeridentity) — Complete identity registration

**Notes**
- This command only shows identities for which the local wallet has relevant keys. It does **not** search the entire blockchain.
- The distinction between `canspendfor` and `cansignfor` matters for multi-sig identities. A wallet might hold 1 of 2 required keys — it can sign but not spend alone.
- SubIDs (e.g., `alice.yourapp@`) appear in the list if the wallet holds their keys, even if the parent identity is a different wallet.
- The `flags` field value of `1` indicates the identity has the `activecurrency` flag (can issue subIDs).

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## recoveridentity

> **Category:** Identity | **Version:** v1.2.x+

⚠️ **SENSITIVE** — Recover a revoked VerusID by providing a new identity definition with updated keys.

**Syntax**
```bash
verus recoveridentity "jsonidentity" (returntx) (tokenrecover) (feeoffer) (sourceoffunds)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| jsonidentity | object | Yes | New identity definition with updated keys/addresses |
| returntx | bool | No | If true, return signed tx instead of broadcasting. Default: false |
| tokenrecover | bool | No | If true, use tokenized ID control token for recovery. Default: false |
| feeoffer | value | No | Non-standard fee amount |
| sourceoffunds | string | No | Transparent or private address to source fees from |

**Result**
```
transactionid    (string) txid if returntx is false, or hex transaction if returntx is true
```

**Examples**

**⚠️ UNTESTED — Recovery is only possible on revoked identities**

**Basic Usage**
```bash
## Recover a revoked identity with new primary addresses
./verus -testnet recoveridentity '{"name":"myname", "primaryaddresses":["RNewAddressHere"], "minimumsignatures":1}'
```

**Full Recovery with New Authorities**
```bash
./verus -testnet recoveridentity '{
  "name": "myname",
  "primaryaddresses": ["RNewAddress1"],
  "minimumsignatures": 1,
  "revocationauthority": "newrevoker@",
  "recoveryauthority": "newrecoverer@"
}'
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"recoveridentity","params":[{"name":"myname","primaryaddresses":["RNewAddr"],"minimumsignatures":1}]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**
- **Key compromise recovery** — revoke the identity, then recover with fresh keys
- **Key rotation** — revoke + recover as a way to completely rotate all identity keys
- **Regain access** — recover an identity that was revoked (intentionally or by revocation authority)

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Not authorized | Wallet doesn't hold recovery authority keys | Import the recovery authority's private key |
| Identity not revoked | Cannot recover an identity that isn't revoked | Revoke first with `revokeidentity` |
| Identity not found | Invalid name or i-address | Check the identity name/address |

**Related Commands**
- [`revokeidentity`](#revokeidentity) — Revoke an identity (required before recovery)
- [`updateidentity`](#updateidentity) — Update identity (for non-revoked IDs)
- [`getidentity`](#getidentity) — Check current identity status

**Notes**
- Recovery requires the **recovery authority** keys — not the primary keys or revocation authority
- The identity must be in a **revoked state** before it can be recovered
- Recovery lets you set **completely new** primary addresses, effectively rotating all keys
- You can also change the revocation and recovery authorities during recovery
- This is the last line of defense — if both primary keys AND recovery authority are compromised, the identity is lost
- Best practice: set recovery authority to a cold-storage identity or a trusted multisig
- For subIDs, include the `parent` field (same gotcha as `updateidentity`)

**Tested On**
- ⚠️ Not tested (requires a revoked identity)
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## registeridentity

> **Category:** Identity | **Version:** v1.2.x+

Register a new VerusID identity on-chain using a prior name commitment.

**Syntax**
```bash
verus registeridentity "jsonidregistration" (returntx) (feeoffer) (sourceoffunds)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| jsonidregistration | object | Yes | JSON object containing txid, namereservation, and identity definition |
| returntx | bool | No | If true, return signed tx hex instead of broadcasting. Default: false |
| feeoffer | amount | No | Fee to offer miner/staker. If omitted, uses standard price |
| sourceoffunds | string | No | Address to source funds from. Default: transparent wildcard "*" |

**jsonidregistration Structure**
```json
{
  "txid": "hexid",
  "namereservation": {
    "name": "namestr",
    "salt": "hexstr",
    "referral": "identityID",
    "parent": "",
    "nameid": "iAddress",
    "version": 1
  },
  "identity": {
    "name": "namestr",
    "primaryaddresses": ["Raddress"],
    "minimumsignatures": 1,
    "revocationauthority": "nameorID",
    "recoveryauthority": "nameorID",
    "privateaddress": "zs-address"
  }
}
```

**Result**
```
transactionid    (string) The transaction ID of the registration
```

**Examples**

**⚠️ UNTESTED — Registration requires a prior `registernamecommitment` and costs VRSC**

**Two-Step Registration Process**
```bash
## Step 1: Create a name commitment (returns txid, salt, etc.)
./verus -testnet registernamecommitment "myname" "controladdress" "referralID"

## Step 2: Register using the commitment output
./verus -testnet registeridentity '{
  "txid": "commitment_txid_hex",
  "namereservation": {
    "name": "myname",
    "salt": "salt_from_commitment",
    "referral": "referralID@",
    "parent": "",
    "nameid": "nameid_from_commitment",
    "version": 1
  },
  "identity": {
    "name": "myname",
    "primaryaddresses": ["<your-R-address>"],
    "minimumsignatures": 1,
    "version": 3
  }
}'
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"registeridentity","params":[{"txid":"hexid","namereservation":{"name":"myname","salt":"hexsalt","referral":""},"identity":{"name":"myname","primaryaddresses":["Raddr"],"minimumsignatures":1}}]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**
- **Creating a new VerusID** — the standard way to register an identity after name commitment
- **Multisig identity** — specify multiple `primaryaddresses` and set `minimumsignatures` > 1
- **With referral** — include a referral identity for fee discount

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Name commitment not found | Invalid or expired txid | Create a new `registernamecommitment` |
| Name already registered | Someone registered the name first | Choose a different name |
| Insufficient funds | Not enough VRSC for registration fee | Fund the wallet or specify `sourceoffunds` |
| Must wait for commitment to be mined | Commitment tx not yet confirmed | Wait for at least 1 confirmation |

**Related Commands**
- [`registernamecommitment`](#registernamecommitment) — Step 1: create a name commitment (required before registeridentity)
- [`getidentity`](#getidentity) — Look up a registered identity
- [`updateidentity`](#updateidentity) — Modify an existing identity
- [`listidentities`](#listidentities) — List identities in wallet

**Notes**
- Registration is a **two-step process**: first `registernamecommitment`, then `registeridentity`
- The name commitment must be mined (1 confirmation) before registration
- Name commitments expire — register promptly after commitment confirms
- Registration fee varies by chain; use `feeoffer` to override
- Identity names are **case-insensitive** and unique per parent chain
- Once registered, an identity cannot be deleted, only revoked/recovered

**Tested On**
- ⚠️ Not directly tested (destructive/costly operation)
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## registernamecommitment

> **Category:** Identity | **Version:** v1.2.x+

Registers a name commitment, which is the required first step for registering a new VerusID. The commitment hides the desired name in a hash to prevent front-running by miners, while ensuring fair name registration.

**Syntax**
```bash
verus registernamecommitment "name" "controladdress" ("referralidentity") ("parentnameorid") ("sourceoffunds")
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | Yes | The unique name to commit to. Creating a commitment for a name that already exists will succeed but can never be used. |
| controladdress | address | Yes | Address that controls this commitment. Must be in the current wallet. **Not necessarily the address that will control the final ID.** Change may go to this address. |
| referralidentity | identity | No | Friendly name or i-address used as referral — lowers network cost of the ID. |
| parentnameorid | currency | No | Parent namespace name or i-address (PBaaS only). Dictates issuance rules & pricing. |
| sourceoffunds | address/id | No | Address to use as source of funds. Default: transparent wildcard `"*"`. |

**Result**
```json
{
  "txid": "hexid",
  "namereservation": {
    "name": "namestr",
    "salt": "hexstr",
    "referral": "identityaddress",
    "parent": "namestr",
    "nameid": "address"
  }
}
```

| Field | Description |
|-------|-------------|
| `txid` | Transaction ID of the commitment transaction |
| `namereservation.name` | The name being committed to |
| `namereservation.salt` | Random salt used to hide the commitment (keep this!) |
| `namereservation.referral` | Referral identity address (if provided) |
| `namereservation.parent` | Parent namespace name |
| `namereservation.nameid` | The i-address the identity will have if registered |

**Examples**

**Basic Name Commitment**
```bash
./verus -testnet registernamecommitment "mynewid" "<your-R-address>"
```

**With Referral Identity**
```bash
./verus -testnet registernamecommitment "mynewid" "<your-R-address>" "myid@"
```

**SubID Under a Parent Namespace**
```bash
./verus -testnet registernamecommitment "newname" "<your-R-address>" "" "yourapp@"
```

**RPC (curl)**
```bash
curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"registernamecommitment","params":["mynewid","<your-R-address>"]}'
```

**Common Use Cases**
- **Step 1 of identity registration**: Always required before `registeridentity`
- **Name squatting prevention**: The commitment-reveal scheme prevents miners from stealing names
- **SubID creation**: Use `parentnameorid` to create identities under a namespace you control

**Two-Step Registration Process**
1. **`registernamecommitment`** — Creates a hidden commitment (this command)
2. Wait for the commitment to be mined (at least 1 confirmation)
3. **`registeridentity`** — Reveals the name and completes registration using the commitment output

```bash
## Step 1: Commit
./verus -testnet registernamecommitment "myname" "RMyAddress..."

## Step 2: Wait for confirmation, then register
./verus -testnet registeridentity '{"txid":"<txid>","namereservation":{"name":"myname","salt":"<salt>","nameid":"<nameid>"},"identity":{"name":"myname","primaryaddresses":["RMyAddress..."],"minimumsignatures":1}}'
```

**Name Rules**
Names must **not** have:
- Leading, trailing, or multiple consecutive spaces
- Any of these characters: `\ / : * ? " < > | @`

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Insufficient funds` | Not enough VRSC/VRSCTEST in wallet | Fund the control address |
| `Invalid name` | Name contains forbidden characters | Remove special characters (see Name Rules above) |
| `Invalid Verus address` | Control address not valid | Use a valid R-address from the current wallet |
| Commitment for existing name | Name already registered | The commitment succeeds but `registeridentity` will fail. Check name availability first with `getidentity`. |

**Related Commands**
- [registeridentity](identity.md#registeridentity) — Step 2: Complete registration using the commitment
- [getidentity](identity.md#getidentity) — Check if a name is already taken
- [listidentities](identity.md#listidentities) — List identities in your wallet

**Notes**
- **Save the output!** The `namereservation` object (especially `salt`) is required for `registeridentity`. If lost, the commitment is wasted.
- The commitment must be mined before you can register. Wait for at least 1 block confirmation.
- Creating a commitment does **not** guarantee the name — someone else could register it first if they had an earlier commitment.
- The `controladdress` receives change from the commitment transaction. It does not need to be a primary address of the final identity.
- Commitments expire after a certain number of blocks if not used with `registeridentity`.
- On testnet, identity registration costs are minimal. On mainnet, costs vary and referrals can reduce fees.
- **Did not run live test** to avoid creating unnecessary commitments on testnet. The command structure and parameters are documented from help text and prior testing experience.

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 1.2.14-2

---

## revokeidentity

> **Category:** Identity | **Version:** v1.2.x+

⚠️ **DESTRUCTIVE** — Revoke a VerusID, disabling it from signing, spending, or being used for authentication until recovered.

**Syntax**
```bash
verus revokeidentity "nameorID" (returntx) (tokenrevoke) (feeoffer) (sourceoffunds)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| nameorID | string | Yes | The identity name (e.g., `myid@`) or i-address to revoke |
| returntx | bool | No | If true, return signed tx instead of broadcasting. Default: false |
| tokenrevoke | bool | No | If true, use tokenized ID control token for revocation. Default: false |
| feeoffer | value | No | Non-standard fee amount |
| sourceoffunds | string | No | Transparent or private address to source fees from |

**Result**
```
transactionid    (string) txid if returntx is false, or hex transaction if returntx is true
```

**Examples**

**⚠️ UNTESTED — This is a destructive operation**

**Basic Usage**
```bash
## Revoke an identity (CAUTION: identity becomes unusable until recovered)
./verus -testnet revokeidentity "myidentity@"
```

**Dry Run (inspect before broadcasting)**
```bash
## Return transaction hex without broadcasting
./verus -testnet revokeidentity "myidentity@" true
```

**Token-Based Revocation**
```bash
## Use tokenized control token for revocation authority
./verus -testnet revokeidentity "myidentity@" false true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"revokeidentity","params":["myidentity@"]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/
```

**Common Use Cases**
- **Compromised identity** — immediately revoke if private keys are stolen
- **Security lockdown** — revoke to prevent any transactions while investigating a breach
- **Pre-recovery** — revoke before using `recoveridentity` to rotate keys

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Not authorized | Wallet doesn't hold revocation authority keys | Import the revocation authority's private key |
| Identity not found | Invalid name or i-address | Check the identity name/address |
| Already revoked | Identity is already in revoked state | Use `recoveridentity` to restore |

**Related Commands**
- [`recoveridentity`](#recoveridentity) — Recover a revoked identity with new keys
- [`updateidentity`](#updateidentity) — Update identity (cannot be done while revoked)
- [`getidentity`](#getidentity) — Check identity status (flags will show revoked state)

**Notes**
- **This is a destructive operation** — a revoked identity cannot sign, spend funds, or authenticate
- Revocation requires the **revocation authority** keys, not the primary keys
- After revocation, only `recoveridentity` (using the **recovery authority**) can restore the identity
- It's good practice to set revocation and recovery authorities to **different** identities for security
- Use `returntx true` to inspect the transaction before committing
- Revocation is an on-chain transaction — it takes effect once mined
- The revocation and recovery authority design means even if primary keys are compromised, you can revoke and recover

**Tested On**
- ⚠️ Not tested (destructive operation)
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## setidentitytimelock

> **Category:** Identity | **Version:** v1.2.x+

Enable timelocking and unlocking of fund access for an on-chain VerusID. Provides time-delayed security against unauthorized spending.

**Syntax**
```bash
verus setidentitytimelock "id@" '{"unlockatblock": height}' (returntx) (feeoffer) (sourceoffunds)
verus setidentitytimelock "id@" '{"setunlockdelay": blocks}' (returntx) (feeoffer) (sourceoffunds)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id@ | string | Yes | The identity name or i-address to timelock |
| unlockatblock | number | No* | Absolute block height at which the ID unlocks. Countdown starts immediately when mined |
| setunlockdelay | number | No* | Number of blocks to delay after an unlock request before funds become spendable |
| returntx | bool | No | If true, return signed tx instead of broadcasting. Default: false |
| feeoffer | value | No | Non-standard fee amount |
| sourceoffunds | string | No | Transparent or private address to source fees from |

*One of `unlockatblock` or `setunlockdelay` must be specified, but not both.

**Result**
```
hexstring    (string) txid if returntx is false, or hex serialized transaction if returntx is true
```

**Examples**

**⚠️ UNTESTED — Timelocking is a sensitive operation that restricts fund access**

**Set an Unlock Delay (Recommended for Security)**
```bash
## Require 100 blocks (~100 minutes) delay after unlock request before spending
./verus -testnet setidentitytimelock "myid@" '{"setunlockdelay": 100}'
```

**Set Absolute Unlock Time**
```bash
## Lock until block 1000000 — countdown starts immediately
./verus -testnet setidentitytimelock "myid@" '{"unlockatblock": 1000000}'
```

**Unlock a Delayed Identity**
```bash
## Set unlockatblock to current block to begin the unlock delay countdown
./verus -testnet setidentitytimelock "myid@" '{"unlockatblock": 926957}'
```

**Dry Run**
```bash
./verus -testnet setidentitytimelock "myid@" '{"setunlockdelay": 100}' true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setidentitytimelock","params":["myid@",{"setunlockdelay":100}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Cold storage security** — lock an identity so funds can't be spent instantly even if keys are compromised
- **Delayed withdrawal** — give yourself a window to revoke if unauthorized unlock is detected
- **Service integration** — services can check lock status and refuse transfers when locked

**Two Locking Modes**

**`setunlockdelay` (Relative Lock)**
- Sets a **delay period** (in blocks) that must pass after an unlock request
- Unlock request = calling `setidentitytimelock` with `unlockatblock` set to current block
- The delay countdown **only starts** when you actively request unlock
- Best for: ongoing security (like a time-lock safe)

**`unlockatblock` (Absolute Lock)**
- Locks until a **specific block height**
- Countdown starts **immediately** when the transaction is mined
- Set to current block height to begin unlocking (still subject to any unlock delay)
- Best for: scheduled unlocks or initiating the unlock process

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Cannot specify both | Both unlockatblock and setunlockdelay provided | Use only one at a time |
| Not authorized | Wallet doesn't hold identity's signing keys | Import the primary key |
| Identity not found | Invalid name or i-address | Verify the identity exists |

**Related Commands**
- [`getidentity`](#getidentity) — Check current timelock status in identity flags
- [`updateidentity`](#updateidentity) — General identity updates
- [`revokeidentity`](#revokeidentity) — Revoke/recover can bypass timelock

**Notes**
- Timelocking is **per-chain** — it does not affect the same identity exported to other chains
- A timelocked identity **prevents all updates** (including contentmultimap changes) until unlocked
- **Locked funds can still stake** — timelocking does not prevent staking rewards
- The **only way to remove a timelock** is through **revoke and recover** — this is by design. Revoking and recovering a timelocked identity removes the timelock entirely
- There is no other mechanism to cancel or shorten a timelock once set
- Services supporting VerusID authentication may also honor the lock status for non-spending operations
- Average block time on Verus is ~60 seconds, so ~1440 blocks ≈ 1 day
- Use `getidentity` to check the current lock state and timelock parameters

**Tested On**
- ⚠️ Not directly tested (would lock fund access)
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## setidentitytrust

> **Category:** Identity | **Version:** v1.2.x+

Set trust ratings for VerusIDs and configure identity trust mode for wallet sync filtering.

**Syntax**
```bash
verus setidentitytrust '{"clearall": bool, "setratings":{"id":JSONRatingObject,...}, "removeratings":["id",...], "identitytrustmode": n}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| clearall | bool | No | If true, clears all wallet trust lists before applying changes |
| setratings | object | No | Key-value pairs of identity names/addresses to rating objects |
| removeratings | array | No | Array of identity names/addresses to remove from trust list |
| identitytrustmode | number | No | 0 = no restriction, 1 = only sync approved IDs, 2 = sync all except blocked |

**Trust Modes**
| Mode | Behavior |
|------|----------|
| 0 | No restriction on identity sync (default) |
| 1 | Only sync identities rated as approved |
| 2 | Sync all identities except those on the block list |

**Result**
```
No return on success, error on failure.
```

**Examples**

**Set Trust Rating for an Identity**
```bash
## Set trust level for myid@
./verus -testnet setidentitytrust '{"setratings":{"myid@":{"trustlevel":2}}, "identitytrustmode":0}'

## Actual Output (tested on VRSCTEST)
## (no output — success returns nothing)
```

**Remove Trust Ratings**
```bash
./verus -testnet setidentitytrust '{"removeratings":["myid@"]}'
```

**Clear All and Set Fresh**
```bash
./verus -testnet setidentitytrust '{"clearall":true, "setratings":{"myid@":{"trustlevel":1}}, "identitytrustmode":1}'
```

**Read Trust Ratings**
```bash
## Use getidentitytrust to read (separate command)
./verus -testnet getidentitytrust '["myid@"]'
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setidentitytrust","params":[{"setratings":{"myid@":{"trustlevel":2}},"identitytrustmode":0}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Whitelist identities** — approve specific IDs for sync in restrictive mode
- **Block spam identities** — add untrusted IDs to block list with mode 2
- **Wallet sync optimization** — limit which identities your wallet tracks

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Invalid JSON | Malformed JSON input | Validate JSON syntax |
| Unknown identity | Identity name doesn't resolve | Use i-address instead |

**Related Commands**
- `getidentitytrust` — Read current trust ratings and mode
- [`getidentity`](#getidentity) — Look up identity details

**Notes**
- Trust ratings are **local to your wallet** — they don't affect the blockchain
- Trust mode controls which identities your wallet syncs/tracks
- Mode 1 (approved only) is the most restrictive — useful for resource-constrained nodes
- The `setratings` and `removeratings` operations can be combined in a single call
- `clearall` is processed first, then `setratings`, then `removeratings`
- Success returns no output (null) — check with `getidentitytrust` to confirm

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## signdata

> **Category:** Identity | **Version:** v1.2.x+

Sign data with a VerusID or t-address using advanced options including VDXF keys, bound hashes, hash type selection, and MMR (Merkle Mountain Range) support.

**Syntax**
```bash
verus signdata '{"address":"id@", "message":"data", ...}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | VerusID (e.g., `myid@`) or t-address to sign with |
| message | string | No* | Plain text message to sign |
| filename | string | No* | File path to sign |
| messagehex | string | No* | Hex-encoded data to sign |
| messagebase64 | string | No* | Base64-encoded data to sign |
| datahash | string | No* | Pre-computed 256-bit hex hash to sign directly |
| vdxfdata | string | No* | VDXF-encoded data to sign |
| prefixstring | string | No | Extra string hashed during signature (must be supplied for verification) |
| vdxfkeys | array | No | Array of VDXF key i-addresses to bind to signature |
| vdxfkeynames | array | No | Array of VDXF key names or friendly IDs |
| boundhashes | array | No | Array of hex hashes to bind to signature |
| hashtype | string | No | `sha256` (default), `sha256D`, `blake2b`, or `keccak256` |
| encrypttoaddress | string | No | Sapling address to encrypt data to |
| createmmr | bool | No | If true, creates MMR from multiple data items |
| mmrdata | array | No | Array of data objects for MMR signing |
| mmrsalt | array | No | Salt values for MMR leaf privacy |
| mmrhash | string | No | Hash type for MMR (default: blake2b) |
| signature | string | No | Current partial signature for multisig IDs |
| priormmr | array | No | Prior MMR data (currently UNIMPLEMENTED in daemon) |

*One data parameter is required.

**Result**
```json
{
  "signaturedata": {
    "version": 1,
    "systemid": "iAddress",
    "hashtype": 5,
    "signaturehash": "hexhash",
    "identityid": "iAddress",
    "signaturetype": 1,
    "signature": "base64sig"
  },
  "system": "VRSCTEST",
  "systemid": "iAddress",
  "hashtype": "sha256",
  "hash": "hexhash",
  "identity": "name@",
  "canonicalname": "name@",
  "address": "iAddress",
  "signatureheight": 926957,
  "signatureversion": 2,
  "signature": "base64sig"
}
```

**Examples**

**Basic Usage — Sign a Message**
```bash
## Command
./verus -testnet signdata '{"address":"myid@", "message":"Hello from myid - testing signdata for wiki docs"}'

## Actual Output (tested on VRSCTEST)
{
  "signaturedata": {
    "version": 1,
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "hashtype": 5,
    "signaturehash": "6972221095db42a7c97bd325ab7b6c641d3372be2ae0b435f7696c90789260c6",
    "identityid": "i...",
    "signaturetype": 1,
    "signature": "AgXtJA4AAUEfK2i7aQevRK3PPJFttLTRk7bkXeKE8vMPd+KE3fobhnViIM496FCXFN4TN2Nh0iQ5fOlcc8VHJqCOTEDa03gvrQ=="
  },
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "hashtype": "sha256",
  "hash": "6972221095db42a7c97bd325ab7b6c641d3372be2ae0b435f7696c90789260c6",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "signatureheight": 926957,
  "signatureversion": 2,
  "signature": "AgXtJA4AAUEfK2i7aQevRK3PPJFttLTRk7bkXeKE8vMPd+KE3fobhnViIM496FCXFN4TN2Nh0iQ5fOlcc8VHJqCOTEDa03gvrQ=="
}
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signdata","params":[{"address":"myid@","message":"hello world"}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Data attestation** — sign arbitrary data with a VerusID for provable authorship
- **VDXF-bound signatures** — bind signatures to specific VDXF data types
- **Multi-object MMR** — sign multiple pieces of data in a single Merkle Mountain Range
- **Encrypted data** — sign and encrypt data to a Sapling address

**signdata vs signmessage**
| Feature | signdata | signmessage |
|---------|----------|-------------|
| Output format | Full JSON with signaturedata | Simple hash + signature |
| Signature version | v2 (includes system context) | v1 (simple) |
| VDXF keys | ✅ | ❌ |
| Bound hashes | ✅ | ❌ |
| Hash type selection | ✅ | ❌ (SHA256 only) |
| MMR support | ✅ | ❌ |
| Verification | `verifysignature` (use `datahash`) | `verifymessage` |

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| No data to sign | Missing message/filename/datahash | Provide at least one data parameter |
| Not authorized | Wallet doesn't hold signing keys for identity | Import the private key |
| Identity not found | Invalid identity name or address | Verify the identity exists |

**Related Commands**
- [`verifysignature`](#verifysignature) — Verify a signdata signature (use `datahash` from output)
- [`signmessage`](#signmessage) — Simpler message signing (v1 signatures)
- [`signfile`](#signfile) — Simple file signing

**Notes**
- Returns **signature version 2** which includes system context in the hash — this means the hash differs from a simple SHA256 of the message
- To verify with `verifysignature`, use the `datahash` field from `signdata` output, NOT the original message (the message-based verification won't match due to v2 hashing)
- The `signaturedata` field contains the raw serialized signature data
- `signatureheight` records the block height at signing time, used for identity state verification
- Supports multisig via the `signature` parameter — pass partial signatures for accumulation

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## signfile

> **Category:** Identity | **Version:** v1.2.x+

Generate a SHA256D hash of a file and sign it with a VerusID or t-address.

**Syntax**
```bash
verus signfile "address or identity" "filepath/filename" ("currentsig")
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | t-address or VerusID (e.g., `myid@`) to sign with |
| filename | string | Yes | Path to local file to sign |
| cursig | string | No | Current partial signature (base64) for multisig IDs |

**Result**
```json
{
  "hash": "hexhash",
  "signature": "base64sig"
}
```

**Examples**

**Basic Usage**
```bash
## Command
./verus -testnet signfile "myid@" "/tmp/verus_test_sign.txt"

## Actual Output (tested on VRSCTEST)
{
  "hash": "720949abdd085252234efa73c02059fdc876f3c2295dd413e020d04292620c5d",
  "signature": "Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186"
}
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signfile","params":["myid@","/tmp/verus_test_sign.txt"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Document signing** — prove authorship or approval of a file
- **Software releases** — sign binaries or archives for verification
- **Audit trails** — create verifiable signatures for compliance documents

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| File not found | Invalid file path | Use absolute path accessible to the daemon |
| Not authorized | Wallet doesn't hold signing keys | Import the private key |
| Identity not found | Invalid identity name | Check spelling and chain suffix |

**Related Commands**
- [`verifyfile`](#verifyfile) — Verify a file signature
- [`signmessage`](#signmessage) — Sign a text message instead
- [`signdata`](#signdata) — Advanced signing with VDXF keys, bound hashes, etc.

**Notes**
- The hash returned is **SHA256** (not SHA256D, despite using SHA256D internally for signing)
- The file must be accessible to the **daemon process**, not just the CLI
- Use `verifyfile` with the same file path and signature to verify
- Supports multisig accumulation via the `cursig` parameter
- The signature encodes the block height at signing time for identity state verification

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## signmessage

> **Category:** Identity | **Version:** v1.2.x+

Sign a message with the private key of a t-address or the authorities present in this wallet for a VerusID.

**Syntax**
```bash
verus signmessage "address or identity" "message" ("currentsig")
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | t-address or VerusID (e.g., `myid@`) to sign with |
| message | string | Yes | The message text to sign |
| cursig | string | No | Current partial signature (base64) for multisig IDs |

**Result**
```json
{
  "hash": "hexhash",
  "signature": "base64sig"
}
```

**Examples**

**Basic Usage**
```bash
## Command
./verus -testnet signmessage "myid@" "Hello from myid - testing signmessage for wiki docs"

## Actual Output (tested on VRSCTEST)
{
  "hash": "c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c",
  "signature": "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE"
}
```

**Verify the Signed Message**
```bash
./verus -testnet verifymessage "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "Hello from myid - testing signmessage for wiki docs"
## Output: true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signmessage","params":["myid@","Hello from myid"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Authentication** — prove you control a VerusID
- **Message attestation** — sign statements or agreements
- **Off-chain verification** — create portable proofs of identity

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Private key not available | Wallet doesn't hold signing keys | Import the private key or unlock wallet |
| Identity not found | Invalid identity name | Check spelling, include chain suffix if needed |
| Wallet locked | Wallet is encrypted and locked | Run `walletpassphrase` first |

**Related Commands**
- [`verifymessage`](#verifymessage) — Verify a signmessage signature
- [`verifyhash`](#verifyhash) — Verify using the hash directly
- [`signdata`](#signdata) — Advanced signing with VDXF keys, bound hashes, etc.
- [`signfile`](#signfile) — Sign a file instead of a message

**Notes**
- Returns a **v1 simple signature** — use `verifymessage` (not `verifysignature`) to verify
- The hash is SHA256 of the message
- For advanced features (VDXF keys, bound hashes, hash type selection), use `signdata` instead
- Supports multisig accumulation — pass partial signatures via `cursig`
- The signature embeds the block height at signing time

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## updateidentity

> **Category:** Identity | **Version:** v1.2.x+

Update an existing VerusID's properties on-chain (primary addresses, authorities, content, flags, etc.).

**Syntax**
```bash
verus updateidentity "jsonidentity" (returntx) (tokenupdate) (feeoffer) (sourceoffunds)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| jsonidentity | object | Yes | New definition of the identity (only changed fields needed alongside `name`) |
| returntx | bool | No | If true, return signed tx instead of broadcasting. Default: false |
| tokenupdate | bool | No | If true, use tokenized ID control token for authority. Default: false |
| feeoffer | value | No | Non-standard fee amount |
| sourceoffunds | string | No | Transparent or private address to source fees from |

**jsonidentity Fields**
```json
{
  "name": "identityname",
  "parent": "iAddress",
  "primaryaddresses": ["Raddress", ...],
  "minimumsignatures": 1,
  "revocationauthority": "nameorID",
  "recoveryauthority": "nameorID",
  "privateaddress": "zs-address",
  "contentmultimap": { ... },
  "flags": 0
}
```

**Result**
```
hexstring    (string) txid if returntx is false, or hex serialized transaction if returntx is true
```

**Examples**

**Basic Usage — Update a Root ID**
```bash
## Update myid@ identity (root-level ID on VRSCTEST)
## (replace i... with a VDXF key from your namespace, e.g. yourapp::data.v1.owner)
./verus -testnet updateidentity '{"name":"myid", "contentmultimap":{"i...":["226172694022"]}}'
```

**⚠️ CRITICAL: SubID Updates Require `parent` Field**
```bash
## WRONG — This will fail silently or update the wrong identity:
./verus -testnet updateidentity '{"name":"alice.yourapp"}'

## CORRECT — SubIDs MUST include the parent field:
./verus -testnet updateidentity '{"name":"alice", "parent":"i..."}'
```

> **⚠️ SubID Gotcha:** When updating a sub-identity (e.g., `alice.yourapp@`), you **must** include the `"parent"` field with the parent identity's i-address. Without it, the daemon will look for a root identity named "alice" instead of the subID "alice.yourapp". This is the most common source of errors with `updateidentity`.

**Token-Based Update**
```bash
## Use tokenized control token instead of key-based authority
./verus -testnet updateidentity '{"name":"myid"}' false true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"updateidentity","params":[{"name":"myid","contentmultimap":{"i...":["226172694022"]}}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Rotate keys** — change `primaryaddresses` to new addresses for security
- **Add content** — store data in `contentmultimap` using VDXF keys
- **Change authorities** — update `revocationauthority` or `recoveryauthority`
- **Enable multisig** — add multiple addresses and increase `minimumsignatures`
- **Set private address** — add a shielded `privateaddress` for receiving private funds

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Identity not found | Wrong name or missing `parent` for subIDs | Include `parent` i-address for sub-identities |
| Not authorized | Wallet doesn't hold signing keys for identity | Import the private key or use `tokenupdate` |
| Identity is revoked | Cannot update a revoked identity | Use `recoveridentity` first |
| Insufficient funds | Not enough for transaction fee | Fund the wallet or specify `sourceoffunds` |

**Related Commands**
- [`getidentity`](#getidentity) — View current identity state before/after update
- [`registeridentity`](#registeridentity) — Initial identity registration
- [`revokeidentity`](#revokeidentity) — Revoke an identity
- [`recoveridentity`](#recoveridentity) — Recover a revoked identity

**Notes**
- The `name` field is always required to identify which ID to update
- **SubIDs require the `parent` field** — this is the #1 gotcha
- Only fields you include will be changed; omitted fields retain their current values
- You must have signing authority (keys in wallet) or use `tokenupdate`
- `tokenupdate` allows holders of the tokenized ID control token to update without primary key authority, but cannot change revocation/recovery authorities
- Updates are on-chain transactions and require confirmation
- Use `returntx` to inspect the transaction before broadcasting in sensitive cases

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## verifyfile

> **Category:** Identity | **Version:** v1.2.x+

Verify a signed file against a VerusID or t-address.

**Syntax**
```bash
verus verifyfile "address or identity" "signature" "filepath/filename" (checklatest)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | t-address or VerusID that signed the file |
| signature | string | Yes | Base64-encoded signature from `signfile` |
| filename | string | Yes | Path to the file that was signed |
| checklatest | bool | No | If true, verify against latest identity state. Default: false (uses signing height) |

**Result**
```
true|false    (boolean) Whether the signature is valid
```

**Examples**

**Basic Usage**
```bash
## Command
./verus -testnet verifyfile "myid@" "Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186" "/tmp/verus_test_sign.txt"

## Actual Output (tested on VRSCTEST)
true
```

**Check Against Latest Identity State**
```bash
## Verify using the current identity keys (not the keys at signing time)
./verus -testnet verifyfile "myid@" "signature_base64" "/tmp/verus_test_sign.txt" true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifyfile","params":["myid@","Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186","/tmp/verus_test_sign.txt"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Software verification** — verify signed binaries or archives
- **Document integrity** — confirm a document hasn't been tampered with since signing
- **Audit compliance** — verify signed audit artifacts

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| false (returns false) | File modified, wrong signature, or wrong identity | Ensure file is unmodified and matches the signing identity |
| File not found | Invalid file path | Use absolute path accessible to the daemon |
| Identity not found | Invalid identity name | Check the identity name/address |

**Related Commands**
- [`signfile`](#signfile) — Sign a file (produces the signature to verify)
- [`verifymessage`](#verifymessage) — Verify a message signature
- [`verifyhash`](#verifyhash) — Verify using a hash directly

**Notes**
- The file must be accessible to the **daemon process**
- By default, verification checks against the identity state at the **signing height** (recorded in the signature)
- Use `checklatest: true` to verify against the **current** identity state — useful if keys have been rotated
- If the identity was updated (key rotation) after signing, default verification still succeeds (checks historical state)

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## verifyhash

> **Category:** Identity | **Version:** v1.2.x+

Verify a signature against a pre-computed hash and a VerusID or t-address.

**Syntax**
```bash
verus verifyhash "address or identity" "signature" "hexhash" (checklatest)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | t-address or VerusID that signed the data |
| signature | string | Yes | Base64-encoded signature from `signmessage` or `signfile` |
| hexhash | string | Yes | Hex-encoded hash of the original message or file |
| checklatest | bool | No | If true, verify against latest identity state. Default: false |

**Result**
```
true|false    (boolean) Whether the signature is valid
```

**Examples**

**Basic Usage**
```bash
## Using the hash from signmessage output to verify
./verus -testnet verifyhash "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c"

## Actual Output (tested on VRSCTEST)
true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifyhash","params":["myid@","Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE","c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Hash-only verification** — when you have the hash but not the original data
- **Remote verification** — verify without transmitting the original file/message
- **Cross-system verification** — verify signatures when only the hash was stored

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| false | Wrong hash, wrong signature, or wrong identity | Ensure hash matches what was originally signed |
| Invalid hex | Hash is not valid hex | Provide a valid 64-character hex hash |

**Related Commands**
- [`signmessage`](#signmessage) — Sign a message (output includes hash)
- [`signfile`](#signfile) — Sign a file (output includes hash)
- [`verifymessage`](#verifymessage) — Verify with the original message text
- [`verifyfile`](#verifyfile) — Verify with the original file
- [`verifysignature`](#verifysignature) — Advanced verification for `signdata` signatures

**Notes**
- The hash must be the **SHA256** hash as returned by `signmessage` or `signfile`
- This is useful when you've stored the hash separately from the original data
- Works with signatures from both `signmessage` and `signfile`
- For `signdata` (v2) signatures, use `verifysignature` with `datahash` instead

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## verifymessage

> **Category:** Identity | **Version:** v1.2.x+

Verify a signed message against a VerusID or t-address.

**Syntax**
```bash
verus verifymessage "address or identity" "signature" "message" (checklatest)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | t-address or VerusID that signed the message |
| signature | string | Yes | Base64-encoded signature from `signmessage` |
| message | string | Yes | The original message that was signed |
| checklatest | bool | No | If true, verify against latest identity state. Default: false |

**Result**
```
true|false    (boolean) Whether the signature is valid
```

**Examples**

**Basic Usage**
```bash
## Command
./verus -testnet verifymessage "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "Hello from myid - testing signmessage for wiki docs"

## Actual Output (tested on VRSCTEST)
true
```

**Verify with Latest Identity State**
```bash
## Check against current keys (useful after key rotation)
./verus -testnet verifymessage "myid@" "signature_base64" "message" true
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifymessage","params":["myid@","Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE","Hello from myid - testing signmessage for wiki docs"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Authentication proof** — verify someone controls a VerusID
- **Message integrity** — confirm a message hasn't been altered
- **Off-chain verification** — verify VerusID signatures in external systems

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| false | Message modified, wrong signature, or wrong identity | Ensure exact message text matches what was signed |
| Identity not found | Invalid identity name | Check spelling and format |

**Related Commands**
- [`signmessage`](#signmessage) — Sign a message (produces the signature to verify)
- [`verifyhash`](#verifyhash) — Verify using the hash instead of the message
- [`verifyfile`](#verifyfile) — Verify a file signature
- [`verifysignature`](#verifysignature) — Advanced verification for `signdata` signatures

**Notes**
- The message must match **exactly** — including whitespace and case
- Use this for signatures produced by `signmessage`. For `signdata` signatures, use `verifysignature`
- By default, checks against the identity state at the **signing height** (embedded in signature)
- `checklatest: true` verifies against current identity keys — will fail if keys were rotated after signing

**Tested On**
- VRSCTEST block height: 926957
- Verus version: 2000753

---

## verifysignature

> **Category:** Identity | **Version:** v1.2.x+

Verify a signature produced by `signdata`, supporting advanced features like VDXF keys, bound hashes, and hash type selection.

**Syntax**
```bash
verus verifysignature '{"address":"id@", "signature":"base64sig", ...}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Yes | VerusID or t-address that signed the data |
| signature | string | Yes | Base64-encoded signature to verify |
| message | string | No* | Original message text |
| filename | string | No* | File path that was signed |
| messagehex | string | No* | Hex-encoded data |
| messagebase64 | string | No* | Base64-encoded data |
| datahash | string | No* | Pre-computed hash (use hash from `signdata` output) |
| prefixstring | string | No | Extra string used during signing (must match) |
| vdxfkeys | array | No | VDXF key i-addresses bound during signing |
| vdxfkeynames | array | No | VDXF key names bound during signing |
| boundhashes | array | No | Hex hashes bound during signing |
| hashtype | string | No | Hash type used: `sha256`, `sha256D`, `blake2b`, `keccak256` |
| checklatest | bool | No | If true, verify against latest identity state. Default: false |

*One data parameter is required.

**Result**
```json
{
  "signaturestatus": "verified",
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "hashtype": "sha256",
  "hash": "hexhash",
  "height": 926958,
  "signatureheight": 926957,
  "signature": "base64sig"
}
```

**Examples**

**Verify Using datahash (Recommended for signdata signatures)**
```bash
## Use the "hash" field from signdata output as "datahash"
./verus -testnet verifysignature '{"address":"myid@", "datahash":"ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae", "signature":"AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="}'

## Actual Output (tested on VRSCTEST)
{
  "signaturestatus": "verified",
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "hashtype": "sha256",
  "hash": "ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae",
  "height": 926958,
  "signatureheight": 926957,
  "signature": "AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="
}
```

**⚠️ Important: Message-Based Verification with signdata**
```bash
## This will NOT work — signdata v2 signatures include system context in the hash:
./verus -testnet verifysignature '{"address":"myid@", "message":"test123", "signature":"..."}'
## Result: signaturestatus: "invalid"

## Instead, use the "hash" from signdata output as "datahash":
./verus -testnet verifysignature '{"address":"myid@", "datahash":"hash_from_signdata", "signature":"..."}'
## Result: signaturestatus: "verified"
```

**RPC (curl)**
```bash
curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifysignature","params":[{"address":"myid@","datahash":"ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae","signature":"AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Verify signdata signatures** — the counterpart to `signdata`
- **VDXF-bound verification** — verify signatures bound to specific VDXF data types
- **Cross-system verification** — verify with just the hash when original data isn't available

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| signaturestatus: "invalid" | Hash mismatch or wrong parameters | Use `datahash` from `signdata` output, not the original message |
| Identity not found | Invalid identity | Check name/address |
| Missing signature | No signature provided | Include the `signature` field |

**Related Commands**
- [`signdata`](#signdata) — Sign data (produces signatures verified by this command)
- [`verifymessage`](#verifymessage) — Verify simple `signmessage` signatures
- [`verifyhash`](#verifyhash) — Simple hash verification for `signmessage`/`signfile`

**Notes**
- **Critical:** `signdata` produces v2 signatures that include system context in the hash. Passing the original `message` to `verifysignature` will compute a different hash and return "invalid". Always use the `datahash` (the `hash` field from `signdata` output) for verification.
- Returns rich JSON with `signaturestatus` ("verified" or "invalid") instead of simple true/false
- Includes `height` (current block) and `signatureheight` (block at signing time)
- For simple `signmessage`/`signfile` signatures, use `verifymessage`/`verifyfile`/`verifyhash` instead

**Tested On**
- VRSCTEST block height: 926958
- Verus version: 2000753

--- PAGE: command-reference/marketplace.md ---

---
label: Marketplace
icon: terminal
---


# Marketplace Commands


---

## closeoffers

> **Category:** Marketplace | **Version:** v1.2.x+

Closes all listed offers if they are still valid and belong to this wallet. Always closes expired offers, even if no parameters are given.

**Syntax**

```bash
closeoffers ('["txid1","txid2",...]') (transparentorprivatefundsdestination) (privatefundsdestination)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `offerids` | array | No | Array of hex transaction IDs of offers to close. If omitted, closes all expired offers. |
| 2 | `transparentorprivatefundsdestination` | string | No | Transparent or private address for closing funds |
| 3 | `privatefundsdestination` | string | No | Private (Sapling) address for native funds only |

**Result**

Returns `null` on success.

**Examples**

**Close all expired offers**

```bash
verus -testnet closeoffers
```

**Close specific offers**

```bash
verus -testnet closeoffers '["1a6d5dd71172c02c825984c77b0ffe2c1234af8823a13be8576f2309eca38ce7"]'
```

**Close offers with specific fund destination**

```bash
verus -testnet closeoffers '["txid1"]' "RMyTransparentAddress"
```

**Close with separate private fund destination**

```bash
verus -testnet closeoffers '["txid1"]' "RTransparentAddr" "zs1privateaddr..."
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Offer not found | Transaction ID doesn't reference a valid offer |
| Not your offer | Offer doesn't belong to the current wallet |

**Related Commands**

- [`makeoffer`](#makeoffer) — Create an offer
- [`listopenoffers`](#listopenoffers) — List wallet's open offers
- [`getoffers`](#getoffers) — List offers for a currency/identity
- [`takeoffer`](#takeoffer) — Accept an offer

**Notes**

- **Always run periodically** to reclaim funds locked in expired offers.
- When called with no arguments, automatically closes all expired offers in the wallet.
- Funds can be directed to both transparent and private (Sapling) addresses.
- The separate `privatefundsdestination` is for native currency only; other assets go to the first destination.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## getoffers

> **Category:** Marketplace | **Version:** v1.2.x+

Returns all open offers for a specific currency or identity.

**Syntax**

```bash
getoffers "currencyorid" (iscurrency) (withtx)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `currencyorid` | string | Yes | Currency or identity to check for offers (both sale and purchase) |
| 2 | `iscurrency` | bool | No | Default `false`. If `false`, looks for ID offers; if `true`, currency offers |
| 3 | `withtx` | bool | No | Default `false`. If `true`, returns serialized hex of the exchange transaction for signing |

**Result**

Returns all available offers for or in the indicated currency or ID, organized by offer type.

**Examples**

**Get currency offers for VRSCTEST**

```bash
verus -testnet getoffers "VRSCTEST" true
```

**Result:**

```json
{
  "currency_iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq_for_ids": [
    {
      "identityid": "iNZzqYdmfCPCcVSTBjbPT8Q7rqeFohxATu",
      "price": 1.50000000,
      "offer": {
        "offer": {
          "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 1.50000000
        },
        "accept": {
          "name": "kneipe",
          "identityid": "iNZzqYdmfCPCcVSTBjbPT8Q7rqeFohxATu",
          "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
          "original": 1
        },
        "blockexpiry": 999999,
        "txid": "1a6d5dd71172c02c825984c77b0ffe2c1234af8823a13be8576f2309eca38ce7"
      }
    },
    {
      "identityid": "iJJ7Ge6eyaqHq7F62kf7vEDYgo1mdtBd4S",
      "price": 10.00000000,
      "offer": {
        "offer": {
          "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 10.00000000
        },
        "accept": {
          "name": "i made this for you",
          "identityid": "iJJ7Ge6eyaqHq7F62kf7vEDYgo1mdtBd4S",
          "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
          "original": 1
        },
        "blockexpiry": 40000000,
        "txid": "832a488e1ea5282825e44e1c016c2b110f31d840abeb191ee8f0e4f0bba8f59e"
      }
    }
  ]
}
```

> The result shows VRSCTEST currency being offered to purchase VerusID identities like "kneipe" and "i made this for you".

**Get identity offers (default)**

```bash
verus -testnet getoffers "someid@" false
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Identity specified as source is not valid` | Invalid identity name or ID when `iscurrency=false` |
| Invalid currency | Currency name or ID not recognized when `iscurrency=true` |

**Related Commands**

- [`makeoffer`](#makeoffer) — Create an offer
- [`takeoffer`](#takeoffer) — Accept an offer
- [`listopenoffers`](#listopenoffers) — List wallet's open offers
- [`closeoffers`](#closeoffers) — Close/cancel offers

**Notes**

- Results are organized by offer direction (e.g., `currency_X_for_ids` shows currency offers wanting to buy identities).
- The `blockexpiry` field shows when each offer expires.
- Use `withtx=true` to get the raw transaction hex needed for `takeoffer` with the `tx` parameter.
- The `price` field shows the amount being offered.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## listopenoffers

> **Category:** Marketplace | **Version:** v1.2.x+

Shows offers outstanding in the current wallet.

**Syntax**

```bash
listopenoffers (unexpired) (expired)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `unexpired` | bool | No | Default `true`. List offers that are not yet expired |
| 2 | `expired` | bool | No | Default `true`. List offers that have expired |

**Result**

Returns all open offers belonging to this wallet, both unexpired and expired (based on filters).

**Examples**

**List all wallet offers**

```bash
verus -testnet listopenoffers
```

**Result (wallet with no offers):**

*(No output — the daemon returns empty/whitespace with no JSON when there are no offers. This is a daemon quirk; there is no empty array or object returned.)*

**List only unexpired offers**

```bash
verus -testnet listopenoffers true false
```

**List only expired offers**

```bash
verus -testnet listopenoffers false true
```

**Common Errors**

No specific errors — returns empty if no offers exist.

**Related Commands**

- [`makeoffer`](#makeoffer) — Create an offer
- [`getoffers`](#getoffers) — List offers for a specific currency/identity
- [`closeoffers`](#closeoffers) — Close/cancel open offers
- [`takeoffer`](#takeoffer) — Accept an offer

**Notes**

- Only shows offers created by the current wallet.
- Use `getoffers` to see all offers on the network for a specific asset.
- Expired offers should be closed with `closeoffers` to reclaim funds.
- By default both unexpired and expired offers are shown.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## makeoffer

> **Category:** Marketplace | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Creates a fully decentralized, on-chain atomic swap offer for any blockchain asset including currencies, NFTs, identities, and contractual agreements.

**Syntax**

```bash
makeoffer fromaddress '{"changeaddress":"addr","expiryheight":n,"offer":{...},"for":{...}}' (returntx) (feeamount)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `fromaddress` | string | Yes | VerusID or wildcard address (`"*"`, `"R*"`, `"i*"`) to send funds from |
| 2 | `offerparams` | object | Yes | Offer parameters (see below) |
| 3 | `returntx` | bool | No | Default `false`. If `true`, returns unsigned hex transaction instead of posting |
| 4 | `feeamount` | number | No | Default `0.0001`. Custom fee amount |

**Offer parameters object**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `changeaddress` | string | Yes | Change destination for constructing transactions |
| `expiryheight` | int | No | Block height at which offer expires. Default: current + 20 blocks (~20 min) |
| `offer` | object | Yes | What you're offering — currency amount or identity |
| `for` | object | Yes | What you want in return — currency amount or identity definition |

**Offer/For as currency**

```json
{"currency": "currencynameorid", "amount": 10.0}
```

**Offer/For as identity**

```json
{"identity": "idnameoriaddress"}
```

**For as new identity (auction/purchase)**

```json
{"name": "identityname", "parent": "parentid", "primaryaddresses": ["R-address"], "minimumsignatures": 1}
```

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `txid` | string | Transaction ID on success (when `returntx` is false) |
| `hex` | string | Serialized partial transaction (when `returntx` is true) |

**Examples**

**Offer 10 VRSCTEST for an identity**

```bash
verus -testnet makeoffer "*" '{"changeaddress":"RChangeAddr","expiryheight":927100,"offer":{"currency":"VRSCTEST","amount":10},"for":{"name":"targetid","parent":"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq","primaryaddresses":["RPrimaryAddr"],"minimumsignatures":1}}'
```

**Offer an identity for VRSCTEST**

```bash
verus -testnet makeoffer "i*" '{"changeaddress":"RChangeAddr","offer":{"identity":"myid@"},"for":{"address":"RReceiverAddr","currency":"VRSCTEST","amount":5}}'
```

**Get unsigned transaction (for review)**

```bash
verus -testnet makeoffer "*" '{"changeaddress":"RChangeAddr","offer":{"currency":"VRSCTEST","amount":1},"for":{"currency":"Bridge.vETH","amount":0.01}}' true
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Insufficient funds | Wallet doesn't have enough of the offered asset |
| Invalid identity | Specified identity doesn't exist or isn't controlled by wallet |
| Invalid currency | Currency name or ID not recognized |
| Invalid change address | Change address is not valid |

**Related Commands**

- [`takeoffer`](#takeoffer) — Accept an existing offer
- [`getoffers`](#getoffers) — List offers for a currency or identity
- [`listopenoffers`](#listopenoffers) — List wallet's open offers
- [`closeoffers`](#closeoffers) — Close/cancel open offers

**Notes**

- Offers are **fully on-chain** and **atomic** — either both sides complete or neither does.
- Can swap any combination: currency↔currency, currency↔identity, identity↔identity.
- The `expiryheight` defaults to ~20 blocks (~20 minutes). Set higher for longer-lasting offers.
- Can be used as bids in on-chain auctions.
- Sources and destinations can be any valid transparent address capable of holding the specific asset.
- Wildcards: `"*"` = any address, `"R*"` = transparent only, `"i*"` = identity addresses only.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — would create real on-chain offers

---

## takeoffer

> **Category:** Marketplace | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Accepts a swap offer on the blockchain, creates and posts the completing transaction.

**Syntax**

```bash
takeoffer fromaddress '{"txid":"txid","changeaddress":"addr","deliver":{...},"accept":{...}}' (returntx) (feeamount)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `fromaddress` | string | Yes | Sapling, VerusID, or wildcard address (`"*"`, `"R*"`, `"i*"`) to send funds/fees from |
| 2 | `offerparams` | object | Yes | Offer acceptance parameters (see below) |
| 3 | `returntx` | bool | No | Default `false`. If `true`, returns hex transaction instead of posting |
| 4 | `feeamount` | number | No | Custom fee amount instead of default miner's fee |

**Offer acceptance object**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `txid` | string | Conditional | Transaction ID of the offer to accept (use this OR `tx`) |
| `tx` | string | Conditional | Hex transaction to complete (use this OR `txid`) |
| `changeaddress` | string | Yes | Change destination address |
| `deliver` | object | Yes | What you're delivering — identity name/address OR `{"currency":"id","amount":n}` |
| `accept` | object | Yes | What you're accepting — `{"address":"id","currency":"id","amount":n}` OR identity definition |
| `feeamount` | number | No | Specific fee amount |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `txid` | string | Transaction ID (when `returntx` is false) |
| `hextx` | string | Hex serialized transaction (when `returntx` is true) |

**Examples**

**Accept an offer by txid**

```bash
verus -testnet takeoffer "*" '{"txid":"1a6d5dd71172c02c825984c77b0ffe2c1234af8823a13be8576f2309eca38ce7","changeaddress":"RChangeAddr","deliver":{"currency":"VRSCTEST","amount":1.5},"accept":{"address":"RMyAddr","currency":"VRSCTEST","amount":0}}'
```

**Accept an identity offer**

```bash
verus -testnet takeoffer "i*" '{"txid":"offertxid","changeaddress":"RChangeAddr","deliver":"myid@","accept":{"address":"RMyAddr","currency":"VRSCTEST","amount":10}}'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Insufficient funds | Wallet can't afford the swap |
| Offer expired | The offer's expiry height has passed |
| Invalid offer txid | Transaction ID doesn't reference a valid offer |

**Related Commands**

- [`makeoffer`](#makeoffer) — Create an offer
- [`getoffers`](#getoffers) — List available offers
- [`listopenoffers`](#listopenoffers) — List wallet's open offers
- [`closeoffers`](#closeoffers) — Close/cancel offers

**Notes**

- The swap is **atomic** — both sides complete in a single transaction or neither does.
- You can use either `txid` (to reference an on-chain offer) or `tx` (hex transaction for offline signing workflows).
- Sapling (shielded) addresses can be used as the funding source.
- The `deliver` field specifies what you give; `accept` specifies what you receive and where.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — would execute real on-chain swaps

--- PAGE: command-reference/mining.md ---

---
label: Mining
icon: terminal
---


# Mining Commands


---

## getblocksubsidy

> **Category:** Mining | **Version:** v1.2.14+

Returns block subsidy reward for a given block height, accounting for mining slow start and founders reward.

**Syntax**
```bash
verus getblocksubsidy [height]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| height | numeric | No | The block height. Defaults to current chain height if omitted. |

**Result**
```json
{
  "miner": x.xxx    // (numeric) The mining reward amount
}
```

**Examples**

**Basic Usage**
```bash
## Current block reward
./verus -testnet getblocksubsidy

## Actual Output (tested on VRSCTEST)
{
  "miner": 6.00000000
}
```

**Specific Height**
```bash
./verus -testnet getblocksubsidy 1000

## Actual Output (tested on VRSCTEST)
{
  "miner": 6.00000000
}
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getblocksubsidy","params":[1000]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Check current block reward for profitability calculations
- Verify reward schedule at different block heights
- Monitor halving/reduction schedule

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Block height out of range | Height exceeds current chain height significantly | Use a valid block height |

**Related Commands**
- [`getmininginfo`](#getmininginfo) — comprehensive mining status
- [`getblocktemplate`](#getblocktemplate) — get data for constructing blocks

**Notes**
- VRSCTEST block reward is 6 VRSCTEST per block
- The help text references "KMD" in the result description — this is inherited from the Komodo codebase; the actual currency is VRSC/VRSCTEST

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getblocktemplate

> **Category:** Mining | **Version:** v1.2.14+

Returns data needed to construct a block to work on. Supports BIP 0022 template and proposal modes.

**Syntax**
```bash
verus getblocktemplate ["jsonrequestobject"]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| jsonrequestobject | string (JSON) | No | Request object with optional `mode`, `miningdistribution`, and `capabilities` fields |

**Request Object Structure**
```json
{
  "mode": "template",
  "miningdistribution": {
    "recipientaddress": relativeweight,
    ...
  },
  "capabilities": ["longpoll", "coinbasetxn", "coinbasevalue", "proposal", "serverlist", "workid"]
}
```

**Result**
```json
{
  "version": n,                        // (numeric) Block version
  "previousblockhash": "xxxx",         // (string) Hash of current highest block
  "finalsaplingroothash": "xxxx",      // (string) Final sapling root hash
  "transactions": [],                  // (array) Non-coinbase transactions to include
  "coinbasetxn": { ... },              // (object) Coinbase transaction info
  "target": "xxxx",                    // (string) Hash target
  "mintime": xxx,                      // (numeric) Min timestamp for next block (epoch seconds)
  "mutable": ["time", "transactions", "prevblock"],
  "noncerange": "00000000ffffffff",
  "sigoplimit": n,                     // (numeric) Sigop limit
  "sizelimit": n,                      // (numeric) Block size limit
  "curtime": ttt,                      // (numeric) Current timestamp (epoch seconds)
  "bits": "xxx",                       // (string) Compressed target
  "height": n                          // (numeric) Next block height
}
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getblocktemplate

## Actual Output (tested on VRSCTEST, truncated)
{
  "capabilities": ["proposal"],
  "version": 65540,
  "previousblockhash": "31e25bb6f23bf71424b2c39142329d8dc2985ecdc28ca05247a734bf6e2b2a39",
  "finalsaplingroothash": "1486454686b458641e8cd2465320bf3693926007ba7c4a6497b51d5a1c4723bd",
  "transactions": [],
  "coinbasetxn": {
    "data": "0400008085202f8901...",
    "hash": "1c82e90c9b8871cecc416d6a330b681c354100ea9fcd183a392e50c68189cd76",
    "depends": [],
    "fee": 0,
    "sigops": 1,
    "coinbasevalue": 600000000,
    "required": true
  },
  "target": "00000004792b0000000000000000000000000000000000000000000000000000",
  "mintime": 1770447385,
  "mutable": ["time", "transactions", "prevblock"],
  "noncerange": "00000000ffffffff",
  "sigoplimit": 60000,
  "sizelimit": 2000000,
  "curtime": 1770448016,
  "bits": "1d04792b",
  "height": 926962
}
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getblocktemplate","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Building custom mining software
- Pool software block construction
- Submitting block proposals for validation

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Node is not connected | No peers connected | Ensure node is synced and has peer connections |
| Node is downloading blocks | Blockchain not fully synced | Wait for sync to complete |

**Related Commands**
- [`submitblock`](#submitblock) — submit a constructed block
- [`submitmergedblock`](#submitmergedblock) — submit a merged-mined block
- [`getblocksubsidy`](#getblocksubsidy) — check block reward
- [`getmininginfo`](#getmininginfo) — current mining status

**Notes**
- The `coinbasevalue` is in satoshis (600000000 = 6.0 VRSCTEST)
- The `miningdistribution` parameter allows splitting coinbase reward across multiple addresses
- See [BIP 0022](https://en.bitcoin.it/wiki/BIP_0022) for full specification
- The `solution` field in the response contains the Equihash solution template

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getlocalsolps

> **Category:** Mining | **Version:** v1.2.14+

Returns the average local solutions per second since this node was started. Same info shown on the metrics screen.

**Syntax**
```bash
verus getlocalsolps
```

**Parameters**
None.

**Result**
```
xxx.xxxxx     (numeric) Solutions per second average
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getlocalsolps

## Actual Output (tested on VRSCTEST)
0
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getlocalsolps","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Monitor local mining performance
- Verify mining hardware is working
- Compare local rate to network rate

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Returns 0 | Mining/staking not active | Enable with `setgenerate true` |

**Related Commands**
- [`getnetworksolps`](#getnetworksolps) — network-wide solution rate
- [`getmininginfo`](#getmininginfo) — comprehensive mining status
- [`setgenerate`](generating.md#setgenerate) — enable/disable mining

**Notes**
- Returns 0 when mining is not active
- This is a local metric only — it reflects this node's hashrate, not the network

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getminingdistribution

> **Category:** Mining | **Version:** v1.2.14+

Retrieves the current mining reward distribution configuration.

**Syntax**
```bash
verus getminingdistribution
```

**Parameters**
None.

**Result**
Returns `null` if not set. If set:
```json
{
  "uniquedestination1": value,    // (string: number) destination address and relative weight
  "uniquedestination2": value,
  ...
}
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getminingdistribution

## Actual Output (tested on VRSCTEST) — no distribution set
(empty/null response)
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getminingdistribution","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Check current reward split before mining
- Verify distribution was set correctly after using `setminingdistribution`
- Audit mining reward destinations

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty/null result | No distribution configured | Use `setminingdistribution` to configure |

**Related Commands**
- [`setminingdistribution`](#setminingdistribution) — set the mining reward distribution
- [`getblocktemplate`](#getblocktemplate) — also accepts `miningdistribution` parameter
- [`getmininginfo`](#getmininginfo) — general mining status

**Notes**
- When no distribution is set, all rewards go to the default mining address
- The values are relative weights, not absolute amounts (e.g., `{"addr1": 0.5, "addr2": 0.5}` splits 50/50)

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getmininginfo

> **Category:** Mining | **Version:** v1.2.14+

Returns a JSON object containing mining-related information including block count, difficulty, staking supply, and generation status.

**Syntax**
```bash
verus getmininginfo
```

**Parameters**
None.

**Result**
```json
{
  "blocks": nnn,                // (numeric) Current block height
  "currentblocksize": nnn,      // (numeric) Last block size
  "currentblocktx": nnn,        // (numeric) Last block transaction count
  "averageblockfees": xxx.xxx,  // (numeric) Avg block fees over past 100 blocks
  "difficulty": xxx.xxx,        // (numeric) Current difficulty
  "stakingsupply": xxx.xxx,     // (numeric) Estimated total staking supply
  "errors": "...",              // (string) Current errors
  "generate": true|false,       // (boolean) Mining/generation on or off
  "genproclimit": n,            // (numeric) Processor limit (-1 = no generation)
  "localhashps": xxx.xxx,        // (numeric) Local hash rate (actual field name; help says `localsolps`)
  "networkhashps": x,            // (numeric) Estimated network hash rate (actual field name; help says `networksolps`)
  "pooledtx": n,                // (numeric) Mempool size
  "testnet": true|false,        // (boolean) Testnet flag
  "chain": "xxxx",             // (string) Network name (main, test, regtest)
  "staking": true|false,        // (boolean) Staking active
  "numthreads": n,              // (numeric) CPU threads mining
  "mergemining": n,             // (numeric) Number of merge-mined chains
  "mergeminedchains": []        // (optional, array) Merge-mined chain names
}
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getmininginfo

## Actual Output (tested on VRSCTEST)
{
  "blocks": 926961,
  "currentblocksize": 0,
  "currentblocktx": 0,
  "averageblockfees": 0.09729953,
  "difficulty": 56478309.28295863,
  "stakingsupply": 31566038.74104909,
  "errors": "",
  "genproclimit": 0,
  "localhashps": 0,
  "networkhashps": 16857317,
  "pooledtx": 0,
  "testnet": true,
  "chain": "main",
  "generate": false,
  "staking": false,
  "numthreads": 0,
  "mergemining": 0
}
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getmininginfo","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Monitor mining/staking status
- Check network difficulty and hashrate
- Verify staking supply and mempool state
- Confirm merge mining configuration

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| None typical | This command rarely errors | — |

**Related Commands**
- [`getgenerate`](generating.md#getgenerate) — focused generate/staking status
- [`setgenerate`](generating.md#setgenerate) — enable/disable mining/staking
- [`getnetworksolps`](#getnetworksolps) — detailed network hashrate
- [`getlocalsolps`](#getlocalsolps) — local solution rate

**Notes**
- The `chain` field shows "main" even on testnet — this refers to the chain type within VRSCTEST
- `localhashps` and `networkhashps` in actual output differ slightly from help text field names (`localsolps`/`networksolps`)
- `stakingsupply` shows the estimated total coins available for staking across the network
- `averageblockfees` is useful for estimating mining profitability beyond the base block reward

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getnetworkhashps

> **Category:** Mining | **Version:** v1.2.14+

**DEPRECATED** — Use [`getnetworksolps`](#getnetworksolps) instead. Kept for backwards compatibility.

Returns the estimated network solutions per second based on the last n blocks.

**Syntax**
```bash
verus getnetworkhashps [blocks] [height]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| blocks | numeric | No | Number of blocks to average over. Default: 120. Use -1 for difficulty averaging window. |
| height | numeric | No | Estimate at the time of this block height. Default: -1 (current). |

**Result**
```
x    (numeric) Estimated solutions per second
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getnetworkhashps

## Actual Output (tested on VRSCTEST)
16857317
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getnetworkhashps","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| None typical | — | — |

**Related Commands**
- [`getnetworksolps`](#getnetworksolps) — preferred replacement
- [`getlocalsolps`](#getlocalsolps) — local solution rate

**Notes**
- Identical functionality to `getnetworksolps` — use that instead
- Kept only for backward compatibility with older mining software

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## getnetworksolps

> **Category:** Mining | **Version:** v1.2.14+

Returns the estimated network solutions per second based on the last n blocks.

**Syntax**
```bash
verus getnetworksolps [blocks] [height]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| blocks | numeric | No | Number of blocks to average over. Default: 120. Use -1 for difficulty averaging window. |
| height | numeric | No | Estimate at the time of this block height. Default: -1 (current). |

**Result**
```
x    (numeric) Estimated solutions per second
```

**Examples**

**Basic Usage**
```bash
./verus -testnet getnetworksolps

## Actual Output (tested on VRSCTEST)
16857317
```

**At a Specific Height**
```bash
./verus -testnet getnetworksolps 120 900000

## Actual Output (tested on VRSCTEST)
24731593
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getnetworksolps","params":[120,900000]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Monitor network hashrate trends
- Compare current vs historical network power
- Estimate mining difficulty changes

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| None typical | — | — |

**Related Commands**
- [`getlocalsolps`](#getlocalsolps) — local node solution rate
- [`getmininginfo`](#getmininginfo) — includes network hashrate
- [`getnetworkhashps`](#getnetworkhashps) — deprecated alias

**Notes**
- This is the preferred command over the deprecated `getnetworkhashps`
- Using `-1` for blocks averages over the difficulty averaging window for a more stable estimate
- Network hashrate dropped from ~24.7M Sol/s at block 900,000 to ~16.9M Sol/s at block 926,961 on VRSCTEST

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## prioritisetransaction

> **Category:** Mining | **Version:** v1.2.14+

Accepts a transaction into mined blocks at a higher (or lower) priority. Adjusts the apparent priority and fee for block selection without changing the actual transaction.

**Syntax**
```bash
verus prioritisetransaction "txid" priority_delta fee_delta
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| txid | string | Yes | The transaction id |
| priority_delta | numeric | Yes | Priority to add/subtract. Priority = coinage × value_in_satoshis / txsize |
| fee_delta | numeric | Yes | Fee value in satoshis to add (or subtract if negative). Not actually paid — only affects selection algorithm. |

**Result**
```
true    (boolean) Returns true on success
```

**Examples**

**Basic Usage**
```bash
## Boost a transaction's priority in the mempool
./verus -testnet prioritisetransaction "txid_here" 0.0 10000
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"prioritisetransaction","params":["txid_here",0.0,10000]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Miners prioritizing their own transactions
- Pool operators boosting specific transactions
- Deprioritizing spam transactions (negative fee_delta)

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Invalid or non-wallet transaction id | txid not in mempool or invalid | Provide a valid txid currently in the mempool |

**Related Commands**
- [`getmininginfo`](#getmininginfo) — check mempool size (`pooledtx`)
- [`getblocktemplate`](#getblocktemplate) — see which transactions are in the template

**Notes**
- This only affects the local node's block construction — it doesn't broadcast any changes
- The fee adjustment is virtual; the actual transaction fee is unchanged on-chain
- Effects persist until the transaction is mined or leaves the mempool
- Requires a valid txid in the mempool to test; documented from help output

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## setminingdistribution

> **Category:** Mining | **Version:** v1.2.14+

Sets multiple mining output addresses with relative weights for distributing block rewards.

**Syntax**
```bash
verus setminingdistribution '{"address1":weight1, "address2":weight2}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| jsonminingdistribution | object | Yes | JSON object with destination addresses as keys and relative weights as values |

Each entry:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| uniquedestination | number | Yes (at least 1) | Valid destination address with relative weight value |

**Result**
```
null on success, exception otherwise
```

**Examples**

**Basic Usage**
```bash
## Split rewards 50/50 between two addresses
./verus -testnet setminingdistribution '{"RAddress1":0.5, "RAddress2":0.5}'
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setminingdistribution","params":[{"RAddress1":0.5,"RAddress2":0.5}]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Split mining rewards across multiple wallets
- Direct a portion of rewards to a specific identity or address
- Pool operators distributing rewards

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Invalid address | Destination address is not valid | Use valid R-addresses or VerusIDs |
| Exception on invalid JSON | Malformed JSON input | Ensure proper JSON formatting with quotes |

**Related Commands**
- [`getminingdistribution`](#getminingdistribution) — check current distribution
- [`getblocktemplate`](#getblocktemplate) — also accepts `miningdistribution` in request
- [`setgenerate`](generating.md#setgenerate) — enable mining/staking

**Notes**
- Values are relative weights, not percentages — `{"a":1, "b":1}` is equivalent to `{"a":0.5, "b":0.5}`
- The distribution applies to all future blocks mined by this node
- Use `getminingdistribution` to verify the setting was applied
- Pass an empty object or call without parameters to clear the distribution

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## submitblock

> **Category:** Mining | **Version:** v1.2.14+

Attempts to submit a new block to the network. See [BIP 0022](https://en.bitcoin.it/wiki/BIP_0022) for full specification.

**Syntax**
```bash
verus submitblock "hexdata" ["jsonparametersobject"]
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| hexdata | string | Yes | The hex-encoded block data to submit |
| jsonparametersobject | string (JSON) | No | Optional parameters (currently ignored except `workid`) |

**Optional Parameters Object**
```json
{
  "workid": "id"    // (string) If server provided a workid, it MUST be included
}
```

**Result**
Returns a string indicating the result:
| Value | Meaning |
|-------|---------|
| `"duplicate"` | Node already has a valid copy of this block |
| `"duplicate-invalid"` | Node has the block but it is invalid |
| `"duplicate-inconclusive"` | Node has the block but hasn't validated it |
| `"inconclusive"` | Node hasn't validated; may not be on best chain |
| `"rejected"` | Block was rejected as invalid |
| *(empty/null)* | Block accepted successfully |

**Examples**

**Basic Usage**
```bash
## Submit a mined block (hex data from mining software)
./verus -testnet submitblock "0400000..."
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"submitblock","params":["hexdata_here"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Mining pool software submitting solved blocks
- Custom mining implementations
- Testing block proposals

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `"rejected"` | Invalid block data or doesn't meet target | Verify block construction and PoW solution |
| `"duplicate"` | Block already known | Block was already submitted or received from network |

**Related Commands**
- [`getblocktemplate`](#getblocktemplate) — get data to construct a block
- [`submitmergedblock`](#submitmergedblock) — submit merged-mined blocks
- [`getblocksubsidy`](#getblocksubsidy) — check expected reward

**Notes**
- Requires a fully constructed and solved block in hex format
- The `jsonparametersobject` is currently ignored by the implementation
- Successful submission returns null/empty — any string response indicates a problem
- Documented from help output; requires actual mined block data to test

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

---

## submitmergedblock

> **Category:** Mining (Multichain) | **Version:** v1.2.14+

Attempts to submit one or more new blocks to one or more networks. Supports Verus and PBaaS merge-mined chains. If the block hash meets targets of other chains added with `addmergedblock`, it will be submitted to those chains as well.

**Syntax**
```bash
verus submitmergedblock "hexdata"
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| hexdata | string | Yes | The hex-encoded block data to submit, including embedded headers of PBaaS merge-mined chains |
| jsonparametersobject | object | No | Additional JSON parameters for block submission |

**Result**
On rejection:
```json
{ "rejected": "reject reason" }
```

On acceptance (this chain + PBaaS):
```json
{ "blockhash": "hex", "accepted": true, "pbaas_submissions": { "ChainName": "chainID_hex", ... } }
```

On acceptance (PBaaS only):
```json
{ "blockhash": "hex", "accepted": "pbaas", "pbaas_submissions": { "ChainName": "chainID_hex", ... } }
```

**Examples**

**Basic Usage**
```bash
./verus -testnet submitmergedblock "0400000..."
```

**RPC (curl)**
```bash
curl --user user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"submitmergedblock","params":["hexdata_here"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- Mining pools supporting PBaaS merge mining
- Submitting blocks valid for multiple chains simultaneously
- PBaaS chain operators running merge-mined networks

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `rejected` | Block doesn't meet target or is invalid | Check block construction and embedded headers |

**Related Commands**
- [`submitblock`](#submitblock) — submit a single-chain block
- [`getblocktemplate`](#getblocktemplate) — get block construction data
- [`getmininginfo`](#getmininginfo) — check `mergemining` and `mergeminedchains` fields

**Notes**
- The block must contain valid embedded headers for any PBaaS chains being merge-mined
- Use `addmergedblock` to configure which PBaaS chains to merge mine
- The `pbaas_submissions` field shows which additional chains accepted the block
- A block can be accepted by PBaaS chains even if rejected by the main chain
- Documented from help output; requires actual mined block data to test

**Tested On**
- VRSCTEST block height: 926961
- Verus version: v1.2.14-2

--- PAGE: command-reference/multichain.md ---

---
label: Multichain
icon: terminal
---

# Multichain Commands

> **Placeholder convention:** Examples in this reference use `yourapp` as an example token/currency name, `i...` to mark a placeholder i-address (substitute the real one from `getcurrency`), and `<block-height>` for a placeholder block number. Commands shown were tested on VRSCTEST — only these project-specific values have been genericized.

---

## addmergedblock

> **Category:** Multichain | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Adds a fully prepared block and its header to the current merge mining queue.

**Syntax**

```bash
addmergedblock "hexdata" ( "jsonparametersobject" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `hexdata` | string | Yes | The hex-encoded, complete, unsolved block data to add. `nTime` and `nSolution` are replaced. |
| 2 | `name` | string | Yes | Chain name symbol |
| 3 | `rpchost` | string | Yes | Host address for RPC connection |
| 4 | `rpcport` | int | Yes | Port address for RPC connection |
| 5 | `userpass` | string | Yes | Credentials for login to RPC |

Parameters 2–5 are passed as a JSON object. Default action when adding would exceed available space is to replace the choice with the least ROI if the new block provides more.

**Result**

| Value | Description |
|-------|-------------|
| `"deserialize-invalid"` | Block could not be deserialized and was rejected as invalid |
| `"blocksfull"` | Block did not exceed others in estimated ROI, and there was no room for an additional merge mined block |
| `{"nextblocktime": n}` | Block has invalid time and must be remade with time returned |

**Examples**

```bash
verus addmergedblock "hexdata" '{"currencyid":"hexstring","rpchost":"127.0.0.1","rpcport":portnum}'
```

```bash
curl --user myusername --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"addmergedblock","params":["hexdata",{"currencyid":"hexstring","rpchost":"127.0.0.1","rpcport":portnum,"estimatedroi":0.5}]}' -H 'content-type:text/plain;' http://127.0.0.1:27486/
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `deserialize-invalid` | Invalid or corrupted hex block data |
| `blocksfull` | Merge mining slots full and new block has lower ROI |

**Related Commands**

- [`getblocktemplate`](mining.md#getblocktemplate) — Get block template for mining
- [`submitblock`](mining.md#submitblock) — Submit a mined block

**Notes**

- Used for merge mining operations where multiple chains share proof-of-work.
- The daemon manages merge mining slots and automatically compares ROI to decide which blocks to keep.
- `nTime` and `nSolution` fields in the provided block data are replaced by the daemon.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — requires active merge mining setup

---

## clearrawmempool

> **Category:** Multichain | **Version:** v1.2.x+

Clears the mempool of all transactions or specific cache types on this node.

**Syntax**

```bash
clearrawmempool '["cachetype1","cachetype2",...]'
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `cachetypes` | array | No | Array of cache types to clear. If omitted, **all** caches are cleared. |

**Valid cache types**

| Type | Description |
|------|-------------|
| `evidence` | Notarization evidence transactions |
| `reservetransfer` | Reserve transfer transactions |
| `offermap` | Marketplace offer map cache |
| `chaintransfer` | Cross-chain transfer transactions |
| `priorconversion` | Prior conversion transactions |

**Result**

No output on success.

**Examples**

**Clear all mempool caches**

```bash
verus -testnet clearrawmempool
```

*(No output on success)*

**Clear only specific cache types**

```bash
verus -testnet clearrawmempool '["offermap","evidence"]'
```

**Clear only offer-related cache**

```bash
verus -testnet clearrawmempool '["offermap"]'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Parse error | Invalid JSON array format |

**Related Commands**

- [`getrawmempool`](blockchain.md#getrawmempool) — View current mempool contents
- [`getmempoolinfo`](blockchain.md#getmempoolinfo) — Get mempool statistics

**Notes**

- **Use with caution** — clearing the mempool removes unconfirmed transactions from this node's view.
- Selective clearing using cache type filters is safer than clearing everything.
- Useful for troubleshooting stuck transactions or clearing stale cross-chain data.
- Only affects the local node's mempool; does not affect other nodes on the network.
- Transactions will be re-received from peers if they are still valid.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## definecurrency

> **Category:** Multichain | **Version:** v1.2.x+

Defines a new blockchain currency, either as an independent PBaaS blockchain or as a token on this blockchain.

**Syntax**
```bash
verus definecurrency '{"name":"coinortokenname",...}' ('{"name":"fractionalgatewayname",...}') ...
```

**Parameters**
The primary argument is a JSON object with the currency definition:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | ✅ | Name of existing identity (must have no active currency) |
| options | int | optional | Bitfield: 0x1=FRACTIONAL, 0x2=IDRESTRICTED, 0x4=IDSTAKING, 0x8=IDREFERRALS, 0x10=IDREFERRALSREQUIRED, 0x20=TOKEN, 0x100=IS_PBAAS_CHAIN |
| idregistrationfees | number | ✅ | Price of an identity in native currency |
| idreferrallevels | int | ✅ | How many levels ID referrals go back in reward |
| notarizationreward | number | ✅ | Default VRSC notarization reward total for first billing period |
| proofprotocol | int | optional | 1=PROOF_PBAASMMR (decentralized), 2=PROOF_CHAINID (centralized mint/burn), 3=PROOF_ETHNOTARIZATION |
| notarizationprotocol | int | optional | 1=PBAASMMR, 2=CHAINID (sole notary), 3=ETHNOTARIZATION |
| startblock | int | optional | Block that must be notarized into block 1 of PBaaS chain |
| endblock | int | optional | Block after which currency life ends (0 = no end) |
| currencies | array | optional | Reserve currencies backing this chain |
| weights | array | optional | Weight of each reserve currency (for fractional) |
| conversions | array | optional | Pre-launch conversion ratio overrides |
| minpreconversion | array | optional | Minimum in each currency to launch |
| maxpreconversion | array | optional | Maximum in each currency allowed |
| initialcontributions | array | optional | Initial contribution in each currency |
| initialsupply | number | required (fractional) | Supply after conversion of contributions |
| prelaunchdiscount | number | optional | Discount on final price at launch for <100% fractional |
| prelaunchcarveout | number | optional | % of pre-converted amounts from reserves |
| preallocations | array | optional | `[{"identity":amount},...]` pre-allocated amounts |
| gatewayconvertername | string | optional | Name of co-launched gateway converter (PBaaS only) |
| blocktime | int | optional | Target seconds between blocks (default: 60) |
| powaveragingwindow | int | optional | Blocks to look back for DAA (default: 45) |
| notarizationperiod | int | optional | Min blocks between notarizations (default: 10 min) |
| eras | array | optional | Up to 3 eras: `[{"reward":n,"decay":n,"halving":n,"eraend":n},...]` |
| nodes | array | optional | Up to 5 nodes: `[{"networkaddress":"ip:port","nodeidentity":"name@"},...]` |
| notaries | array | optional | List of notary identities for PBaaS chains: `["identity",...]` |
| minnotariesconfirm | int | optional | Minimum unique notary signatures required for auto-notarization |
| expiryheight | int | optional | Block height at which the definition transaction expires (default: current height + 20) |

**Result**
```json
{
  "txid": "transactionid",
  "tx": "json",
  "hex": "data"
}
```

**Examples**

**Simple Token Definition (reference: yourapp)**
The `yourapp` token on VRSCTEST was defined with these characteristics:
```bash
## Example definition (DO NOT run — creates real currency):
./verus -testnet definecurrency '{
  "name": "yourapp",
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"myid@": 200}]
}'

## Result: yourapp token created at block <block-height>
## currencyid: i...
## proofprotocol 2 = centralized (ID holder can mint/burn)
## options 32 (0x20) = TOKEN
```

**Fractional Basket Currency (reference: VRSC-USD)**
```bash
## Example fractional currency with two reserves:
./verus -testnet definecurrency '{
  "name": "VRSC-USD",
  "options": 33,
  "currencies": ["VRSCTEST", "USD"],
  "weights": [0.5, 0.5],
  "initialsupply": 2000000,
  "initialcontributions": [200000, 1000000],
  "idregistrationfees": 5,
  "idreferrallevels": 3
}'
## options 33 = FRACTIONAL (1) + TOKEN (32)
```

**PBaaS Chain Definition**
```bash
./verus -testnet definecurrency '{
  "name": "mypbaas",
  "options": 264,
  "idregistrationfees": 100,
  "idreferrallevels": 3,
  "notarizationreward": 0.0001,
  "eras": [{"reward": 600000000, "halving": 1051924, "eraend": 0}],
  "nodes": [{"networkaddress": "1.2.3.4:12345", "nodeidentity": "mynode@"}],
  "blocktime": 60
}'
## options 264 = IS_PBAAS_CHAIN (256) + IDREFERRALS (8)
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"definecurrency","params":[{"name":"tokenname","options":32,"proofprotocol":2,"idregistrationfees":0.01,"idreferrallevels":0}]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Create a simple token** with `options: 32` (TOKEN) and `proofprotocol: 2` (centralized)
- **Create a fractional basket** with `options: 33` (FRACTIONAL+TOKEN), reserve currencies, and weights
- **Launch a PBaaS chain** with `options: 264` (IS_PBAAS_CHAIN+IDREFERRALS), eras, and nodes
- **Create a gateway converter** for cross-chain bridges using `gatewayconvertername`

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Identity not found` | Named identity doesn't exist | Create the identity first with `registernamecommitment` + `registeridentity` |
| `Currency already defined` | Identity already has an active currency | Use a different identity name |
| `Insufficient funds` | Not enough VRSC to pay definition fee | Ensure identity has funds (200 VRSCTEST for currency, 10000 for PBaaS) |
| `Invalid currency definition` | Missing required fields or invalid options | Check all required fields are present |

**Related Commands**
- [getcurrency](#getcurrency) — verify the currency after creation
- [listcurrencies](#listcurrencies) — list all currencies
- [sendcurrency](#sendcurrency) — send/convert with the new currency
- [getlaunchinfo](#getlaunchinfo) — get launch details

**Notes**
- The identity named after the currency must exist and have no active currency
- All launch funds must be available from the identity with the same name
- Once activated, the symbol cannot be reused (even if identity is transferred/revoked) unless `endblock` is set and reached
- Currency registration fee on VRSCTEST: 200 VRSCTEST; PBaaS chain: 10,000 VRSCTEST
- Options are additive bitfields: combine with OR (e.g., FRACTIONAL + TOKEN = 0x1 + 0x20 = 0x21 = 33)

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## estimateconversion

> **Category:** Multichain | **Version:** v1.2.x+

Estimates conversion from one currency to another, accounting for pending conversions, fees, and slippage.

**Syntax**
```bash
verus estimateconversion '{"currency":"name","convertto":"name","amount":n}'
verus estimateconversion '[array of conversions]'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currency | string | ✅ | Source currency name (defaults to native) |
| amount | number | ✅ | Amount to convert, denominated in source currency |
| convertto | string | optional | Destination currency (must be reserve↔fractional pair) |
| preconvert | bool | optional | Convert at market price before currency launch (default: false) |
| via | string | optional | Common fractional basket to route through when converting between two reserves |

Multiple conversions can be passed as an array for batch estimation through one basket.

**Result**
```json
{
  "inputcurrencyid": "i-address",
  "netinputamount": 99.95,
  "outputcurrencyid": "i-address",
  "estimatedcurrencyout": 568.27,
  "estimatedcurrencystate": { ... }
}
```

**Examples**

**Convert VRSCTEST → VRSC-USD (reserve → fractional)**
```bash
./verus -testnet estimateconversion '{"currency":"VRSCTEST","convertto":"VRSC-USD","amount":10}'
## Actual Output (tested on VRSCTEST)
{
  "inputcurrencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "netinputamount": 9.99750000,
  "outputcurrencyid": "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD",
  "estimatedcurrencyout": 53.30897428,
  "estimatedcurrencystate": {
    "flags": 49,
    "currencyid": "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD",
    "reservecurrencies": [
      {
        "currencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
        "weight": 0.50000000,
        "reserves": 189111.88850281,
        "priceinreserve": 0.18754127
      },
      {
        "currencyid": "iFawzbS99RqGs7J2TNxME1TmmayBGuRkA2",
        "weight": 0.50000000,
        "reserves": 1075715.34495600,
        "priceinreserve": 1.06678128
      }
    ],
    "supply": 2016749.56340113
  }
}
```

**Convert Between Reserves via Basket (VRSCTEST → USD via VRSC-USD)**
```bash
./verus -testnet estimateconversion '{"currency":"VRSCTEST","convertto":"USD","via":"VRSC-USD","amount":100}'
## Actual Output (tested on VRSCTEST)
{
  "inputcurrencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "netinputamount": 99.95000000,
  "outputcurrencyid": "iFawzbS99RqGs7J2TNxME1TmmayBGuRkA2",
  "estimatedcurrencyout": 568.27012650
}
## 100 VRSCTEST ≈ 568.27 USD (via VRSC-USD basket)
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"estimateconversion","params":[{"currency":"VRSCTEST","convertto":"VRSC-USD","amount":10}]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Price quotes** before executing `sendcurrency` with conversion
- **Slippage estimation** — compare `netinputamount` vs `amount` to see fees
- **Cross-reserve pricing** — use `via` to estimate reserve-to-reserve swaps
- **Batch estimation** — pass array to estimate multiple conversions simultaneously

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Source currency cannot be converted to destination` | No conversion path exists | Use `getcurrencyconverters` to find valid pairs; use `via` for reserve↔reserve |
| `Currency not found` | Invalid currency name | Check spelling with `getcurrency` |

**Related Commands**
- [sendcurrency](#sendcurrency) — execute the conversion
- [getcurrencyconverters](#getcurrencyconverters) — find available conversion pairs
- [getcurrencystate](#getcurrencystate) — check current reserve ratios

**Notes**
- Fees are ~0.025% conversion fee + 0.02% network fee (visible in `netinputamount` vs `amount`)
- The `estimatedcurrencystate` shows the projected state AFTER the conversion
- For reserve↔reserve swaps, you MUST use `via` to specify the fractional basket
- Direct conversion only works: reserve→fractional or fractional→reserve
- Results are estimates; actual output depends on other pending conversions in the same block

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getbestproofroot

> **Category:** Multichain | **Version:** v1.2.x+

Determines and returns the index of the best (most recent, valid, qualified) proof root from a list of proof roots.

**Syntax**

```bash
getbestproofroot '{"proofroots":[...],"lastconfirmed":n}'
```

**Parameters**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `proofroots` | array | Yes (may be empty) | Ordered array of proof root objects |
| `proofroots[].version` | int | Yes | Version of proof root data structure |
| `proofroots[].type` | int | Yes | Type of proof root (chain or system specific) |
| `proofroots[].systemid` | string | Yes | System the proof root is for |
| `proofroots[].height` | int | Yes | Height of this proof root |
| `proofroots[].stateroot` | string | Yes | Merkle tree root for the specified block |
| `proofroots[].blockhash` | string | Yes | Hash identifier for the specified block |
| `proofroots[].power` | string | Yes | Work/stake power for most-work rule |
| `currencies` | array | No | Currency IDs to query for currency states |
| `lastconfirmed` | int | Yes | Index into proof root array indicating last confirmed root |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `bestindex` | int | Index of best unconfirmed proof root, or -1 |
| `latestproofroot` | object | Latest valid proof root of chain |
| `laststableproofroot` | object | Tip minus BLOCK_MATURITY or last notarized tip |
| `lastconfirmedproofroot` | object | Last confirmed proof root |
| `currencystates` | object | Currency states of target and published bridges |

**Examples**

**Query with empty proof roots**

```bash
verus -testnet getbestproofroot '{"proofroots":[],"lastconfirmed":0}'
```

**Result:**

```json
{
  "latestproofroot": {
    "version": 1,
    "type": 1,
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "height": 926990,
    "stateroot": "b55b3de4f19296085120a0b167f04bd1e2483bc65208ac0545b872fd449521e2",
    "blockhash": "000000018e6991fb0d5b595b7b7b8e4cb7f04a0b8b6704ecd0f063221d534bb1",
    "power": "000000000000007cdf67b5b86988e351000000000000000000070a048434c248"
  },
  "laststableproofroot": {
    "version": 1,
    "type": 1,
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "height": 926970,
    "stateroot": "f2ad072f1f36c4ae2aa00b99e3b813465c2a753aa5db7bcb74f4fee61185d3f6",
    "blockhash": "000000025a722d4b3383c75413efe07e8f29c5990e7b53fee65794a41adbece2",
    "power": "000000000000007cdecdbd910883658e000000000000000000070a000e8a52fb"
  }
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Parse error | Invalid JSON format in the proof roots parameter |

**Related Commands**

- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data for a currency
- [`getnotarizationproofs`](#getnotarizationproofs) — Get notarization proofs
- [`submitacceptednotarization`](#submitacceptednotarization) — Submit a notarization

**Notes**

- Core part of the Verus cross-chain notarization protocol.
- The `laststableproofroot` is typically at `tip - BLOCK_MATURITY` (20 blocks) behind the latest.
- Proof roots contain the Merkle state root, block hash, and cumulative chain power for validation.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## getcurrency

> **Category:** Multichain | **Version:** v1.2.x+

Returns the complete definition for any given currency or chain registered on the blockchain.

**Syntax**
```bash
verus getcurrency "currencyname"
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currencyname | string | optional | Name or i-address of the currency. Omit for current chain. Also accepts `hex:currencyidhex` format. |

**Result**
Returns a JSON object containing the full currency definition including version, options, parent chain, system ID, launch parameters, eras, nodes, and the last confirmed currency state.

Key fields:
- `currencyid` — the i-address identifier
- `options` — bitfield (0x20=TOKEN, 0x1=FRACTIONAL, 0x100=IS_PBAAS_CHAIN, etc.)
- `systemid` — system this currency runs on
- `startblock` / `endblock` — lifecycle boundaries
- `bestcurrencystate` / `lastconfirmedcurrencystate` — current supply, emissions, fees

**Examples**

**Basic Usage — Token**
```bash
./verus -testnet getcurrency yourapp
## Actual Output (tested on VRSCTEST)
{
  "version": 1,
  "options": 32,
  "name": "yourapp",
  "currencyid": "i...",
  "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "notarizationprotocol": 1,
  "proofprotocol": 2,
  "launchsystemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "startblock": <block-height>,
  "endblock": 0,
  "idregistrationfees": 0.01000000,
  "idreferrallevels": 0,
  "idimportfees": 0.02000000,
  "fullyqualifiedname": "yourapp",
  "bestcurrencystate": {
    "flags": 48,
    "version": 1,
    "currencyid": "i...",
    "initialsupply": 0.00000000,
    "emitted": 10.00000000,
    "supply": 210.00000000
  }
}
```

**Basic Usage — Native Chain**
```bash
./verus -testnet getcurrency VRSCTEST
## Returns full VRSCTEST chain definition including:
## - eras with reward/halving schedule
## - node list for network connectivity
## - registration fee structure
## - preallocations
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getcurrency","params":["yourapp"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Check if a currency exists** before interacting with it
- **Get the i-address** (`currencyid`) for a currency by name
- **Inspect supply** via `bestcurrencystate.supply`
- **Check launch status** via `startblock` and currency state flags
- **Find reserve currencies** in fractional baskets via `currencies` and `weights` arrays

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Currency not found` | Name/ID doesn't exist on this chain | Check spelling, ensure currency was defined on this chain |
| No output | Daemon not synced | Wait for sync to complete |

**Related Commands**
- [listcurrencies](#listcurrencies) — list all registered currencies
- [getcurrencystate](#getcurrencystate) — get current state at specific height
- [definecurrency](#definecurrency) — define a new currency
- [getlaunchinfo](#getlaunchinfo) — get launch details

**Notes**
- `options: 32` (0x20) = TOKEN, `options: 33` (0x21) = FRACTIONAL TOKEN
- `proofprotocol: 2` means centralized (ID controller can mint/burn)
- The `bestcurrencystate` shows the latest state; `lastconfirmedcurrencystate` shows last notarized state

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getcurrencyconverters

> **Category:** Multichain | **Version:** v1.2.x+

Retrieves all fractional currencies that have the specified currencies as reserves, enabling conversion between them.

**Syntax**
```bash
verus getcurrencyconverters "currency1" "currency2" ...
verus getcurrencyconverters '{"convertto":"name","fromcurrency":"name","amount":n,"slippage":0.01}'
```

**Parameters**

**Simple Form**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currency1, currency2, ... | string(s) | ✅ | One or more currency names — returns fractional currencies that hold ALL listed as reserves |

**Advanced Form (JSON object)**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| convertto | string | ✅ | Target/destination currency |
| fromcurrency | string/array | ✅ | Source currency name, or array of objects: `[{"currency":"name","targetprice":n}]` or `[{"currency":"name","targetprice":[n,...]}]` |
| amount | number | optional | Amount of destination currency needed |
| slippage | number | optional | Max slippage (0.01 = 1%, max 50000000 = 50%) |

**Result**
Array of currency objects with their current state and last conversion amounts.

**Examples**

**Find Converters for VRSCTEST**
```bash
./verus -testnet getcurrencyconverters VRSCTEST
## Actual Output (tested on VRSCTEST, truncated)
[
  {
    "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD": {
      "version": 1,
      "options": 33,
      "name": "VRSC-USD",
      "currencyid": "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD",
      "currencies": [
        "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
        "iFawzbS99RqGs7J2TNxME1TmmayBGuRkA2"
      ],
      "weights": [0.50000000, 0.50000000],
      "initialsupply": 2000000.00000000,
      "initialcontributions": [200000.00000000, 1000000.00000000]
    },
    "fullyqualifiedname": "VRSC-USD",
    "height": 924671,
    ...
  },
  ...
]
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getcurrencyconverters","params":["VRSCTEST"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Discover trading pairs** — find all fractional baskets that hold a given currency
- **Build a DEX UI** — enumerate available conversion paths
- **Price discovery** — find converters with best rates for a target amount with slippage control

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty array `[]` | No fractional currencies hold the specified reserve(s) | Check currency names; only fractional baskets are returned |

**Related Commands**
- [estimateconversion](#estimateconversion) — estimate a specific conversion
- [sendcurrency](#sendcurrency) — execute a conversion
- [getcurrency](#getcurrency) — get details on a specific converter

**Notes**
- Only returns **fractional** currencies (baskets with reserves)
- Simple tokens like `yourapp` won't appear (they have no reserves)
- The advanced JSON form with `slippage` filters converters that can satisfy the trade within tolerance

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getcurrencystate

> **Category:** Multichain | **Version:** v1.2.x+

Returns the currency state(s) on the blockchain for any specified currency at a given height or range, optionally with market/volume data.

**Syntax**
```bash
verus getcurrencystate "currencynameorid" ("n") ("conversiondatacurrency")
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currencynameorid | string | ✅ | Name or i-address of currency |
| n | int/string | optional | Height or range: `"n"`, `"m,n"` (range), or `"m,n,o"` (range with step). Default: latest. |
| conversiondatacurrency | string | optional | If present, returns market data with volumes denominated in this currency |

**Result**
Array of objects, each containing `height`, `blocktime`, `currencystate`, and optionally `conversiondata` with OHLCV-style volume pairs.

**Examples**

**Basic Usage**
```bash
./verus -testnet getcurrencystate yourapp
## Actual Output (tested on VRSCTEST)
[
  {
    "height": 926963,
    "blocktime": 1770448221,
    "currencystate": {
      "flags": 48,
      "version": 1,
      "currencyid": "i...",
      "launchcurrencies": [],
      "initialsupply": 0.00000000,
      "emitted": 10.00000000,
      "supply": 210.00000000,
      "primarycurrencyfees": 0.00000000,
      "primarycurrencyconversionfees": 0.00000000,
      "primarycurrencyout": 10.00000000,
      "preconvertedout": 0.00000000
    }
  }
]
```

**At Specific Height**
```bash
./verus -testnet getcurrencystate yourapp <block-height>
## replace <block-height> with an actual block number
```

**Range with Step (for charting)**
```bash
./verus -testnet getcurrencystate "VRSC-USD" "926900,926963,10"
## Returns state every 10 blocks from 926900 to 926963
```

**With Market Data**
```bash
./verus -testnet getcurrencystate "VRSC-USD" "" "VRSCTEST"
## Returns conversion volume data denominated in VRSCTEST
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getcurrencystate","params":["yourapp"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Track supply over time** with height ranges
- **Build price charts** using `conversiondata` with OHLCV volume pairs
- **Monitor reserve ratios** for fractional currencies
- **Check fees collected** via `primarycurrencyfees` and `primarycurrencyconversionfees`

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Currency not found` | Invalid name/ID | Verify currency exists with `getcurrency` |
| Empty array `[]` | Height before currency existed | Use height >= currency's `startblock` |

**Related Commands**
- [getcurrency](#getcurrency) — full currency definition
- [getinitialcurrencystate](#getinitialcurrencystate) — state at launch
- [estimateconversion](#estimateconversion) — estimate conversion with current state

**Notes**
- For fractional currencies, the state includes `reservecurrencies` with weights, reserves, and prices
- The `flags` field indicates currency state: launched, prelaunch, refunding, etc.
- Using a range with step is efficient for building historical charts

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getcurrencytrust

> **Category:** Multichain | **Version:** v1.2.x+

Returns trust ratings for currencies in the wallet, controlling which currencies are synced/displayed.

**Syntax**
```bash
verus getcurrencytrust '["currencyid",...]'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currencyids | array | optional | Array of currency i-addresses to query. Omit or `[]` for all rated currencies. |

**Result**
```json
{
  "setratings": { "currencyid": JSONRatingObject, ... },
  "currencytrustmode": n
}
```

Trust modes:
- `0` = No restriction on sync (default)
- `1` = Only sync currencies rated as approved
- `2` = Sync all except those on block list

**Examples**

**Get All Trust Ratings**
```bash
./verus -testnet getcurrencytrust
## Actual Output (tested on VRSCTEST — no ratings set):
## (empty response — no trust ratings configured)
```

**Query Specific Currency**
```bash
./verus -testnet getcurrencytrust '["i..."]'
## Replace i... with the actual currencyid from getcurrency
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getcurrencytrust","params":[]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Check wallet filtering** — see which currencies are approved/blocked
- **Audit trust settings** before changing them with `setcurrencytrust`

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty response | No trust ratings configured | This is normal — default is trust mode 0 (no filtering) |

**Related Commands**
- [setcurrencytrust](#setcurrencytrust) — modify trust ratings
- [listcurrencies](#listcurrencies) — list all currencies

**Notes**
- Trust ratings are wallet-local settings, not on-chain
- Default mode 0 means all currencies are visible and spendable
- Useful for wallets that want to filter spam tokens

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getexports

> **Category:** Multichain | **Version:** v1.2.x+

Returns export transfers to the specified currency/chain within an optional block height range.

**Syntax**
```bash
verus getexports "chainname" (heightstart) (heightend)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| chainname | string | ✅ | Name or i-address of the destination currency/chain |
| heightstart | int | optional | Only return exports at or above this height (default: 0) |
| heightend | int | optional | Only return exports at or below this height (default: max) |

**Result**
Array of export objects containing height, txid, export info (source/destination systems, amounts, fees), partial transaction proof, and transfer details.

**Examples**

**Get Exports for yourapp**
```bash
./verus -testnet getexports yourapp
## Actual Output (tested on VRSCTEST, truncated)
[
  {
    "height": <block-height>,
    "txid": "62b74cbb9d2ed4050c1d59d09f69bda23cc0ca8de67343b8c1e6b17c961cd657",
    "txoutnum": 4,
    "exportinfo": {
      "version": 1,
      "flags": 65,
      "sourceheightstart": 0,
      "sourceheightend": <block-height>,
      "sourcesystemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "destinationsystemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "destinationcurrencyid": "i...",
      "totalamounts": {
        "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 100.00000000
      },
      "totalfees": {
        "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 100.00000000
      }
    },
    "transfers": []
  },
  ...
]
```

**Get Exports in Height Range**
```bash
./verus -testnet getexports VRSCTEST 926950 926963
## Returns exports to VRSCTEST within that block range
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getexports","params":["yourapp"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Track cross-chain transfers** leaving this chain
- **Monitor bridge activity** for specific currencies
- **Verify export completion** by checking transfer details
- **Audit currency launch** exports (initial funding)

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty array `[]` | No exports in the specified range | Broaden height range or check currency name |
| `Currency not found` | Invalid chain name | Verify with `getcurrency` |

**Related Commands**
- [getimports](#getimports) — get incoming imports
- [getpendingtransfers](#getpendingtransfers) — pending (not yet exported) transfers
- [sendcurrency](#sendcurrency) — create exports with `exportto`

**Notes**
- The first export for a currency is typically the launch/definition transaction
- `totalamounts` and `totalfees` show aggregate values for all transfers in that export batch
- Exports are batched — multiple transfers may be aggregated into a single export

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getimports

> **Category:** Multichain | **Version:** v1.2.x+

Returns all imports into a specific currency/chain, optionally filtered by block height range.

**Syntax**
```bash
verus getimports "chainname" (startheight) (endheight)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| chainname | string | optional | Name or i-address of the chain. Omit for current chain. |
| startheight | int | optional | Start height (default: 0) |
| endheight | int | optional | End height (default: 0 = latest) |

**Result**
Array of import objects containing import height, txid, import details (source system, amounts, token values), and the import notarization.

**Examples**

**Get All Imports for VRSCTEST**
```bash
./verus -testnet getimports VRSCTEST
## Actual Output (tested on VRSCTEST, first entry)
[
  {
    "importheight": 238,
    "importtxid": "0672a49165fd34fa387a4c497a93c7a3ccbfa093e136e136585695557f83a261",
    "importvout": 2,
    "import": {
      "version": 1,
      "flags": 15,
      "sourcesystemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "sourceheight": 1,
      "importcurrencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "numoutputs": 0
    },
    "importnotarization": {
      "version": 2,
      "isdefinition": true,
      "launchcleared": true,
      "launchconfirmed": true,
      "launchcomplete": true,
      ...
    }
  },
  ...
]
```

**Get Recent Imports**
```bash
./verus -testnet getimports VRSCTEST 926900 926963
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getimports","params":["VRSCTEST"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Track incoming cross-chain transfers**
- **Verify bridge imports** from external systems
- **Monitor currency launch imports** (initial conversions)
- **Debug cross-chain issues** by checking import notarizations

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty response | No imports in range, or currency has no imports | Broaden height range |
| `Currency not found` | Invalid chain name | Verify with `getcurrency` |

**Related Commands**
- [getexports](#getexports) — get outgoing exports
- [getpendingtransfers](#getpendingtransfers) — transfers awaiting export
- [sendcurrency](#sendcurrency) — send cross-chain (creates exports that become imports)

**Notes**
- The first import for VRSCTEST (height 238) is the chain's genesis/definition import
- Import notarizations contain launch state flags (`launchcleared`, `launchconfirmed`, `launchcomplete`)
- Can return very large result sets without height filtering on long-running chains

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getinitialcurrencystate

> **Category:** Multichain | **Version:** v1.2.x+

Returns the total amount of preconversions confirmed on the blockchain for a specified currency at launch time.

**Syntax**
```bash
verus getinitialcurrencystate "name"
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | ✅ | Name or chain ID of the currency |

**Result**
```json
{
  "flags": n,
  "version": 1,
  "currencyid": "i-address",
  "launchcurrencies": [],
  "initialsupply": 0.0,
  "emitted": 0.0,
  "supply": 0.0,
  "primarycurrencyfees": 0.0,
  "primarycurrencyconversionfees": 0.0,
  "primarycurrencyout": 0.0,
  "preconvertedout": 0.0
}
```

**Examples**

**Get Initial State for yourapp**
```bash
./verus -testnet getinitialcurrencystate yourapp
## Actual Output (tested on VRSCTEST)
{
  "flags": 26,
  "version": 1,
  "currencyid": "i...",
  "launchcurrencies": [],
  "initialsupply": 0.00000000,
  "emitted": 0.00000000,
  "supply": 0.00000000,
  "primarycurrencyfees": 0.00000000,
  "primarycurrencyconversionfees": 0.00000000,
  "primarycurrencyout": 0.00000000,
  "preconvertedout": 0.00000000
}
## flags 26 = prelaunch state flags
## supply 0 = no pre-conversions (tokens were pre-allocated, not pre-converted)
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getinitialcurrencystate","params":["yourapp"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Verify launch conditions** — check how much was pre-converted before launch
- **Audit initial supply** — confirm the starting supply matched expectations
- **Compare initial vs current** — use with `getcurrencystate` to see growth

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Currency not found` | Invalid name/ID | Verify with `getcurrency` |

**Related Commands**
- [getcurrencystate](#getcurrencystate) — current state (compare with initial)
- [getlaunchinfo](#getlaunchinfo) — full launch details with proofs
- [getcurrency](#getcurrency) — currency definition

**Notes**
- For simple tokens without pre-conversion, all values will be 0 (supply comes from preallocations)
- For fractional currencies, `launchcurrencies` will show reserve contributions
- The `flags` field encodes the launch state at the time of the snapshot
- Compare with current `getcurrencystate` to see how the currency has evolved since launch

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getlastimportfrom

> **Category:** Multichain | **Version:** v1.2.x+

Returns the last import from a specific originating system.

**Syntax**

```bash
getlastimportfrom "systemname"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `systemname` | string | Yes | Name or ID of the system to retrieve the last import from |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `lastimport` | object | Last import from the indicated system on this chain |
| `lastconfirmednotarization` | object | Last confirmed notarization of the indicated system on this chain |

**Examples**

**Query for a bridged system**

```bash
verus -testnet getlastimportfrom "VRSC"
```

**Result (when no bridge exists):**

```
error code: -8
error message: Invalid chain name or chain ID
```

> This error occurs because VRSC is not a bridged system on the VRSCTEST testnet. On mainnet with active bridges, this would return import and notarization data.

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid chain name or chain ID` | The specified system does not exist or is not a valid import source |

**Related Commands**

- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data for a currency
- [`submitimports`](#submitimports) — Submit imports from another system
- [`getimports`](#getimports) — Get imports for a currency

**Notes**

- Only works for systems that have an active bridge to the current chain.
- Returns both the last import transaction and the last confirmed notarization from that system.
- Useful for monitoring cross-chain import status and debugging bridge operations.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## getlaunchinfo

> **Category:** Multichain | **Version:** v1.2.x+

Returns the launch notarization data and partial transaction proof for a currency's launch.

**Syntax**
```bash
verus getlaunchinfo "currencyid"
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currencyid | string | ✅ | Hex-encoded ID or string name of the currency |

**Result**
```json
{
  "currencydefinition": {},
  "txid": "hexstr",
  "voutnum": n,
  "transactionproof": {},
  "launchnotarization": {},
  "notarynotarization": {}
}
```

**Examples**

**Get Launch Info for yourapp**
```bash
./verus -testnet getlaunchinfo yourapp
## Actual Output (tested on VRSCTEST):
## Error: "No valid export found"
## This is expected for simple tokens that launched without pre-conversion exports
```

**Get Launch Info for a PBaaS Chain or Fractional Currency**
```bash
./verus -testnet getlaunchinfo VRSC-USD
## Would return the full launch notarization for the VRSC-USD fractional basket
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getlaunchinfo","params":["VRSC-USD"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Verify currency launch** — get proof that a currency was properly launched
- **Cross-chain launch verification** — use the transaction proof for external validation
- **Audit launch parameters** — confirm the original currency definition at launch

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `No valid export found` | Currency launched without exports (e.g., simple tokens) or hasn't launched yet | Only currencies with pre-conversion/launch exports have launch info |
| `Currency not found` | Invalid name/ID | Check with `getcurrency` |

**Related Commands**
- [getinitialcurrencystate](#getinitialcurrencystate) — initial state at launch
- [getcurrency](#getcurrency) — current currency definition
- [definecurrency](#definecurrency) — how the currency was defined

**Notes**
- Simple tokens (like `yourapp`) that launch without pre-conversions may return "No valid export found"
- This command is primarily useful for PBaaS chains and fractional currencies with launch phases
- The `transactionproof` can be used for cross-chain verification of the launch

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getnotarizationdata

> **Category:** Multichain | **Version:** v1.2.x+

Returns the latest PBaaS notarization data for a specified currency.

**Syntax**

```bash
getnotarizationdata "currencynameorid" (getevidence) (separatecounterevidence)
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `currencynameorid` | string | Yes | Hex-encoded ID or string name to search for notarizations |
| 2 | `getevidence` | bool | No | If true, returns notarization evidence as well |
| 3 | `separatecounterevidence` | bool | No | If true, counter-evidence is processed and returned with proof roots |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `version` | int | Notarization protocol version |
| `notarizations` | array | Array of notarization objects |
| `forks` | array | Fork indices |
| `lastconfirmedheight` | int | Height of last confirmed notarization |
| `lastconfirmed` | int | Index of last confirmed notarization |
| `bestchain` | int | Index of best chain |

**Examples**

**Get notarization data for VRSCTEST**

```bash
verus -testnet getnotarizationdata "VRSCTEST"
```

**Result:**

```json
{
  "version": 1,
  "notarizations": [
    {
      "index": 0,
      "txid": "0000000000000000000000000000000000000000000000000000000000000000",
      "vout": -1,
      "notarization": {
        "version": 2,
        "launchconfirmed": true,
        "proposer": {
          "address": "i3UXS5QPRQGNRDDqVnyWTnmFCTHDbzmsYk",
          "type": 4
        },
        "currencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
        "notarizationheight": 926990,
        "currencystate": {
          "flags": 16,
          "version": 1,
          "currencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
          "initialsupply": 0.00000000,
          "emitted": 0.00000000,
          "supply": 0.00000000
        },
        "proofroots": [
          {
            "version": 1,
            "type": 1,
            "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
            "height": 926990,
            "stateroot": "b55b3de4f19296085120a0b167f04bd1e2483bc65208ac0545b872fd449521e2",
            "blockhash": "000000018e6991fb0d5b595b7b7b8e4cb7f04a0b8b6704ecd0f063221d534bb1",
            "power": "000000000000007cdf67b5b86988e351000000000000000000070a048434c248"
          }
        ]
      }
    }
  ],
  "forks": [[0]],
  "lastconfirmedheight": 926990,
  "lastconfirmed": 0,
  "bestchain": 0
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid currency or ID | The specified currency name or ID doesn't exist |

**Related Commands**

- [`getbestproofroot`](#getbestproofroot) — Get best proof root
- [`getnotarizationproofs`](#getnotarizationproofs) — Get notarization proofs
- [`submitacceptednotarization`](#submitacceptednotarization) — Submit a notarization

**Notes**

- For the native chain (VRSCTEST on testnet), this returns the current chain state as a self-notarization.
- For cross-chain currencies, this returns pending and confirmed notarizations from bridged systems.
- The `getevidence` flag adds cryptographic evidence supporting each notarization.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## getnotarizationproofs

> **Category:** Multichain | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Returns proofs for requested challenges to unconfirmed cross-chain notarizations.

**Syntax**

```bash
getnotarizationproofs '[challengerequests, ...]'
```

**Parameters**

Takes an array of challenge request objects. Two types are supported:

**Skip Challenge**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | `"vrsc::evidence.skipchallenge"` or `"iCwxpRL6h3YeCRtGjgQSsqoKdZCuM4Dxaf"` |
| `evidence` | object | Yes | CNotaryEvidence object |
| `entropyhash` | string | Yes | Hex entropy hash |
| `proveheight` | int | Yes | Height to prove |
| `atheight` | int | Yes | Height at which to prove |

**Primary Proof**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | `"vrsc::evidence.primaryproof"` or `"iKDesmiEkEjDG61nQSZJSGhWvC8x8xA578"` |
| `priornotarizationref` | object | Conditional | CUTXORef — either this or `priorroot` required |
| `priorroot` | object | Conditional | CProofRoot — either this or `priornotarizationref` required |
| `challengeroots` | array | No | Array of `{indexkey, proofroot}` objects |
| `evidence` | object | Yes | CNotaryEvidence object |
| `entropyhash` | string | Yes | Hex entropy hash |
| `confirmnotarization` | object | Conditional | New notarization — cannot combine with `confirmroot` |
| `confirmroot` | object | Conditional | CProofRoot — cannot combine with `confirmnotarization` |
| `fromheight` | int | Yes | Starting height |
| `toheight` | int | Yes | Ending height |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `evidence` | array | Array of CNotaryEvidence objects containing proofs for requested challenges |

**Examples**

```bash
verus -testnet getnotarizationproofs '[{"type":"iCwxpRL6h3YeCRtGjgQSsqoKdZCuM4Dxaf","evidence":{},"proveheight":100,"atheight":200}]'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Parse error | Invalid JSON challenge request format |
| Cannot have both `confirmnotarization` and `confirmroot` | Mutually exclusive fields |

**Related Commands**

- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data
- [`submitchallenges`](#submitchallenges) — Submit evidence challenges
- [`getbestproofroot`](#getbestproofroot) — Get best proof root

**Notes**

- Part of the Verus cross-chain consensus challenge/response protocol.
- Proofs can independently or in combination invalidate or force competing chains to provide more proofs.
- Skip challenges prove that blocks exist at certain heights; primary proofs provide full state proofs.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — requires active cross-chain notarization disputes

---

## getpendingtransfers

> **Category:** Multichain | **Version:** v1.2.x+

Returns all pending transfers for a particular chain that have not yet been aggregated into an export.

**Syntax**
```bash
verus getpendingtransfers "chainname"
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| chainname | string | optional | Name or i-address of the chain. Omit for current chain. |

**Result**
Array of pending transfer objects, or empty if no transfers are pending.

**Examples**

**Check Pending Transfers for VRSCTEST**
```bash
./verus -testnet getpendingtransfers VRSCTEST
## Actual Output (tested on VRSCTEST):
## (empty — no pending transfers at time of test)
```

**Check Pending Transfers for yourapp**
```bash
./verus -testnet getpendingtransfers yourapp
## (empty — no pending transfers)
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getpendingtransfers","params":["VRSCTEST"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Monitor cross-chain queue** — see transfers waiting to be exported
- **Debug stuck transfers** — check if a `sendcurrency` with `exportto` is queued
- **Pre-conversion monitoring** — track pending pre-launch conversions

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Currency not found` | Invalid chain name | Verify with `getcurrency` |

**Related Commands**
- [getexports](#getexports) — see completed exports
- [getimports](#getimports) — see completed imports
- [sendcurrency](#sendcurrency) — create transfers

**Notes**
- Pending transfers are temporary — they get batched into exports at the next block
- An empty result is normal when no cross-chain activity is in progress
- Transfers appear here briefly between `sendcurrency` and the next block that processes them

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getreservedeposits

> **Category:** Multichain | **Version:** v1.2.x+

Returns all reserve deposits under control of the specified currency or chain, showing the backing reserves.

**Syntax**
```bash
verus getreservedeposits "currencyname" (returnutxos)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| currencyname | string | ✅ | Full name or i-address of the controlling currency |
| returnutxos | bool | optional | If true, returns individual UTXOs with currency values (default: false) |

**Result**
```json
{
  "utxos": [...],
  "currency1_iaddress": value,
  "currency2_iaddress": value
}
```

**Examples**

**Get Reserve Deposits for VRSC-USD Basket**
```bash
./verus -testnet getreservedeposits VRSC-USD
## Actual Output (tested on VRSCTEST)
{
  "iFawzbS99RqGs7J2TNxME1TmmayBGuRkA2": 1075715.34495600,
  "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq": 189101.88975281
}
## Shows ~1.07M USD and ~189K VRSCTEST backing the VRSC-USD basket
```

**Get Deposits for VRSCTEST (no reserves)**
```bash
./verus -testnet getreservedeposits VRSCTEST
## Actual Output:
{}
## Empty — VRSCTEST is a native chain, not a fractional currency
```

**With UTXO Details**
```bash
./verus -testnet getreservedeposits VRSC-USD true
## Returns individual UTXOs that hold the reserve deposits
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getreservedeposits","params":["VRSC-USD"]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Verify basket backing** — confirm fractional currencies are fully backed by reserves
- **Audit reserve health** — compare reserves to supply for solvency checks
- **Track reserve changes** over time
- **UTXO analysis** — use `returnutxos: true` for detailed deposit accounting

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty `{}` | Currency has no reserves (native chain or simple token) | Only fractional currencies have reserve deposits |
| `Currency not found` | Invalid name/ID | Verify with `getcurrency` |

**Related Commands**
- [getcurrencystate](#getcurrencystate) — includes reserve amounts in currency state
- [getcurrency](#getcurrency) — see currency definition with reserve currencies and weights
- [getcurrencyconverters](#getcurrencyconverters) — find currencies with reserves

**Notes**
- Only fractional currencies (baskets) have reserve deposits
- Simple tokens (like `yourapp`) and native chains return empty `{}`
- Reserve deposits are held in special on-chain outputs controlled by the currency protocol
- The i-addresses in the result map to the reserve currency IDs (use `getcurrency` to resolve names)

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## getsaplingtree

> **Category:** Multichain | **Version:** v1.2.x+

Returns the entries for a light wallet Sapling tree state at a specified height or range.

**Syntax**

```bash
getsaplingtree "n"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `n` | string/int | No | Height or inclusive range. Formats: `"n"`, `"m,n"` (range), `"m,n,o"` (range with step). If omitted, returns latest state. |

**Result**

Array of objects:

| Field | Type | Description |
|-------|------|-------------|
| `network` | string | Currency ID of the network |
| `height` | int | Block height |
| `hash` | string | Block hash at this height |
| `time` | int | Block timestamp |
| `tree` | string | Hex-encoded Sapling commitment tree state |

**Examples**

**Get Sapling tree at specific height**

```bash
verus -testnet getsaplingtree "926990"
```

**Result:**

```json
[
  {
    "network": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "height": 926990,
    "hash": "000000018e6991fb0d5b595b7b7b8e4cb7f04a0b8b6704ecd0f063221d534bb1",
    "time": 1770449419,
    "tree": "0125e011918cd61ca18258b0bb583c7819db8b1baa9526dac97f0150224165d71b000901c9708ac265b695f0fb23c0fbf45d67231c7997e1c4f196b9f57e6ddad704b30a01a3b3a2f9f7e5138d69dbd99622ebb113f456d918e939d373abde9143a8c73f3501affbd0b08eab4485c9ff5700471153e8ca3dd729f2a2e764ee2f9df7a69cdf4f0000019423f71049e07cc2f720456034a962ff85b85c82e6251beb3aa4583daace38020001b891214ff69d3a6004d52ecbcb145a968d375d79834061d3586baaaf76faaf4a01d8b8e6065b6356e94a872598f8c7fed4cbf0dba06c0ee5943836b827a63f0139"
  }
]
```

**Get Sapling tree for a range with step**

```bash
verus -testnet getsaplingtree "926980,926990,5"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid height | Height exceeds current chain tip or is negative |

**Related Commands**

- [`getblock`](blockchain.md#getblock) — Get block data at a height
- [`getblockchaininfo`](blockchain.md#getblockchaininfo) — Get blockchain state info

**Notes**

- Essential for light wallet (SPV) synchronization of Sapling shielded transactions.
- The `tree` field contains the serialized Sapling note commitment tree, which light wallets need to validate and construct shielded transactions.
- Range queries with step are useful for building periodic checkpoints.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## listcurrencies

> **Category:** Multichain | **Version:** v1.2.x+

Returns definitions for all currencies registered on the blockchain, with optional filtering by launch state, system type, or converter status.

**Syntax**
```bash
verus listcurrencies ({"query"}) (startblock) (endblock)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | object | optional | Filter criteria (see below) |
| startblock | int | optional | Positional param after query object. Filters to currencies defined at or after this block height |
| endblock | int | optional | Positional param after startblock. Filters to currencies defined at or before this block height |

**Query Object**
| Name | Type | Description |
|------|------|-------------|
| launchstate | string | `"prelaunch"`, `"launched"`, `"refund"`, or `"complete"` |
| systemtype | string | `"local"`, `"imported"`, `"gateway"`, or `"pbaas"` |
| fromsystem | string | System name/ID to query currencies from (default: local chain) |
| converter | array | Only return fractional converters of listed currencies, e.g. `["VRSCTEST"]` |

**Result**
Array of currency objects, each containing `currencydefinition`, `bestheight`, `besttxid`, and `bestcurrencystate`.

**Examples**

**List All Currencies**
```bash
./verus -testnet listcurrencies
## Returns all currencies on VRSCTEST (can be very long)
## Example entry:
{
  "currencydefinition": {
    "name": "VRSC-USD",
    "currencyid": "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD",
    "options": 33,
    "currencies": ["iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq", "iFawzbS99RqGs7J2TNxME1TmmayBGuRkA2"],
    "weights": [0.50000000, 0.50000000],
    "initialsupply": 2000000.00000000,
    ...
  },
  "bestheight": 924671,
  "bestcurrencystate": { ... }
}
```

**List Only Launched Currencies**
```bash
./verus -testnet listcurrencies '{"launchstate":"launched"}'
```

**List Converters for VRSCTEST**
```bash
./verus -testnet listcurrencies '{"converter":["VRSCTEST"]}'
## Returns only fractional baskets that hold VRSCTEST as a reserve
```

**List PBaaS Chains Only**
```bash
./verus -testnet listcurrencies '{"systemtype":"pbaas"}'
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"listcurrencies","params":[]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Enumerate all tokens** on the network
- **Find active fractional baskets** for trading with `converter` filter
- **Monitor pre-launch currencies** with `launchstate: "prelaunch"`
- **Discover imported currencies** from other chains

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Empty array `[]` | No currencies match the filter | Broaden filter criteria or omit query |
| Timeout | Too many currencies to return | Use `startblock`/`endblock` to narrow range |

**Related Commands**
- [getcurrency](#getcurrency) — get details for a specific currency
- [getcurrencyconverters](#getcurrencyconverters) — find conversion pairs
- [getcurrencytrust](#getcurrencytrust) — check trust ratings

**Notes**
- Output can be very large on active networks; use filters to narrow results
- The `bestcurrencystate` in each result is equivalent to calling `getcurrencystate` for that currency
- `systemtype: "local"` returns currencies running on this chain; `"imported"` returns those from other systems

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## refundfailedlaunch

> **Category:** Multichain | **Version:** v1.2.x+

Refunds any funds sent to a chain if they are eligible for refund after a failed currency launch.

**Syntax**

```bash
refundfailedlaunch "currencyid"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `currencyid` | string | Yes | i-address or full chain name of the currency to refund contributions to |

**Result**

Returns transaction information for the refund on success. No specific result format documented.

**Examples**

**Attempt refund on a non-failed currency**

```bash
verus -testnet refundfailedlaunch "VRSCTEST"
```

**Result:**

```
error code: -8
error message: Cannot refund the specified chain
```

> This error is expected — VRSCTEST launched successfully and is not eligible for refund.

**Common Errors**

| Error | Cause |
|-------|-------|
| `Cannot refund the specified chain` | Currency launched successfully or doesn't exist |
| `Invalid currency` | Currency name or ID not recognized |

**Related Commands**

- [`definecurrency`](#definecurrency) — Define a new currency
- [`getcurrency`](#getcurrency) — Get currency information
- [`getcurrencystate`](#getcurrencystate) — Get current state of a currency

**Notes**

- Only works for currencies that failed to meet their minimum preconversion threshold before launch.
- Attempts to refund **all** transactions for **all** contributors, not just the caller.
- The wallet must have the ability to sign refund transactions for the relevant addresses.
- A currency launch fails when it doesn't reach its minimum required preconversions before the start block.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990

---

## sendcurrency

> **Category:** Multichain | **Version:** v1.2.x+

The most versatile command in Verus — sends, converts, bridges, mints, and burns currency in a single operation.

**Syntax**
```bash
verus sendcurrency "fromaddress" '[{"address":"dest","amount":n,...},...]' (minconfs) (feeamount) (returntxtemplate)
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| fromaddress | string | ✅ | Source address. Wildcards: `"*"` (any), `"R*"` (transparent only), `"i*"` (identity only) |
| outputs | array | ✅ | Array of output objects (see below) |
| minconfs | int | optional | Minimum confirmations for source UTXOs (default: 1) |
| feeamount | number | optional | Custom fee amount instead of default miner fee |
| returntxtemplate | bool | optional | If true, returns unsigned tx template instead of broadcasting |

**Output Object Fields**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | ✅ | Destination address, VerusID, or `name@chain` for cross-chain |
| amount | number | ✅ | Amount to send in source currency |
| currency | string | optional | Source currency (default: native chain currency) |
| convertto | string | optional | Currency to convert to (reserve↔fractional) |
| via | string | optional | Fractional basket to route reserve↔reserve conversions through |
| exportto | string | optional | Chain/system to export to (cross-chain send) |
| feecurrency | string | optional | Currency to pay fees in |
| refundto | string | optional | Refund address for failed pre-conversions |
| memo | string | optional | Message for z-address destinations |
| preconvert | bool | optional | Convert before currency launch (default: false) |
| burn | bool | optional | Destroy tokens (subtract from supply, token only) |
| mintnew | bool | optional | Create new tokens (must send from currency's controlling ID, centralized only) |
| addconversionfees | bool | optional | Auto-calculate extra to cover conversion fees on full amount |
| exportid | bool | optional | Export full VerusID definition cross-chain |
| exportcurrency | bool | optional | Export currency definition cross-chain |
| data | object | optional | Store large, optionally signed data in outputs |

**Result**
```
"operation-id"   (string) if returntxtemplate is false
```
Or if `returntxtemplate` is true:
```json
{
  "outputtotals": { "currencyid": amount },
  "hextx": "hexstring"
}
```

**Examples**

**Simple Send**
```bash
./verus -testnet sendcurrency "*" '[{"address":"myid@","amount":1}]'
## Sends 1 VRSCTEST from any wallet address to myid@
```

**Send a Token**
```bash
./verus -testnet sendcurrency "*" '[{"address":"myid@","amount":5,"currency":"yourapp"}]'
## Sends 5 yourapp tokens to myid@
```

**Convert VRSCTEST → VRSC-USD**
```bash
./verus -testnet sendcurrency "*" '[{
  "address":"myid@",
  "amount":10,
  "currency":"VRSCTEST",
  "convertto":"VRSC-USD"
}]'
## Converts 10 VRSCTEST to VRSC-USD basket tokens, sent to myid@
```

**Convert Between Reserves (VRSCTEST → USD via basket)**
```bash
./verus -testnet sendcurrency "*" '[{
  "address":"myid@",
  "amount":100,
  "currency":"VRSCTEST",
  "convertto":"USD",
  "via":"VRSC-USD"
}]'
## Converts VRSCTEST → USD through the VRSC-USD fractional basket
```

**Cross-Chain Export**
```bash
./verus -testnet sendcurrency "*" '[{
  "address":"myid@",
  "amount":10,
  "currency":"VRSCTEST",
  "exportto":"vETH",
  "feecurrency":"veth"
}]'
## Exports 10 VRSCTEST to Ethereum via the bridge
```

**Mint New Tokens (Centralized Currency)**
```bash
./verus -testnet sendcurrency "yourapp@" '[{
  "address":"myid@",
  "amount":10,
  "currency":"yourapp",
  "mintnew":true
}]'
## Mints 10 new yourapp tokens (must send from controlling ID)
```

**Burn Tokens**
```bash
./verus -testnet sendcurrency "*" '[{
  "address":"myid@",
  "amount":5,
  "currency":"yourapp",
  "burn":true
}]'
## Burns 5 yourapp tokens, removing them from supply
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"sendcurrency","params":["*",[{"address":"myid@","amount":1}]]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Simple transfers** — send native or token currency to any address/ID
- **DEX swaps** — convert between reserves and fractional currencies
- **Cross-chain bridging** — export currency to another chain via `exportto`
- **Token minting** — create new supply for centralized (proofprotocol:2) tokens
- **Token burning** — permanently destroy tokens
- **Pre-conversion** — participate in currency launches before `startblock`

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| `Insufficient funds` | Wallet doesn't have enough of the specified currency | Check balance with `getbalance` or `getcurrencybalance` |
| `Source currency cannot be converted to destination` | No valid conversion path | Use `getcurrencyconverters` to find paths; use `via` for reserve↔reserve |
| `Invalid address` | Destination address/ID not found | Verify address with `getidentity` or `validateaddress` |
| `Cannot mint currency` | Sending from wrong ID or non-centralized currency | Must send from the currency's control ID; currency must have `proofprotocol: 2` |

**Related Commands**
- [estimateconversion](#estimateconversion) — preview conversion before sending
- [getcurrencyconverters](#getcurrencyconverters) — find conversion pairs
- [getcurrency](#getcurrency) — check currency details
- [getexports](#getexports) / [getimports](#getimports) — track cross-chain transfers

**Notes**
- **Conversions are DeFi**: all conversions in the same block get the same price (no front-running)
- The `"*"` wildcard for `fromaddress` sources funds from any wallet UTXO
- Cross-chain sends require the destination chain to be running and notarized
- `mintnew` only works with `proofprotocol: 2` (centralized) currencies
- `burn` only works with tokens, not native chain currencies
- Use `returntxtemplate: true` for offline signing or fee estimation
- Operation IDs can be tracked with `z_getoperationstatus`

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## setcurrencytrust

> **Category:** Multichain | **Version:** v1.2.x+

Sets trust ratings for currencies, controlling which currencies the wallet will sync, display, and allow spending.

**Syntax**
```bash
verus setcurrencytrust '{"clearall":bool,"setratings":[...],"removeratings":[...],"currencytrustmode":n}'
```

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| clearall | bool | optional | Clear all existing trust ratings before applying changes |
| setratings | array | optional | `[{"currencyid": JSONRatingObject}, ...]` — set/replace ratings for currencies |
| removeratings | array | optional | `["currencyid", ...]` — remove ratings for specified currencies |
| currencytrustmode | int | optional | 0 = spend/list all, 1 = only approved, 2 = all except blocked |

**Result**
No return on success; error on failure.

**Examples**

**Set Trust Mode to Allowlist**
```bash
./verus -testnet setcurrencytrust '{"currencytrustmode":1}'
## Now only currencies explicitly rated as approved will be shown/spendable
```

**Approve a Specific Currency**
```bash
./verus -testnet setcurrencytrust '{"setratings":[{"i...":{"trustlevel":1}}]}'
## Approves yourapp token (replace i... with your currency's actual currencyid)
```

**Remove a Rating**
```bash
./verus -testnet setcurrencytrust '{"removeratings":["i..."]}'
## Removes the rating for that currency (replace i... with your currency's actual currencyid)
```

**Reset All Trust Settings**
```bash
./verus -testnet setcurrencytrust '{"clearall":true,"currencytrustmode":0}'
## Clears all ratings and sets mode to unrestricted
```

**RPC (curl)**
```bash
curl --user user1445741888:pass... --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"setcurrencytrust","params":[{"currencytrustmode":0}]}' \
  -H 'content-type: text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**
- **Filter spam tokens** — set mode 2 and block unwanted currencies
- **Curated wallet** — set mode 1 and only approve known currencies
- **Reset to defaults** — clearall + mode 0

**Common Errors**
| Error | Cause | Solution |
|-------|-------|---------|
| Invalid parameters | Malformed JSON or invalid currency ID | Check JSON syntax and verify currency IDs |

**Related Commands**
- [getcurrencytrust](#getcurrencytrust) — view current trust settings
- [listcurrencies](#listcurrencies) — see available currencies

**Notes**
- Trust settings are wallet-local only — they don't affect the blockchain
- Mode 1 (allowlist) is the most restrictive — only explicitly approved currencies work
- Mode 2 (blocklist) is moderate — everything works except explicitly blocked
- These settings affect `listcurrencies` output and spending ability

**Tested On**
- VRSCTEST block height: 926963
- Verus version: 1.2.14-2

---

## submitacceptednotarization

> **Category:** Multichain | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Finishes an almost complete notarization transaction based on the notary chain and current wallet.

**Syntax**

```bash
submitacceptednotarization "{earnednotarization}" "{notaryevidence}" sourceoffunds
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | `earnednotarization` | object | Yes | Notarization earned on the other system, basis for this submission |
| 2 | `notaryevidence` | object | Yes | Evidence and notary signatures validating the notarization |
| 3 | `sourceoffunds` | string | No | Valid source of funds to enable privacy when notarizing multiple PBaaS chains |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| `txid` | string | Transaction ID of submitted transaction, or NULL on failure |

**Examples**

```bash
verus -testnet submitacceptednotarization "{earnednotarization}" "{notaryevidence}" "sourceoffunds"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid notarization | The earned notarization object is malformed or invalid |
| Insufficient funds | Wallet cannot cover transaction fees |

**Related Commands**

- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data
- [`getnotarizationproofs`](#getnotarizationproofs) — Get notarization proofs
- [`submitchallenges`](#submitchallenges) — Submit evidence challenges

**Notes**

- Used by notary nodes to submit cross-chain notarizations.
- The `sourceoffunds` parameter allows privacy by using a specific funding address when notarizing multiple chains.
- Submission is subject to consensus rules — invalid notarizations will be rejected.
- Typically called by automated bridge/notary software, not end users.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — requires active notary node setup

---

## submitchallenges

> **Category:** Multichain | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Submits cryptographic challenges to existing, unconfirmed notarizations, proving the existence of an alternate chain.

**Syntax**

```bash
submitchallenges '[challengeobjects, ...]'
```

**Parameters**

Array of challenge objects:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | `"vrsc::evidence.skipchallenge"` or `"vrsc::evidence.validitychallenge"` |
| `notarizationref` | object | Yes | `{"txid":"hex","voutnum":n}` — reference to the notarization being challenged |
| `forkroot` | object | No | Fork root proof |
| `challengeroot` | object | Yes | Challenge proof root |
| `evidence` | object | Yes | CNotaryEvidence supporting the challenge |

**Result**

Array of results:

| Field | Type | Description |
|-------|------|-------------|
| `txid` | string | Transaction ID of submitted challenge |
| `error` | string | Error string if challenge submission failed |

**Examples**

```bash
verus -testnet submitchallenges '[{"notarizationref":{"txid":"hexvalue","voutnum":0},"challengeroot":{},"evidence":{}}]'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Insufficient funds | Wallet lacks funds for challenge transaction fees |
| Invalid notarization reference | Referenced notarization doesn't exist or is already confirmed |

**Related Commands**

- [`getnotarizationproofs`](#getnotarizationproofs) — Get proofs for challenges
- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data
- [`submitacceptednotarization`](#submitacceptednotarization) — Submit a notarization

**Notes**

- Part of Verus's decentralized cross-chain dispute resolution system.
- Does not require the alternate chain to have more power — only that it moved forward multiple blocks since the prior notarization.
- Requires the local wallet to have funds for transaction fees.
- Challenge types: `skipchallenge` (i-addr: `iCwxpRL6h3YeCRtGjgQSsqoKdZCuM4Dxaf`) and `validitychallenge` (i-addr: `iCPb8ywQna7jYV2SHrGZ6vQMj7kuyWFxvb`).

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — requires active cross-chain notarization disputes

---

## submitimports

> **Category:** Multichain | **Version:** v1.2.x+

⚠️ DOCUMENTED FROM HELP — Accepts a set of exports from another system to post to the current network.

**Syntax**

```bash
submitimports '{"sourcesystemid":"systemid","notarizationtxid":"txid","notarizationtxoutnum":n,"exports":[...]}'
```

**Parameters**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sourcesystemid` | string | Yes | System ID of the source chain |
| `notarizationtxid` | string | Yes | Transaction ID of the notarization backing these imports |
| `notarizationtxoutnum` | int | Yes | Output number of the notarization transaction |
| `exports` | array | Yes | Array of export objects |

**Export object fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `height` | int | Yes | Block height of the export |
| `txid` | string | Yes | Transaction ID of the export |
| `txoutnum` | int | Yes | Output number |
| `partialtransactionproof` | string | Yes | Hex-encoded partial transaction proof |
| `transfers` | array | Yes | Array of transfer objects |

**Result**

Array of objects:

| Field | Type | Description |
|-------|------|-------------|
| `currency` | string | Currency ID |
| `txid` | string | Transaction ID of the submitted import |
| `txoutnum` | int | Output number |

**Examples**

```bash
verus -testnet submitimports '{"sourcesystemid":"systemid","notarizationtxid":"txid","notarizationtxoutnum":0,"exports":[{"height":100,"txid":"hexid","txoutnum":0,"partialtransactionproof":"hexstr","transfers":[]}]}'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid source system | Source system ID is not recognized |
| Invalid notarization | Referenced notarization doesn't exist or is invalid |
| Proof verification failed | Partial transaction proof cannot be verified |

**Related Commands**

- [`getlastimportfrom`](#getlastimportfrom) — Get last import from a system
- [`getnotarizationdata`](#getnotarizationdata) — Get notarization data
- [`submitacceptednotarization`](#submitacceptednotarization) — Submit a notarization

**Notes**

- Used by bridge nodes to relay cross-chain transfers.
- Each export must include a valid partial transaction proof that can be verified against the referenced notarization.
- Typically called by automated bridge software, not end users.

**Tested On**

- **VRSCTEST** v1.2.14-2, block height 926990
- ⚠️ Not directly tested — requires active cross-chain bridge setup

--- PAGE: command-reference/network.md ---

---
label: Network
icon: terminal
---


# Network Commands


---

## addnode

> **Category:** Network | **Version:** v1.2.14+

Attempts to add or remove a node from the addnode list, or tries a connection to a node once.

**Syntax**

```
addnode "node" "add|remove|onetry"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| node      | string | Yes      | The node address (IP:port). See `getpeerinfo` for connected nodes. |
| command   | string | Yes      | `add` to add to the list, `remove` to remove, `onetry` to try once. |

**Result**

No return value on success.

**Examples**

```bash
## Add a node to the addnode list
verus -testnet addnode "192.168.0.6:18842" "add"

## Try connecting to a node once
verus -testnet addnode "192.168.0.6:18842" "onetry"

## Remove a node from the list
verus -testnet addnode "192.168.0.6:18842" "remove"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Error adding node` | Node already in the addnode list |
| `Node has not been added` | Trying to remove a node that isn't in the list |

**Related Commands**

- [`getaddednodeinfo`](#getaddednodeinfo) — View added nodes
- [`disconnectnode`](#disconnectnode) — Disconnect a specific node
- [`getpeerinfo`](#getpeerinfo) — View connected peers

**Notes**

- Nodes added with `add` will be persistently reconnected to.
- `onetry` attempts a single connection without adding to the persistent list.
- Use `getaddednodeinfo` to verify added nodes.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## clearbanned

> **Category:** Network | **Version:** v1.2.14+

Clear all banned IPs from the ban list.

**Syntax**

```
clearbanned
```

**Parameters**

None.

**Result**

No return value on success.

**Examples**

```bash
verus -testnet clearbanned
```

**Common Errors**

None typical — this command always succeeds.

**Related Commands**

- [`setban`](#setban) — Add or remove an IP from the ban list
- [`listbanned`](#listbanned) — List all banned IPs

**Notes**

- Removes all entries from the ban list at once.
- Use `listbanned` before running to verify what will be cleared.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## disconnectnode

> **Category:** Network | **Version:** v1.2.14+

Immediately disconnects from the specified node.

**Syntax**

```
disconnectnode "node"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| node      | string | Yes      | The node address (IP:port). See `getpeerinfo` for connected nodes. |

**Result**

No return value on success.

**Examples**

```bash
verus -testnet disconnectnode "192.168.0.6:18842"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Node not found in connected nodes` | The specified node is not currently connected |

**Related Commands**

- [`addnode`](#addnode) — Add/remove nodes from the connection list
- [`getpeerinfo`](#getpeerinfo) — List connected peers to find node addresses

**Notes**

- The disconnection is immediate.
- The node may reconnect if it's in the addnode list or connects inbound.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getaddednodeinfo

> **Category:** Network | **Version:** v1.2.14+

Returns information about added nodes. If `dns` is false, only a list of added nodes is returned; otherwise connected information is also available.

**Syntax**

```
getaddednodeinfo dns ( "node" )
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| dns       | boolean | Yes      | If false, only list added nodes. If true, include connection info. |
| node      | string  | No       | Return info about this specific node only. |

**Result**

```json
[
  {
    "addednode": "192.168.0.201",
    "connected": true|false,
    "addresses": [
      {
        "address": "192.168.0.201:8233",
        "connected": "outbound"
      }
    ]
  }
]
```

**Examples**

```bash
## Query all added nodes (no nodes added in this example)
verus -testnet getaddednodeinfo true
```

**Testnet output:**
```json
[
]
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Node has not been added` | Querying a specific node that wasn't added via `addnode` |

**Related Commands**

- [`addnode`](#addnode) — Add nodes to the list
- [`getpeerinfo`](#getpeerinfo) — View all connected peers

**Notes**

- Only nodes added via `addnode "add"` appear here. `onetry` nodes are not listed.
- Empty result means no nodes have been manually added.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getconnectioncount

> **Category:** Network | **Version:** v1.2.14+

Returns the number of connections to other nodes.

**Syntax**

```
getconnectioncount
```

**Parameters**

None.

**Result**

| Type    | Description |
|---------|-------------|
| numeric | The connection count |

**Examples**

```bash
verus -testnet getconnectioncount
```

**Testnet output:**
```
5
```

**Common Errors**

None typical.

**Related Commands**

- [`getpeerinfo`](#getpeerinfo) — Detailed info about each connection
- [`getnetworkinfo`](#getnetworkinfo) — General network state info

**Notes**

- Includes both inbound and outbound connections.
- A count of 0 may indicate network issues or that the node is still starting up.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getdeprecationinfo

> **Category:** Network | **Version:** v1.2.14+

Returns an object containing the current version and deprecation block height. Applicable only on mainnet.

**Syntax**

```
getdeprecationinfo
```

**Parameters**

None.

**Result**

```json
{
  "version": 2000753,
  "subversion": "/MagicBean:2.0.7-3/",
  "deprecationheight": 4453160
}
```

| Field             | Type    | Description |
|-------------------|---------|-------------|
| version           | numeric | The server version number |
| subversion        | string  | The server subversion string |
| deprecationheight | numeric | The block height at which this version will deprecate and shut down |

**Examples**

```bash
verus -testnet getdeprecationinfo
```

**Testnet output:**
```json
{
  "version": 2000753,
  "subversion": "/MagicBean:2.0.7-3/",
  "deprecationheight": 4453160
}
```

**Common Errors**

None typical.

**Related Commands**

- [`getinfo`](control.md#getinfo) — General server information
- [`getnetworkinfo`](#getnetworkinfo) — Network-specific info

**Notes**

- The deprecation height is the block at which this daemon version will automatically shut down, forcing operators to upgrade.
- On testnet, the deprecation height still applies but may differ from mainnet.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getnettotals

> **Category:** Network | **Version:** v1.2.14+

Returns information about network traffic, including bytes in, bytes out, and current time.

**Syntax**

```
getnettotals
```

**Parameters**

None.

**Result**

```json
{
  "totalbytesrecv": 19372173,
  "totalbytessent": 8385281,
  "timemillis": 1770450604273
}
```

| Field          | Type    | Description |
|----------------|---------|-------------|
| totalbytesrecv | numeric | Total bytes received |
| totalbytessent | numeric | Total bytes sent |
| timemillis     | numeric | Current time in milliseconds (Unix epoch) |

**Examples**

```bash
verus -testnet getnettotals
```

**Testnet output:**
```json
{
  "totalbytesrecv": 19372173,
  "totalbytessent": 8385281,
  "timemillis": 1770450604273
}
```

**Common Errors**

None typical.

**Related Commands**

- [`getnetworkinfo`](#getnetworkinfo) — General network state info
- [`getpeerinfo`](#getpeerinfo) — Per-peer traffic stats

**Notes**

- Values are cumulative since daemon start.
- Useful for monitoring bandwidth usage.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getnetworkinfo

> **Category:** Network | **Version:** v1.2.14+

Returns an object containing various state info regarding P2P networking.

**Syntax**

```
getnetworkinfo
```

**Parameters**

None.

**Result**

| Field          | Type    | Description |
|----------------|---------|-------------|
| version        | numeric | The server version |
| subversion     | string  | The server subversion string |
| protocolversion| numeric | The protocol version |
| localservices  | string  | The services offered to the network |
| timeoffset     | numeric | The time offset |
| connections    | numeric | The number of connections |
| networks       | array   | Information per network (ipv4, ipv6, onion) |
| relayfee       | numeric | Minimum relay fee for non-free transactions in VRSC/kB |
| localaddresses | array   | List of local addresses |
| warnings       | string  | Any network warnings |

**Examples**

```bash
verus -testnet getnetworkinfo
```

**Testnet output:**
```json
{
  "version": 2000753,
  "subversion": "/MagicBean:2.0.7-3/",
  "protocolversion": 170010,
  "localservices": "0000000000000005",
  "timeoffset": 0,
  "connections": 5,
  "networks": [
    {
      "name": "ipv4",
      "limited": false,
      "reachable": true,
      "proxy": "",
      "proxy_randomize_credentials": false
    },
    {
      "name": "ipv6",
      "limited": false,
      "reachable": true,
      "proxy": "",
      "proxy_randomize_credentials": false
    },
    {
      "name": "onion",
      "limited": true,
      "reachable": false,
      "proxy": "",
      "proxy_randomize_credentials": false
    }
  ],
  "relayfee": 0.00000100,
  "localaddresses": [],
  "warnings": ""
}
```

**Common Errors**

None typical.

**Related Commands**

- [`getpeerinfo`](#getpeerinfo) — Detailed per-peer info
- [`getconnectioncount`](#getconnectioncount) — Just the connection count
- [`getnettotals`](#getnettotals) — Traffic stats

**Notes**

- The `networks` array shows reachability for ipv4, ipv6, and onion (Tor).
- `localservices` is a bitmask of services this node offers.
- Empty `localaddresses` means the node is not advertising a public address.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## getpeerinfo

> **Category:** Network | **Version:** v1.2.14+

Returns data about each connected network node as a JSON array of objects.

**Syntax**

```
getpeerinfo
```

**Parameters**

None.

**Result**

Array of peer objects with the following fields:

| Field           | Type    | Description |
|-----------------|---------|-------------|
| id              | numeric | Peer index |
| addr            | string  | IP address and port of the peer |
| addrlocal       | string  | Local address |
| services        | string  | Services offered |
| tls_established | boolean | TLS connection status |
| tls_verified    | boolean | Peer certificate verification status |
| lastsend        | numeric | Last send time (epoch seconds) |
| lastrecv        | numeric | Last receive time (epoch seconds) |
| bytessent       | numeric | Total bytes sent |
| bytesrecv       | numeric | Total bytes received |
| conntime        | numeric | Connection time (epoch seconds) |
| timeoffset      | numeric | Time offset in seconds |
| pingtime        | numeric | Ping time in seconds |
| pingwait        | numeric | Time waiting for ping response (seconds) |
| version         | numeric | Peer protocol version |
| subver          | string  | Peer version string |
| inbound         | boolean | True if inbound connection |
| startingheight  | numeric | Starting block height of the peer |
| banscore        | numeric | Current ban score |
| synced_headers  | numeric | Last common header |
| synced_blocks   | numeric | Last common block |
| inflight        | array   | Block heights currently being requested |
| addr_processed  | numeric | Number of addr messages processed |
| addr_rate_limited | numeric | Number of addr messages rate-limited |
| whitelisted     | boolean | Whether the peer is whitelisted |

**Examples**

```bash
verus -testnet getpeerinfo
```

**Testnet output (first peer):**
```json
{
  "id": 7,
  "addr": "135.181.184.117:18842",
  "addrlocal": "75.159.130.74:9527",
  "services": "0000000000000005",
  "tls_established": true,
  "tls_verified": false,
  "lastsend": 1770450600,
  "lastrecv": 1770450599,
  "bytessent": 706304,
  "bytesrecv": 2011655,
  "conntime": 1770408356,
  "timeoffset": 0,
  "pingtime": 0.168548,
  "version": 170010,
  "subver": "/MagicBean:2.0.73/",
  "inbound": false,
  "startingheight": 926330,
  "banscore": 0,
  "synced_headers": 926998,
  "synced_blocks": 926998,
  "inflight": [],
  "addr_processed": 178,
  "addr_rate_limited": 0,
  "whitelisted": false
}
```

**Common Errors**

None typical.

**Related Commands**

- [`getconnectioncount`](#getconnectioncount) — Quick connection count
- [`addnode`](#addnode) — Add/remove nodes
- [`disconnectnode`](#disconnectnode) — Disconnect a peer

**Notes**

- `tls_established` and `tls_verified` show TLS connection security status.
- `banscore` accumulates as a peer misbehaves; at threshold (default 100), the peer is banned.
- `pingtime` is measured in decimal seconds.
- Use peer `addr` values with `disconnectnode` or `addnode`.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## listbanned

> **Category:** Network | **Version:** v1.2.14+

List all banned IPs/Subnets.

**Syntax**

```
listbanned
```

**Parameters**

None.

**Result**

Array of banned entries. Empty array if no bans exist.

**Examples**

```bash
verus -testnet listbanned
```

**Testnet output:**
```json
[]
```

**Common Errors**

None typical.

**Related Commands**

- [`setban`](#setban) — Add or remove bans
- [`clearbanned`](#clearbanned) — Clear all bans

**Notes**

- Each entry includes the banned IP/subnet, ban creation time, and expiry time.
- Empty result means no IPs are currently banned.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## ping

> **Category:** Network | **Version:** v1.2.14+

Requests that a ping be sent to all other nodes, to measure ping time. Results are available in `getpeerinfo` via `pingtime` and `pingwait` fields.

**Syntax**

```
ping
```

**Parameters**

None.

**Result**

No return value (void). This is an **asynchronous** command.

**Examples**

```bash
## Send ping to all peers
verus -testnet ping

## Then check results
verus -testnet getpeerinfo
## Look for "pingtime" field in each peer's output
```

**Common Errors**

None typical.

**Related Commands**

- [`getpeerinfo`](#getpeerinfo) — View ping results in `pingtime` and `pingwait` fields

**Notes**

- **Asynchronous**: `ping` returns immediately with no output. The actual ping measurement happens in the background.
- Results are available via `getpeerinfo` — check `pingtime` (last completed ping) and `pingwait` (pending ping).
- The ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.
- Values are in decimal seconds.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## setban

> **Category:** Network | **Version:** v1.2.14+

Attempts to add or remove an IP/Subnet from the banned list.

**Syntax**

```
setban "ip(/netmask)" "add|remove" (bantime) (absolute)
```

**Parameters**

| Parameter      | Type    | Required | Description |
|----------------|---------|----------|-------------|
| ip(/netmask)   | string  | Yes      | IP or subnet to ban (default /32 = single IP) |
| command        | string  | Yes      | `add` or `remove` |
| bantime        | numeric | No       | Seconds to ban (0 = default 24h). Can be overridden by `-bantime` startup arg. |
| absolute       | boolean | No       | If true, `bantime` is an absolute Unix timestamp |

**Result**

No return value on success.

**Examples**

```bash
## Ban a single IP for 24 hours (default)
verus -testnet setban "192.168.0.6" "add"

## Ban an IP for 1 day explicitly
verus -testnet setban "192.168.0.6" "add" 86400

## Ban a subnet
verus -testnet setban "192.168.0.0/24" "add"

## Remove a ban
verus -testnet setban "192.168.0.6" "remove"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `IP/Subnet already banned` | Trying to ban an already-banned address |
| `IP/Subnet not found` | Trying to remove a ban that doesn't exist |

**Related Commands**

- [`listbanned`](#listbanned) — List all banned IPs
- [`clearbanned`](#clearbanned) — Clear all bans

**Notes**

- Default ban duration is 24 hours unless overridden.
- The `-bantime` startup argument sets the default ban duration globally.
- Supports CIDR notation for subnet bans (e.g., `/24`).

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

--- PAGE: command-reference/rawtransactions.md ---

---
label: Raw Transactions
icon: terminal
---


# Raw Transactions Commands


---

## createrawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Create a transaction spending the given inputs and sending to the given addresses. Returns a hex-encoded raw transaction. The transaction is **not signed** and is **not stored** in the wallet or transmitted to the network.

**Syntax**

```
createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,...} (locktime) (expiryheight)
```

**Parameters**

| Parameter    | Type    | Required | Description |
|--------------|---------|----------|-------------|
| transactions | array   | Yes      | Array of input objects with `txid`, `vout`, and optional `sequence` |
| addresses    | object  | Yes      | Object with addresses as keys and amounts as values |
| locktime     | numeric | No       | Raw locktime (default 0). Non-0 also locktime-activates inputs |
| expiryheight | numeric | No       | Expiry height (default: nextblockheight+40 post-Blossom) |

**Address object format**

```json
{
  "address": 0.01,
  "address": {"currency": 0.01},
  "data": "hex"
}
```

**Result**

| Type   | Description |
|--------|-------------|
| string | Hex string of the unsigned raw transaction |

**Examples**

```bash
verus -testnet createrawtransaction '[{"txid":"myid","vout":0}]' '{"myaddress":0.01}'

## With OP_RETURN data
verus -testnet createrawtransaction '[{"txid":"myid","vout":0}]' '{"myaddress":0.01,"data":"00010203"}'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid parameter` | Malformed JSON input |
| `Invalid Verus address` | Invalid destination address |

**Related Commands**

- [`fundrawtransaction`](#fundrawtransaction) — Add inputs to fund the transaction
- [`signrawtransaction`](#signrawtransaction) — Sign the transaction
- [`sendrawtransaction`](#sendrawtransaction) — Broadcast signed transaction
- [`decoderawtransaction`](#decoderawtransaction) — Inspect the raw transaction

**Notes**

- This creates an **unsigned** transaction. Use `signrawtransaction` before broadcasting.
- Typical workflow: `createrawtransaction` → `fundrawtransaction` → `signrawtransaction` → `sendrawtransaction`.
- The `data` key creates an OP_RETURN output.
- Supports multi-currency outputs via the object value format.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help; not executed to avoid creating transactions)

---

## decoderawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Return a JSON object representing the serialized, hex-encoded transaction.

**Syntax**

```
decoderawtransaction "hexstring"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| hex       | string | Yes      | The transaction hex string |

**Result**

| Field          | Type    | Description |
|----------------|---------|-------------|
| txid           | string  | The transaction id |
| overwintered   | boolean | The Overwintered flag |
| version        | numeric | The version |
| versiongroupid | string  | Version group id (Overwintered txs) |
| locktime       | numeric | The lock time |
| expiryheight   | numeric | Last valid block height for mining (Overwintered txs) |
| vin            | array   | Array of inputs |
| vout           | array   | Array of outputs |
| vjoinsplit     | array   | JoinSplit data (version >= 2) |

**Examples**

```bash
## First get a raw transaction hex
verus -testnet getrawtransaction "1f345eb81bfc9b349b39fbb87edf284c565084bacc5a7f75113ab0dcf47ee7d8"

## Then decode it
verus -testnet decoderawtransaction "0400008085202f890206d5c092..."
```

**Testnet output (truncated):**
```json
{
  "txid": "1f345eb81bfc9b349b39fbb87edf284c565084bacc5a7f75113ab0dcf47ee7d8",
  "overwintered": true,
  "version": 4,
  "versiongroupid": "892f2085",
  "locktime": 0,
  "expiryheight": 926685,
  "vin": [
    {
      "txid": "0099668458e75500a75422ff5dc5e1236da73e5624939bb47431c8a792c0d506",
      "vout": 0,
      "addresses": ["iHErKKqAxAyBPaaf4MphkYFctDamXxTA2Y"],
      "scriptSig": { "asm": "...", "hex": "..." },
      "value": 0.00000000,
      "sequence": 4294967295
    }
  ],
  "vout": [...]
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `TX decode failed` | Invalid or corrupted hex string |

**Related Commands**

- [`getrawtransaction`](#getrawtransaction) — Get raw hex from a txid
- [`decodescript`](#decodescript) — Decode a script
- [`createrawtransaction`](#createrawtransaction) — Create raw transactions

**Notes**

- Read-only operation — does not modify the wallet or blockchain.
- Useful for inspecting transactions before signing or broadcasting.
- The `addresses` field in `vin` shows the spending addresses.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## decodescript

> **Category:** Rawtransactions | **Version:** v1.2.14+

Decode a hex-encoded script.

**Syntax**

```
decodescript "hex"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| hex       | string | Yes      | The hex encoded script |

**Result**

```json
{
  "asm": "asm",
  "hex": "hex",
  "type": "type",
  "reqSigs": 1,
  "addresses": ["address"],
  "p2sh": "address"
}
```

| Field          | Type    | Description |
|----------------|---------|-------------|
| asm            | string  | Script public key in assembly |
| hex            | string  | Hex encoded public key |
| type           | string  | Output type (e.g., pubkeyhash, scripthash, multisig) |
| spendableoutput| boolean | Whether the output is spendable |
| reqSigs        | numeric | Required signatures |
| addresses      | array   | Decoded addresses |
| p2sh           | string  | P2SH address wrapping this script |

**Examples**

```bash
## Decode a standard P2PKH script
verus -testnet decodescript "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac"
```

**Testnet output:**
```json
{
  "type": "pubkeyhash",
  "spendableoutput": true,
  "reqSigs": 1,
  "addresses": [
    "RMq8TyhrWAY76qY2EUcQfxW7GhNpnwvsSC"
  ],
  "p2sh": "bS8xsSnoTMoWXr26adY8pZwyLvadMh3nWr"
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Argument must be hexadecimal` | Non-hex characters in input |

**Related Commands**

- [`decoderawtransaction`](#decoderawtransaction) — Decode a full transaction
- [`createrawtransaction`](#createrawtransaction) — Create raw transactions

**Notes**

- Useful for analyzing scripts from transaction outputs.
- The `p2sh` field shows what the P2SH address would be if this script were wrapped.
- `spendableoutput` indicates if the script type is recognized as spendable.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## fundrawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Add inputs to a transaction until it has enough value to meet its output value. Adds one change output to the outputs. Existing inputs are not modified.

**Syntax**

```
fundrawtransaction "hexstring" '[utxos]' (changeaddress) (explicitfee)
```

**Parameters**

| Parameter     | Type   | Required | Description |
|---------------|--------|----------|-------------|
| hexstring     | string | Yes      | Hex string of the raw transaction |
| objectarray   | array  | No       | UTXOs to select from for funding |
| changeaddress | string | No       | Address to send change to |
| explicitfee   | number | No       | Use this fee instead of default (only with UTXO list) |

**Result**

```json
{
  "hex": "value",
  "fee": 0.0001,
  "changepos": 1
}
```

| Field     | Type    | Description |
|-----------|---------|-------------|
| hex       | string  | The resulting funded raw transaction (hex) |
| fee       | numeric | The fee added to the transaction |
| changepos | numeric | Position of the added change output, or -1 |

**Examples**

```bash
## Create an empty transaction
verus -testnet createrawtransaction "[]" '{"myaddress":0.01}'

## Fund it
verus -testnet fundrawtransaction "rawtransactionhex"

## Sign it
verus -testnet signrawtransaction "fundedtransactionhex"

## Send it
verus -testnet sendrawtransaction "signedtransactionhex"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Insufficient funds` | Wallet doesn't have enough balance |
| `TX decode failed` | Invalid hex string |

**Related Commands**

- [`createrawtransaction`](#createrawtransaction) — Create the initial transaction
- [`signrawtransaction`](#signrawtransaction) — Sign after funding
- [`sendrawtransaction`](#sendrawtransaction) — Broadcast signed transaction

**Notes**

- Inputs added by this command are **not signed** — use `signrawtransaction` afterward.
- Previously signed inputs may need to be re-signed since inputs/outputs have been modified.
- The optional UTXO list allows controlling which inputs are used for funding.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help)

---

## getrawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Return the raw transaction data. If verbose=0, returns hex-encoded data. If verbose is non-zero, returns a JSON object with transaction details.

**Syntax**

```
getrawtransaction "txid" (verbose)
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| txid      | string  | Yes      | The transaction id |
| verbose   | numeric | No       | 0 (default) returns hex string; non-zero returns JSON object |

**Result**

**If verbose=0:** hex-encoded transaction string.

**If verbose>0:** JSON object with `txid`, `version`, `vin`, `vout`, `blockhash`, `confirmations`, `time`, `blocktime`, and more.

**Examples**

```bash
## Get raw hex
verus -testnet getrawtransaction "1f345eb81bfc9b349b39fbb87edf284c565084bacc5a7f75113ab0dcf47ee7d8"
```

**Testnet output (truncated):**
```
0400008085202f890206d5c092a7c83174b49b9324563ea76d23e1c55dff2254a70055e758846699...
```

```bash
## Get verbose JSON
verus -testnet getrawtransaction "1f345eb81bfc9b349b39fbb87edf284c565084bacc5a7f75113ab0dcf47ee7d8" 1
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `No information available about transaction` | Transaction not in mempool and no unspent output exists (need `-txindex`) |
| `Invalid or non-wallet transaction id` | Malformed txid |

**Related Commands**

- [`decoderawtransaction`](#decoderawtransaction) — Decode raw hex to JSON
- [`sendrawtransaction`](#sendrawtransaction) — Broadcast a transaction

**Notes**

- By default, this only works for transactions in the mempool or with unspent outputs.
- To query any transaction, start the node with `-txindex` command line option.
- Verbose mode (1) returns the same data as `decoderawtransaction` plus block info.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## sendrawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Submits a raw transaction (serialized, hex-encoded) to the local node and network.

**Syntax**

```
sendrawtransaction "hexstring" (allowhighfees)
```

**Parameters**

| Parameter     | Type    | Required | Description |
|---------------|---------|----------|-------------|
| hexstring     | string  | Yes      | The hex string of the signed raw transaction |
| allowhighfees | boolean | No       | Allow high fees (default: false) |

**Result**

| Type   | Description |
|--------|-------------|
| string | The transaction hash in hex |

**Examples**

```bash
## Typical workflow
verus -testnet createrawtransaction '[{"txid":"mytxid","vout":0}]' '{"myaddress":0.01}'
verus -testnet signrawtransaction "myhex"
verus -testnet sendrawtransaction "signedhex"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `TX decode failed` | Invalid hex string |
| `Missing inputs` | Referenced inputs don't exist or are already spent |
| `Transaction already in block chain` | Transaction was already confirmed |
| `absurdly-high-fee` | Fee exceeds safety threshold (use `allowhighfees` to override) |
| `16: mandatory-script-verify-flag-failed` | Transaction not properly signed |

**Related Commands**

- [`createrawtransaction`](#createrawtransaction) — Create the transaction
- [`signrawtransaction`](#signrawtransaction) — Sign before sending
- [`fundrawtransaction`](#fundrawtransaction) — Add inputs for funding

**Notes**

- The transaction must be fully signed before broadcasting.
- Typical workflow: `createrawtransaction` → `fundrawtransaction` → `signrawtransaction` → `sendrawtransaction`.
- Use `allowhighfees=true` to bypass the high-fee safety check.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help; not executed)

---

## signrawtransaction

> **Category:** Rawtransactions | **Version:** v1.2.14+

Sign inputs for a raw transaction (serialized, hex-encoded).

**Syntax**

```
signrawtransaction "hexstring" ([prevtxs]) ([privatekeys]) (sighashtype) (branchid)
```

**Parameters**

| Parameter   | Type   | Required | Description |
|-------------|--------|----------|-------------|
| hexstring   | string | Yes      | The transaction hex string |
| prevtxs     | array  | No       | Previous dependent transaction outputs (or null) |
| privatekeys | array  | No       | Private keys for signing (or null to use wallet) |
| sighashtype | string | No       | Signature hash type (default: ALL) |
| branchid    | string | No       | Hex consensus branch id to sign with |

**Sighash types**

`ALL`, `NONE`, `SINGLE`, `ALL|ANYONECANPAY`, `NONE|ANYONECANPAY`, `SINGLE|ANYONECANPAY`

**prevtxs format**

```json
[
  {
    "txid": "id",
    "vout": 0,
    "scriptPubKey": "hex",
    "redeemScript": "hex",
    "amount": 0.01
  }
]
```

**Result**

```json
{
  "hex": "value",
  "complete": true,
  "errors": []
}
```

| Field    | Type    | Description |
|----------|---------|-------------|
| hex      | string  | The signed raw transaction hex |
| complete | boolean | Whether all inputs are fully signed |
| errors   | array   | Script verification errors (if any) |

**Examples**

```bash
verus -testnet signrawtransaction "myhex"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Input not found or already spent` | Referenced UTXO doesn't exist |
| `Unable to sign input, invalid stack size` | Script requires keys not in wallet |

**Related Commands**

- [`createrawtransaction`](#createrawtransaction) — Create the transaction
- [`fundrawtransaction`](#fundrawtransaction) — Add funding inputs
- [`sendrawtransaction`](#sendrawtransaction) — Broadcast after signing

**Notes**

- If no private keys are provided, the wallet's keys are used.
- Check `complete` in the result — if false, more signatures are needed (e.g., multisig).
- The `branchid` parameter allows signing with consensus rules ahead of the node's current height.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help)

--- PAGE: command-reference/util.md ---

---
label: Util
icon: terminal
---


# Util Commands


---

## createmultisig

> **Category:** Util | **Version:** v1.2.14+

Creates a multi-signature address with n-of-m keys required. Returns the address and redeemScript.

**Syntax**

```
createmultisig nrequired ["key",...]
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| nrequired | numeric | Yes      | Number of required signatures out of n keys |
| keys      | array   | Yes      | Array of addresses or hex-encoded public keys |

**Result**

```json
{
  "address": "multisigaddress",
  "redeemScript": "script"
}
```

**Examples**

```bash
verus -testnet createmultisig 2 '["RTZMZHDFSTFQst8XmX2dR4DaH87cEUs3gC","RNKiEBduBru6Siv1cZRVhp4fkZNyPska6z"]'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `a]multisignature address must require at least one key` | nrequired < 1 |
| `not enough keys supplied` | nrequired > number of keys |
| `Invalid public key` | Malformed key in the array |

**Related Commands**

- [`validateaddress`](#validateaddress) — Validate an address
- [`createrawtransaction`](rawtransactions.md#createrawtransaction) — Use the multisig address in transactions

**Notes**

- This does not add the multisig to the wallet. Use `addmultisigaddress` for that.
- The `redeemScript` is needed to spend from the multisig address.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## estimatefee

> **Category:** Util | **Version:** v1.2.14+

Estimates the approximate fee per kilobyte needed for a transaction to begin confirmation within nblocks blocks.

**Syntax**

```
estimatefee nblocks
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| nblocks   | numeric | Yes      | Target number of blocks for confirmation |

**Result**

| Type    | Description |
|---------|-------------|
| numeric | Estimated fee per kilobyte in VRSC. Returns minimum fee if not enough data. |

**Examples**

```bash
verus -testnet estimatefee 6
```

**Testnet output:**
```
0.00000100
```

**Common Errors**

None typical.

**Related Commands**

- [`estimatepriority`](#estimatepriority) — Estimate priority for zero-fee transactions

**Notes**

- Returns the minimum relay fee if not enough transactions and blocks have been observed.
- On testnet, fees are typically at the minimum (0.00000100 VRSC/kB).

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## estimatepriority

> **Category:** Util | **Version:** v1.2.14+

Estimates the approximate priority a zero-fee transaction needs to begin confirmation within nblocks blocks.

**Syntax**

```
estimatepriority nblocks
```

**Parameters**

| Parameter | Type    | Required | Description |
|-----------|---------|----------|-------------|
| nblocks   | numeric | Yes      | Target number of blocks for confirmation |

**Result**

| Type    | Description |
|---------|-------------|
| numeric | Estimated priority. Returns -1.0 if not enough data. |

**Examples**

```bash
verus -testnet estimatepriority 6
```

**Testnet output:**
```
-1
```

**Common Errors**

None typical.

**Related Commands**

- [`estimatefee`](#estimatefee) — Estimate fee per kilobyte

**Notes**

- Returns -1.0 when not enough transactions and blocks have been observed.
- Priority is based on coin age (value × confirmations).
- In practice, most transactions use fees rather than relying on priority.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## invalidateblock

> **Category:** Util | **Version:** v1.2.14+

Permanently marks a block as invalid, as if it violated a consensus rule.

**Syntax**

```
invalidateblock "hash"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| hash      | string | Yes      | The hash of the block to mark as invalid |

**Result**

No return value on success.

**Examples**

```bash
verus -testnet invalidateblock "000000018e6991fb0d5b595b7b7b8e4cb7f04a0b8b6704ecd0f063221d534bb1"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Block not found` | The specified block hash doesn't exist |

**Related Commands**

- [`reconsiderblock`](#reconsiderblock) — Undo the effects of `invalidateblock`

**Notes**

- ⚠️ **Dangerous**: This will cause the node to reject the specified block and all its descendants, potentially causing a chain reorganization.
- The invalidation is persistent across restarts.
- Use `reconsiderblock` to reverse this action.
- Primarily used for debugging or testing chain reorganizations.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only; not executed)

---

## jumblr_deposit

> **Category:** Util | **Version:** v1.2.14+

> ⚠️ **DEPRECATED** — Jumblr functionality is deprecated and may be removed in future versions.

Sets the deposit address for the Jumblr privacy mixing service.

**Syntax**

```
jumblr_deposit "depositaddress"
```

**Parameters**

| Parameter      | Type   | Required | Description |
|----------------|--------|----------|-------------|
| depositaddress | string | Yes      | The transparent address to use as the Jumblr deposit address |

**Result**

Confirmation of the deposit address being set.

**Examples**

```bash
verus -testnet jumblr_deposit "<R-address>"
```

**Related Commands**

- [`jumblr_secret`](#jumblr_secret) — Set the secret (destination) address
- [`jumblr_pause`](#jumblr_pause) — Pause Jumblr
- [`jumblr_resume`](#jumblr_resume) — Resume Jumblr

**Notes**

- **DEPRECATED**: Jumblr is no longer actively maintained.
- Jumblr was a privacy feature that mixed coins through shielded (z) addresses.
- The deposit address is the transparent address from which funds are sent into the mixing process.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only)

---

## jumblr_pause

> **Category:** Util | **Version:** v1.2.14+

> ⚠️ **DEPRECATED** — Jumblr functionality is deprecated and may be removed in future versions.

Pauses the Jumblr privacy mixing service.

**Syntax**

```
jumblr_pause
```

**Parameters**

None.

**Result**

Confirmation that Jumblr has been paused.

**Examples**

```bash
verus -testnet jumblr_pause
```

**Related Commands**

- [`jumblr_resume`](#jumblr_resume) — Resume Jumblr
- [`jumblr_deposit`](#jumblr_deposit) — Set deposit address
- [`jumblr_secret`](#jumblr_secret) — Set secret address

**Notes**

- **DEPRECATED**: Jumblr is no longer actively maintained.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only)

---

## jumblr_resume

> **Category:** Util | **Version:** v1.2.14+

> ⚠️ **DEPRECATED** — Jumblr functionality is deprecated and may be removed in future versions.

Resumes the Jumblr privacy mixing service after a pause.

**Syntax**

```
jumblr_resume
```

**Parameters**

None.

**Result**

Confirmation that Jumblr has been resumed.

**Examples**

```bash
verus -testnet jumblr_resume
```

**Related Commands**

- [`jumblr_pause`](#jumblr_pause) — Pause Jumblr
- [`jumblr_deposit`](#jumblr_deposit) — Set deposit address
- [`jumblr_secret`](#jumblr_secret) — Set secret address

**Notes**

- **DEPRECATED**: Jumblr is no longer actively maintained.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only)

---

## jumblr_secret

> **Category:** Util | **Version:** v1.2.14+

> ⚠️ **DEPRECATED** — Jumblr functionality is deprecated and may be removed in future versions.

Sets the secret (destination) address for the Jumblr privacy mixing service.

**Syntax**

```
jumblr_secret "secretaddress"
```

**Parameters**

| Parameter     | Type   | Required | Description |
|---------------|--------|----------|-------------|
| secretaddress | string | Yes      | The transparent address to receive mixed funds |

**Result**

Confirmation of the secret address being set.

**Examples**

```bash
verus -testnet jumblr_secret "<R-address>"
```

**Related Commands**

- [`jumblr_deposit`](#jumblr_deposit) — Set the deposit address
- [`jumblr_pause`](#jumblr_pause) — Pause Jumblr
- [`jumblr_resume`](#jumblr_resume) — Resume Jumblr

**Notes**

- **DEPRECATED**: Jumblr is no longer actively maintained.
- The secret address is the destination where mixed coins are sent after passing through shielded addresses.
- This address should ideally be unlinked to the deposit address for privacy.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only)

---

## reconsiderblock

> **Category:** Util | **Version:** v1.2.14+

Removes invalidity status of a block and its descendants, reconsidering them for activation. Used to undo the effects of `invalidateblock`.

**Syntax**

```
reconsiderblock "hash"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| hash      | string | Yes      | The hash of the block to reconsider |

**Result**

No return value on success.

**Examples**

```bash
verus -testnet reconsiderblock "000000018e6991fb0d5b595b7b7b8e4cb7f04a0b8b6704ecd0f063221d534bb1"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Block not found` | The specified block hash doesn't exist |

**Related Commands**

- [`invalidateblock`](#invalidateblock) — Mark a block as invalid

**Notes**

- This reverses the effect of `invalidateblock`.
- The block and all its descendants will be reconsidered for the active chain.
- May trigger a chain reorganization if the reconsidered chain has more work.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2 (documented from help only; not executed)

---

## validateaddress

> **Category:** Util | **Version:** v1.2.14+

Return information about the given transparent address.

**Syntax**

```
validateaddress "address"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| address   | string | Yes      | The transparent address to validate |

**Result**

```json
{
  "isvalid": true,
  "address": "verusaddress",
  "scriptPubKey": "hex",
  "segid": 60,
  "ismine": false,
  "iswatchonly": false,
  "isscript": false
}
```

| Field          | Type    | Description |
|----------------|---------|-------------|
| isvalid        | boolean | Whether the address is valid |
| address        | string  | The validated address |
| scriptPubKey   | string  | Hex encoded scriptPubKey |
| segid          | numeric | Segment ID |
| ismine         | boolean | Whether the address belongs to the wallet |
| issharedownership | boolean | Whether ownership is shared |
| iswatchonly    | boolean | Whether the address is watch-only |
| isscript       | boolean | Whether it's a script address |
| account        | string  | DEPRECATED. Associated account name |
| pubkey         | string  | Public key hex (if available) |
| iscompressed   | boolean | Whether the key is compressed |

**Examples**

```bash
verus -testnet validateaddress "<R-address>"
```

**Testnet output:**
```json
{
  "isvalid": true,
  "address": "<R-address>",
  "scriptPubKey": "76a914fa0d06f4b97c6f570e72f480441f4f24aed0da7588ac",
  "segid": 60,
  "ismine": false,
  "issharedownership": false,
  "iswatchonly": false,
  "isscript": false
}
```

**Common Errors**

None — invalid addresses return `{"isvalid": false}`.

**Related Commands**

- [`z_validateaddress`](#z_validateaddress) — Validate shielded (z) addresses
- [`getaddressbalance`](addressindex.md#getaddressbalance) — Get balance for an address

**Notes**

- If the address is invalid, only `isvalid: false` is returned.
- `ismine` indicates whether the wallet contains the private key.
- Works with both R-addresses and i-addresses.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

---

## z_validateaddress

> **Category:** Util | **Version:** v1.2.14+

Return information about the given shielded (z) address.

**Syntax**

```
z_validateaddress "zaddr"
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| zaddr     | string | Yes      | The z-address to validate |

**Result**

```json
{
  "isvalid": true,
  "address": "zaddr",
  "type": "sprout|sapling",
  "ismine": false
}
```

| Field                      | Type    | Description |
|----------------------------|---------|-------------|
| isvalid                    | boolean | Whether the address is valid |
| address                    | string  | The validated z address |
| type                       | string  | "sprout" or "sapling" |
| ismine                     | boolean | Whether the address belongs to the wallet |
| payingkey                  | string  | [sprout] Hex value of paying key (a_pk) |
| transmissionkey            | string  | [sprout] Hex value of transmission key (pk_enc) |
| diversifier                | string  | [sapling] Hex value of diversifier (d) |
| diversifiedtransmissionkey | string  | [sapling] Hex value of pk_d |

**Examples**

```bash
verus -testnet z_validateaddress "zcWsmqT4X2V4jgxbgiCzyrAfRT1vi1F4sn7M5Pkh66izzw8Uk7LBGAH3DtcSMJeUb2pi3W4SQF8LMKkU2cUuVP68yAGcomL"
```

**Testnet output:**
```json
{
  "isvalid": true,
  "address": "zcWsmqT4X2V4jgxbgiCzyrAfRT1vi1F4sn7M5Pkh66izzw8Uk7LBGAH3DtcSMJeUb2pi3W4SQF8LMKkU2cUuVP68yAGcomL",
  "type": "sprout",
  "payingkey": "f5bb3c888ccc9831e3f6ba06e7528e26a312eec3acc1823be8918b6a3a5e20ad",
  "transmissionkey": "7a58c7132446564e6b810cf895c20537b3528357dc00150a8e201f491efa9c1a",
  "ismine": false
}
```

**Common Errors**

None — invalid addresses return `{"isvalid": false}`.

**Related Commands**

- [`validateaddress`](#validateaddress) — Validate transparent addresses

**Notes**

- Sprout addresses start with `zc` and show `payingkey`/`transmissionkey`.
- Sapling addresses start with `zs` and show `diversifier`/`diversifiedtransmissionkey`.
- `ismine` indicates whether the wallet has the spending key.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

--- PAGE: command-reference/vdxf.md ---

---
label: VDXF
icon: terminal
---


# VDXF Commands


---

## getvdxfid

> **Category:** VDXF | **Version:** v1.2.14+

Returns the VDXF key (i-address) of a URI string. VDXF (Verus Data Exchange Format) provides a universal namespace for data keys.

**Syntax**

```
getvdxfid "vdxfuri" ({"vdxfkey":"i-address", "uint256":"hexstr", "indexnum":0})
```

**Parameters**

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| vdxfuri   | string | Yes      | The URI string to convert to a VDXF key |
| vdxfkey   | string | No       | VDXF key or i-address to combine via hash |
| uint256   | string | No       | 256-bit hash to combine with hash |
| indexnum  | number | No       | int32_t number to combine with hash |

**Result**

```json
{
  "vdxfid": "iAddress",
  "indexid": "xAddress",
  "hash160result": "hex",
  "qualifiedname": {
    "namespace": "i-address",
    "name": "string"
  }
}
```

| Field         | Type   | Description |
|---------------|--------|-------------|
| vdxfid        | string | i-address of the VDXF key |
| indexid       | string | x-address (index form) |
| hash160result | string | 20-byte hash in hex |
| qualifiedname | object | Separated name and namespace (field may appear as `"namespace"` or `"parentid"` depending on context) |
| bounddata     | object | Returned if additional data was bound |

**Examples**

```bash
verus -testnet getvdxfid "vrsc::system.agent.profile"
```

**Testnet output:**
```json
{
  "vdxfid": "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo",
  "indexid": "xQAucLDToJsGeocAtSBJNoMKhjFgN49Nm1",
  "hash160result": "30b5577487b05178ce95aac28940d78187cd0bae",
  "qualifiedname": {
    "namespace": "i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV",
    "name": "vrsc::system.agent.profile"
  }
}
```

```bash
verus -testnet getvdxfid "vrsc::system.currency.export"
```

**Testnet output:**
```json
{
  "vdxfid": "iLY9mLpjMHy94rcJk4roxoNgRLSqhJeHFz",
  "indexid": "xRNGE9FpCcBoh2VLbkWxwBuDSzTrZUN94D",
  "hash160result": "dcb11f97bce0c8734d92da7b0f5551acfbb629bb",
  "qualifiedname": {
    "namespace": "i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV",
    "name": "vrsc::system.currency.export"
  }
}
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid parameters` | Missing or malformed URI string |

**Related Commands**

- [`getidentity`](identity.md#getidentity) — Get identity with VDXF content

**Notes**

- VDXF provides a decentralized, collision-resistant namespace for data keys.
- The `namespace` in the result (e.g., `i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV`) represents the VRSC root namespace.
- URIs follow the format `namespace::category.subcategory.name`.
- The `vdxfid` (i-address) is the canonical identifier used in VerusID content maps and other VDXF data structures.
- Optional binding parameters (`vdxfkey`, `uint256`, `indexnum`) create compound keys by hashing additional data with the base key.

**Tested On**

- **VRSCTEST** — Block height: 926996 | Version: v1.2.14-2

--- PAGE: command-reference/wallet.md ---

---
label: Wallet
icon: terminal
---


# Wallet Commands

> **Placeholder convention:** Examples in this reference use `yourapp` / `yourapp-registration` as example token and account names, `<R-address>` for transparent addresses, `<txid>` for transaction IDs, `<blockhash>` for block hashes, and `<WIF-private-key>` for private key output. Commands shown were tested on VRSCTEST — only these project-specific values have been genericized.

---

## addmultisigaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Add a nrequired-to-sign multisignature address to the wallet. Each key is a Verus address or hex-encoded public key.

**Syntax**

```
addmultisigaddress nrequired ["key",...] ( "account" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | nrequired | numeric | Yes | Number of required signatures out of n keys/addresses |
| 2 | keysobject | string (JSON array) | Yes | JSON array of addresses or hex-encoded public keys |
| 3 | account | string | No | **DEPRECATED.** Must be `""` (empty string) for default account |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | A Verus address associated with the keys |

**Examples**

```bash
## Add a 2-of-2 multisig address
verus addmultisigaddress 2 '["RAddr1...","RAddr2..."]'
```

```bash
## JSON-RPC
curl --user myusername --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"addmultisigaddress","params":[2,"[\"RAddr1\",\"RAddr2\"]"]}' -H 'content-type:text/plain;' http://127.0.0.1:27486/
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `not enough keys supplied` | Fewer keys provided than `nrequired` |
| `a multisignature address must require at least one key` | nrequired < 1 |

**Related Commands**

- [`createmultisig`](util.md#createmultisig) — Creates multisig address without adding to wallet
- [`listunspent`](#listunspent) — List UTXOs including multisig

**Notes**

- The resulting address is added to the wallet and can be used to receive funds.
- To spend from multisig, you need the required number of signatures via `signrawtransaction`.
- The `account` parameter is deprecated — pass `""` or omit.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## backupwallet

> **Category:** Wallet | **Version:** v1.2.x+

Safely copies wallet.dat to a destination filename.

**Syntax**

```
backupwallet "destination"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | destination | string | Yes | The destination filename (alphanumeric only, no paths). Saved in the `-exportdir` directory. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| path | string | The full path of the destination file. |

**Examples**

**Basic Usage**

```bash
verus -testnet backupwallet "testbackup"
```

**Output:**
```
/home/cluster/.komodo/vrsctest/testbackup
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"backupwallet","params":["mybackup"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Regular backups** — schedule periodic wallet backups
- **Pre-upgrade safety** — backup before daemon upgrades
- **Disaster recovery** — maintain offsite copies

**Common Errors**

| Error | Cause |
|-------|-------|
| `Filename is invalid as only alphanumeric characters are allowed` | Filename contains special characters, slashes, or dots |
| `Error: Wallet backup failed!` | File system error or permissions issue |

**Related Commands**

- [`dumpprivkey`](#dumpprivkey) — Export individual private keys
- [`importprivkey`](#importprivkey) — Import keys into a wallet
- [`getwalletinfo`](#getwalletinfo) — Check wallet state before backup

**Notes**

- The filename must be **alphanumeric only** — no paths, dots, or special characters.
- The file is saved to the data directory (e.g., `~/.komodo/vrsctest/`) or the `-exportdir` if configured.
- The backup is a copy of `wallet.dat` — it contains all private keys. **Store securely.**
- Delete test backups after verification.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## convertpassphrase

> **Category:** Wallet | **Version:** v1.2.14-2+

Converts a Verus Desktop, Agama, Verus Agama, or Verus Mobile passphrase to a private key and WIF format for import with `importprivkey`.

**Syntax**

```
convertpassphrase "walletpassphrase"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | walletpassphrase | string | Yes | The wallet passphrase to convert |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| walletpassphrase | string | The passphrase entered |
| address | string | Verus address corresponding to the passphrase |
| pubkey | string | Hex-encoded raw public key |
| privkey | string | Hex-encoded raw private key |
| wif | string | Private key in WIF format (use with `importprivkey`) |

**Examples**

```bash
verus convertpassphrase "my wallet passphrase words here"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Missing passphrase argument | No passphrase provided |

**Related Commands**

- [`importprivkey`](#importprivkey) — Import WIF private key into wallet
- [`dumpprivkey`](#dumpprivkey) — Export private key in WIF format

**Notes**

- Useful for migrating from Verus Desktop/Agama/Mobile wallets to CLI.
- The WIF output can be directly used with `importprivkey`.
- **Security:** Be cautious with passphrases — do not expose them in shell history.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## decryptdata

> **Category:** Wallet | **Version:** v1.2.14-2+

Decrypts a VDXF data descriptor, which is typically encrypted to a z-address. Uses viewing keys from the wallet or provided parameters to decrypt nested encryption layers.

**Syntax**

```
decryptdata '{
  "datadescriptor": {},
  "evk": "Optional Sapling extended full viewing key",
  "ivk": "Optional hex incoming viewing key",
  "txid": "hex",
  "retrieve": bool
}'
```

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| datadescriptor | object | Optional* | Data descriptor to decrypt (uses keys from descriptor & wallet) |
| iddata | object | Optional* | Identity, VDXF key, metadata to limit query, and keys to decrypt |
| evk | string | No | Extended viewing key for decoding (may not be in descriptor) |
| ivk | string | No | Incoming viewing key (hex) for decoding |
| txid | string | No | Transaction ID if data is from a tx and retrieve is true |
| retrieve | boolean | No | Default `false`. If true, retrieves data from on-chain reference and decrypts |

*Either `datadescriptor` or `iddata` is required.

**iddata sub-fields**

| Name | Type | Description |
|------|------|-------------|
| identityid | string | Identity (e.g., `id@`) |
| vdxfkey | string | VDXF key (e.g., `i-vdxfkey`) |
| startheight | numeric | Start block height for query |
| endheight | numeric | End block height for query |
| getlast | boolean | Get the last matching entry |

**Result**

Returns the decrypted data descriptor object with as much decryption as possible completed.

**Examples**

```bash
## Encrypt data first
verus signdata '{"address":"Verus Coin Foundation.vrsc@", "createmmr":true, "data":[{"message":"hello world", "encrypttoaddress":"zs1..."}]}'

## Then decrypt
verus decryptdata '{"datadescriptor":{...encrypted output...}}'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| No decryption possible | Neither viewing key nor SSK matches the encrypted data |
| Missing required fields | Neither `datadescriptor` nor `iddata` provided |

**Related Commands**

- [`signdata`](identity.md#signdata) — Sign and optionally encrypt data
- [`z_exportviewingkey`](#z_exportviewingkey) — Export viewing key for decryption
- [`verifysignature`](identity.md#verifysignature) — Verify signed data

**Notes**

- Part of Verus's VDXF (Verus Data Exchange Format) system for identity-linked encrypted data.
- Supports nested encryption layers — will attempt to decrypt as deeply as possible.
- If only a viewing key is available (not spending key), decryption is still possible for data encrypted to that key.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## dumpprivkey

> **Category:** Wallet | **Version:** v1.2.x+

Reveals the private key corresponding to a transparent address.

**Syntax**

```
dumpprivkey "t-addr"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | t-addr | string | Yes | The transparent address (R-address) to export. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| key | string | The WIF-encoded private key. |

**Examples**

**Basic Usage**

```bash
verus -testnet dumpprivkey "<R-address>"
```

**Output:**
```
<WIF-private-key>
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"dumpprivkey","params":["<R-address>"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Wallet migration** — export keys to import into another wallet
- **Backup** — store individual private keys securely
- **Debugging** — verify key ownership

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid Verus address` | Address format is wrong |
| `Private key for address is not known` | Address is not in this wallet |
| `Wallet is locked` | Wallet must be unlocked with `walletpassphrase` first |

**Related Commands**

- [`importprivkey`](#importprivkey) — Import a private key
- [`backupwallet`](#backupwallet) — Full wallet backup (preferred)

**Notes**

> ⚠️ **SECURITY WARNING:** The private key controls all funds at this address. Anyone with the key can spend the funds. Never share private keys. Store them encrypted and offline.

- Returns a WIF (Wallet Import Format) encoded key.
- The wallet must be unlocked if encrypted.
- For z-addresses, use `z_exportkey` instead.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## dumpwallet

> **Category:** Wallet | **Version:** v1.2.14-2+

Dumps transparent address (taddr) wallet keys in a human-readable format to a file. Does NOT include shielded (z-address) keys — use `z_exportwallet` for that.

**Syntax**

```
dumpwallet "filename" ( omitemptytaddresses )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | filename | string | Yes | Output filename (saved in `-exportdir` folder) |
| 2 | omitemptytaddresses | boolean | No | Default `false`. If true, only export addresses with UTXOs or that control IDs |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| path | string | Full path of the destination file |

**Examples**

```bash
verus dumpwallet "my-wallet-backup"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Cannot overwrite existing file` | File already exists at destination |
| `exportdir` not set | verusd not started with `-exportdir` option |

**Related Commands**

- [`importwallet`](#importwallet) — Import taddr keys from dump file
- [`z_exportwallet`](#z_exportwallet) — Export all keys (taddr + zaddr)
- [`backupwallet`](#backupwallet) — Copy wallet.dat file

**Notes**

- Only exports transparent address keys. Use `z_exportwallet` for both transparent and shielded.
- Requires `-exportdir` to be set when starting verusd.
- Cannot overwrite existing files (safety measure).
- The `omitemptytaddresses` flag should be used carefully — addresses not yet indexed may be skipped.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## encryptwallet

> **Category:** Wallet | **Version:** v1.2.14-2+

Encrypts the wallet with a passphrase. This is for first-time encryption only.

⚠️ **This command is DISABLED by default.** Requires experimental features to be enabled.

**Syntax**

```
encryptwallet "passphrase"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | passphrase | string | Yes | The passphrase to encrypt the wallet with (minimum 1 character) |

**Enabling**

To enable, restart verusd with:
```
-experimentalfeatures -developerencryptwallet
```

Or add to config file:
```
experimentalfeatures=1
developerencryptwallet=1
```

**Result**

Shuts down the server after encrypting.

**Examples**

```bash
## Encrypt the wallet
verus encryptwallet "my pass phrase"

## After restart, unlock for operations
verus walletpassphrase "my pass phrase"

## Lock again
verus walletlock
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `encryptwallet is disabled` | Experimental features not enabled |
| Wallet already encrypted | Use `walletpassphrasechange` instead |

**Related Commands**

- `walletpassphrase` — Unlock encrypted wallet (not a standalone RPC — wallet is unlocked via daemon startup flags or `encryptwallet` workflow)
- `walletlock` — Lock the wallet (not a standalone RPC in Verus)
- `walletpassphrasechange` — Change encryption passphrase (not a standalone RPC in Verus)

**Notes**

- **DO NOT use casually** — encrypting the wallet requires the passphrase for all future private key operations.
- The server shuts down after encryption completes.
- This is an experimental feature inherited from zcashd.
- After encryption, `dumpprivkey`, `z_exportkey`, signing, and sending all require unlocking first.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output only — **not executed**)

---

## getaccount

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Returns the account associated with the given address.

**Syntax**

```
getaccount "address"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | The Verus address for account lookup |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | The account name |

**Examples**

```bash
verus getaccount "<R-address>"
```

**Live output (testnet):**
```
yourapp-registration
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid address | Address not recognized |

**Related Commands**

- [`setaccount`](#setaccount) — Set account for an address (deprecated)
- [`getaccountaddress`](#getaccountaddress) — Get address for an account (deprecated)
- [`listaccounts`](#listaccounts) — List all accounts (deprecated)

**Notes**

- The account system is **deprecated**. Accounts were a Bitcoin Core feature removed in later versions.
- Default account is `""` (empty string).

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## getaccountaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Returns the current Verus address for receiving payments to the specified account.

**Syntax**

```
getaccountaddress "account"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | account | string | Yes | Must be `""` for default account. Any other string causes an error. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | The account's Verus address |

**Examples**

```bash
verus getaccountaddress ""
```

**Live output (testnet):**
```
RNUj32rViHuEk5F3VEmk53q4xhMMq2wffT
```

**Related Commands**

- [`getaccount`](#getaccount) — Get account for an address (deprecated)
- [`getaddressesbyaccount`](#getaddressesbyaccount) — Get all addresses for account (deprecated)

**Notes**

- The account system is **deprecated**.
- Only `""` (empty string) is accepted as the account parameter.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## getaddressesbyaccount

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Returns the list of addresses for the given account.

**Syntax**

```
getaddressesbyaccount "account"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | account | string | Yes | Must be `""` for default account |

**Result**

JSON array of Verus addresses associated with the account.

**Examples**

```bash
verus getaddressesbyaccount ""
```

**Live output (testnet):**
```json
[
  "RB5s8g763JCWcpdsMsiTMiQ5SQdj376ipg",
  "RExj2gcJrBnrPjmaqcyk7NdvLtvaKX2LGH",
  "<R-address>",
  "RNUj32rViHuEk5F3VEmk53q4xhMMq2wffT",
  "<R-address>",
  "RQVywYFCbASodUjjpff57RLpGpT5UUbcbT",
  "RRcQfB7G4GKFb9pShCK48V1kvuspnKrFMf",
  "RSCo6N67YCBTv6M2u8XmXbQo63EEqD148v"
]
```

**Related Commands**

- [`getaccount`](#getaccount) — Get account for address (deprecated)
- [`getaccountaddress`](#getaccountaddress) — Get address for account (deprecated)
- [`listaccounts`](#listaccounts) — List all accounts (deprecated)

**Notes**

- The account system is **deprecated**.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## getbalance

> **Category:** Wallet | **Version:** v1.2.x+

Returns the server's total available balance.

**Syntax**

```
getbalance ( "account" minconf includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | account | string | No | `""` | DEPRECATED. Must be `""` or `"*"` for total balance. |
| 2 | minconf | numeric | No | 1 | Only include transactions confirmed at least this many times. |
| 3 | includeWatchonly | bool | No | false | Also include balance in watch-only addresses. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| amount | numeric | The total amount in VRSCTEST received. |

**Examples**

**Basic Usage**

```bash
verus -testnet getbalance
```

**Output:**
```
122.88450000
```

**With Minimum Confirmations**

```bash
verus -testnet getbalance "*" 6
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getbalance","params":["*",6]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Check total wallet balance** before sending transactions
- **Verify confirmed balance** with higher minconf for large payments
- **Monitor watch-only addresses** with `includeWatchonly=true`

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid account name` | Passing an account name other than `""` or `"*"` |

**Related Commands**

- [`getcurrencybalance`](#getcurrencybalance) — Balance for a specific address/currency
- [`getunconfirmedbalance`](#getunconfirmedbalance) — Unconfirmed balance only
- [`getwalletinfo`](#getwalletinfo) — Full wallet state including balance

**Notes**

- The `account` parameter is deprecated. Always use `""` or `"*"`.
- Returns the balance for the entire wallet, not a specific address.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getcurrencybalance

> **Category:** Wallet | **Version:** v1.2.x+

Returns the balance in all currencies of a taddr or zaddr belonging to the node's wallet.

**Syntax**

```
getcurrencybalance "address" ( minconf ) ( friendlynames ) ( includeshared )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | address | string or object | Yes | — | The address to query. Supports z*, R*, i* wildcards. Can be an object with `address` and `currency` members. |
| 2 | minconf | numeric | No | 1 | Minimum confirmations to include. |
| 3 | friendlynames | boolean | No | true | Use friendly names instead of i-addresses. |
| 4 | includeshared | bool | No | false | Include outputs spendable by others too. |

**Result**

Returns an object with currency names as keys and balances as values.

**Examples**

**Basic Usage**

```bash
verus -testnet getcurrencybalance "<R-address>"
```

**Output:**
```json
{
  "VRSCTEST": 52.88540000,
  "yourapp": 109.99000000
}
```

**With Minimum Confirmations**

```bash
verus -testnet getcurrencybalance "<R-address>" 5
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getcurrencybalance","params":["<R-address>",5]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Check multi-currency balances** on a PBaaS chain
- **Per-address accounting** — see exactly what each address holds
- **Wildcard queries** — use `"R*"` to check all R-addresses

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid address` | Address not recognized or not in wallet |

> ⚠️ **CAUTION:** If the wallet only has an incoming viewing key for the address, spends cannot be detected and the returned balance may be larger than actual.

**Related Commands**

- [`getbalance`](#getbalance) — Total wallet balance (single currency)
- [`getwalletinfo`](#getwalletinfo) — Full wallet state
- [`listunspent`](#listunspent) — Detailed UTXO listing

**Notes**

- Unlike `getbalance`, this command shows **all currencies** held at an address.
- The `address` parameter can be an object: `{"address":"R...","currency":"VRSCTEST"}` to filter by currency.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getnewaddress

> **Category:** Wallet | **Version:** v1.2.x+

Returns a new VRSCTEST address for receiving payments.

**Syntax**

```
getnewaddress ( "account" )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | account | string | No | `""` | DEPRECATED. Must be `""` for default account. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| address | string | A new VRSCTEST transparent address (R-address). |

**Examples**

**Basic Usage**

```bash
verus -testnet getnewaddress
```

**Output:**
```
RB5s8g763JCWcpdsMsiTMiQ5SQdj376ipg
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getnewaddress","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Generate receiving address** for each incoming payment
- **Improve privacy** by using a fresh address per transaction
- **Label-based accounting** (deprecated account system)

**Common Errors**

| Error | Cause |
|-------|-------|
| `Error: Keypool ran out` | Key pool exhausted — wallet may need unlocking |

**Related Commands**

- [`getrawchangeaddress`](#getrawchangeaddress) — Address for change outputs
- [`getbalance`](#getbalance) — Check balance after receiving
- [`getcurrencybalance`](#getcurrencybalance) — Check per-address balance

**Notes**

- Each call generates a new address from the HD key pool.
- The `account` parameter is deprecated — do not pass anything other than `""`.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getrawchangeaddress

> **Category:** Wallet | **Version:** v1.2.x+

Returns a new VRSCTEST address for receiving change. For use with raw transactions, NOT normal use.

**Syntax**

```
getrawchangeaddress
```

**Parameters**

None.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| address | string | A new change address (R-address). |

**Examples**

**Basic Usage**

```bash
verus -testnet getrawchangeaddress
```

**Output:**
```
RPLRRViL6KqckYSyR2EUSBx1Dcos2F2qho
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getrawchangeaddress","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Raw transaction construction** — specify a change output manually
- **Advanced UTXO management** — control where change goes

**Common Errors**

| Error | Cause |
|-------|-------|
| `Keypool ran out` | Key pool exhausted |

**Related Commands**

- [`getnewaddress`](#getnewaddress) — For normal receiving addresses
- [`listunspent`](#listunspent) — List UTXOs for raw transaction building

**Notes**

- This is intended for raw transaction workflows only. For normal use, use `getnewaddress`.
- The wallet automatically handles change addresses during standard sends.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getreceivedbyaccount

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Returns the total amount received by addresses associated with the specified account.

**Syntax**

```
getreceivedbyaccount "account" ( minconf )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | account | string | Yes | Must be `""` for default account |
| 2 | minconf | numeric | No | Minimum confirmations (default: 1) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | numeric | Total amount received in VRSC |

**Examples**

```bash
verus getreceivedbyaccount ""
```

**Live output (testnet):**
```
766.98690000
```

**Related Commands**

- [`getreceivedbyaddress`](#getreceivedbyaddress) — Get received amount by address
- [`listreceivedbyaccount`](#listreceivedbyaccount) — List received by all accounts (deprecated)

**Notes**

- The account system is **deprecated**.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## getreceivedbyaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns the total amount received by the given Verus address in transactions with at least `minconf` confirmations.

**Syntax**

```
getreceivedbyaddress "address" ( minconf )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | The Verus address |
| 2 | minconf | numeric | No | Minimum confirmations (default: 1) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | numeric | Total amount in VRSC received at this address |

**Examples**

```bash
verus getreceivedbyaddress "<R-address>"
```

**Live output (testnet):**
```
520.23650000
```

```bash
## With minimum 6 confirmations
verus getreceivedbyaddress "<R-address>" 6
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid address | Address not in wallet or malformed |

**Related Commands**

- [`getreceivedbyaccount`](#getreceivedbyaccount) — Get received by account (deprecated)
- [`listreceivedbyaddress`](#listreceivedbyaddress) — List received by all addresses
- [`z_getbalance`](#z_getbalance) — Get balance for any address type

**Notes**

- Only counts received amounts, not current balance (doesn't subtract sends).
- Address must belong to the wallet.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## gettransaction

> **Category:** Wallet | **Version:** v1.2.x+

Get detailed information about an in-wallet transaction.

**Syntax**

```
gettransaction "txid" ( includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | txid | string | Yes | — | The transaction id. |
| 2 | includeWatchonly | bool | No | false | Include watch-only addresses in balance/details. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| amount | numeric | Net transaction amount in VRSCTEST |
| fee | numeric | Fee paid (negative, send only) |
| confirmations | numeric | Number of confirmations |
| blockhash | string | Block hash containing the tx |
| blockindex | numeric | Index within the block |
| blocktime | numeric | Block time (epoch seconds) |
| txid | string | Transaction id |
| time | numeric | Transaction time (epoch) |
| timereceived | numeric | Time received (epoch) |
| details | array | Array of send/receive detail objects |
| vjoinsplit | array | Shielded join-split details |
| hex | string | Raw transaction hex |

**Examples**

**Basic Usage**

```bash
verus -testnet gettransaction "<txid>"
```

**Output (trimmed):**
```json
{
  "amount": 0.00000000,
  "fee": -0.00100000,
  "confirmations": 326,
  "blockhash": "<blockhash>",
  "blockindex": 1,
  "blocktime": 1770429214,
  "txid": "<txid>",
  "details": [
    {
      "account": "",
      "address": "<R-address>",
      "category": "send",
      "amount": -0.92700000,
      "vout": 1,
      "fee": -0.00100000
    }
  ]
}
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"gettransaction","params":["<txid>"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Payment verification** — confirm a tx has enough confirmations
- **Transaction debugging** — inspect details, fee, block placement
- **Accounting** — extract send/receive details for records

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid or non-wallet transaction id` | The txid is not in this wallet |

**Related Commands**

- [`listtransactions`](#listtransactions) — List recent transactions
- [`sendtoaddress`](#sendtoaddress) — Create a transaction

**Notes**

- Only works for transactions that involve this wallet's addresses.
- The `amount` field shows the **net** effect (send + receive can cancel out to 0 for self-sends).

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getunconfirmedbalance

> **Category:** Wallet | **Version:** v1.2.x+

Returns the server's total unconfirmed balance.

**Syntax**

```
getunconfirmedbalance
```

**Parameters**

None.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| amount | numeric | Total unconfirmed balance in VRSCTEST. |

**Examples**

**Basic Usage**

```bash
verus -testnet getunconfirmedbalance
```

**Output:**
```
0.00000000
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getunconfirmedbalance","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Monitor incoming payments** — check if funds are pending
- **Transaction confirmation tracking** — poll until unconfirmed drops to 0

**Common Errors**

None typical — this command takes no arguments.

**Related Commands**

- [`getbalance`](#getbalance) — Confirmed balance
- [`getwalletinfo`](#getwalletinfo) — Includes both confirmed and unconfirmed

**Notes**

- Returns only the unconfirmed portion. Use `getbalance` for confirmed funds.
- A non-zero value means transactions are waiting for block inclusion.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## getwalletinfo

> **Category:** Wallet | **Version:** v1.2.x+

Returns an object containing various wallet state info.

**Syntax**

```
getwalletinfo
```

**Parameters**

None.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| walletversion | numeric | Wallet version |
| balance | numeric | Total confirmed balance |
| unconfirmed_balance | numeric | Total unconfirmed balance |
| immature_balance | numeric | Total immature (coinbase) balance |
| reserve_balance | object | PBaaS reserve token balances |
| unconfirmed_reserve_balance | object | Unconfirmed reserve token balances |
| immature_reserve_balance | object | Immature reserve token balances |
| eligible_staking_outputs | numeric | Number of outputs eligible for staking |
| eligible_staking_balance | numeric | Total balance eligible for staking |
| txcount | numeric | Total transaction count |
| keypoololdest | numeric | Timestamp of oldest pre-generated key |
| keypoolsize | numeric | Number of pre-generated keys |
| unlocked_until | numeric | Unlock expiry (0 if locked) |
| paytxfee | numeric | Transaction fee config (VRSC/kB) |
| seedfp | string | BLAKE2b-256 hash of HD seed |

**Examples**

**Basic Usage**

```bash
verus -testnet getwalletinfo
```

**Output:**
```json
{
  "walletversion": 60000,
  "balance": 122.88450000,
  "unconfirmed_balance": 0.00000000,
  "immature_balance": 0.00000000,
  "eligible_staking_outputs": 8,
  "eligible_staking_balance": 122.88450000,
  "reserve_balance": {
    "yourapp": 210.00000000
  },
  "txcount": 57,
  "keypoololdest": 1770080498,
  "keypoolsize": 101,
  "paytxfee": 0.00010000,
  "seedfp": "2187fa609bc5b8507d961fa009ee7acd8658964e1dc4a4ef1e04a63a805811de"
}
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"getwalletinfo","params":[]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Wallet health check** — verify balance, tx count, key pool status
- **Staking info** — check eligible staking balance and output count
- **Reserve balances** — see PBaaS token holdings
- **Security audit** — check if wallet is locked (`unlocked_until`)

**Common Errors**

None typical — this command takes no arguments.

**Related Commands**

- [`getbalance`](#getbalance) — Simple balance query
- [`getunconfirmedbalance`](#getunconfirmedbalance) — Unconfirmed only
- [`listtransactions`](#listtransactions) — Transaction history

**Notes**

- `reserve_balance` only appears on PBaaS-enabled chains with non-native tokens.
- `seedfp` is a fingerprint of the HD seed — useful for verifying wallet identity without exposing the seed.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## importaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Adds an address or script (in hex) that can be watched as if it were in your wallet but cannot be used to spend. Creates a watch-only entry.

**Syntax**

```
importaddress "address" ( "label" rescan )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | The address or hex script to watch |
| 2 | label | string | No | Optional label (default: `""`) |
| 3 | rescan | boolean | No | Rescan wallet for transactions (default: `true`) |

**Result**

No return value on success.

**Examples**

```bash
## Import with rescan
verus importaddress "RAddr..."

## Import without rescan (faster)
verus importaddress "RAddr..." "my-watch" false
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Rescan timeout | Large blockchain + rescan=true can take very long |

**Related Commands**

- [`importprivkey`](#importprivkey) — Import spendable private key
- [`z_importviewingkey`](#z_importviewingkey) — Import shielded viewing key (watch-only)

**Notes**

- Watch-only addresses show in balance with `includeWatchonly` flag.
- Rescan can take minutes to hours on large chains — use `rescan=false` and rescan later if needed.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## importprivkey

> **Category:** Wallet | **Version:** v1.2.x+

Adds a private key (as returned by `dumpprivkey`) to your wallet.

**Syntax**

```
importprivkey "verusprivkey" ( "label" rescan )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | verusprivkey | string | Yes | — | The WIF-encoded private key. |
| 2 | label | string | No | `""` | An optional label for the address. |
| 3 | rescan | boolean | No | true | Rescan the blockchain for transactions. |

**Result**

None (returns null on success).

**Examples**

**Basic Usage**

```bash
verus -testnet importprivkey "myWIFkey"
```

**Import Without Rescan**

```bash
verus -testnet importprivkey "myWIFkey" "testing" false
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"importprivkey","params":["myWIFkey","testing",false]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Wallet migration** — import keys exported from another wallet
- **Key recovery** — restore access from a backed-up private key
- **Fast import** — use `rescan=false` when importing multiple keys, then rescan once at the end

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid private key encoding` | Key is not valid WIF format |
| `Wallet is locked` | Unlock with `walletpassphrase` first |

**Related Commands**

- [`dumpprivkey`](#dumpprivkey) — Export a private key
- [`importaddress`](wallet.md#importaddress) — Import watch-only address

**Notes**

> ⚠️ **WARNING:** With `rescan=true` (default), this call can take **minutes** as it scans the entire blockchain for transactions involving the imported key.

- If importing multiple keys, set `rescan=false` for all but the last import, or trigger a manual rescan afterward.
- The imported key becomes part of the wallet's keystore permanently.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## importwallet

> **Category:** Wallet | **Version:** v1.2.14-2+

Imports transparent address (taddr) keys from a wallet dump file created by `dumpwallet`.

**Syntax**

```
importwallet "filename"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | filename | string | Yes | Path to the wallet dump file |

**Result**

No return value on success.

**Examples**

```bash
## Dump then import
verus dumpwallet "mybackup"
verus importwallet "/path/to/exportdir/mybackup"
```

**Related Commands**

- [`dumpwallet`](#dumpwallet) — Export taddr keys to file
- [`z_importwallet`](#z_importwallet) — Import both taddr and zaddr keys

**Notes**

- Only imports transparent keys. Use `z_importwallet` for full import (taddr + zaddr).
- Triggers a rescan after import.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## keypoolrefill

> **Category:** Wallet | **Version:** v1.2.14-2+

Fills the keypool with pre-generated keys for faster address generation.

**Syntax**

```
keypoolrefill ( newsize )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | newsize | numeric | No | New keypool size (default: 100) |

**Result**

No return value on success.

**Examples**

```bash
verus keypoolrefill
verus keypoolrefill 200
```

**Live test (testnet):** Completed successfully with no output.

**Related Commands**

- [`getwalletinfo`](#getwalletinfo) — Shows current keypool size

**Notes**

- Pre-generating keys improves address generation speed.
- Useful before operations that need many new addresses.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listaccounts

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Returns an object with account names as keys and account balances as values.

**Syntax**

```
listaccounts ( minconf includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 2 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

JSON object mapping account names to balances.

**Examples**

```bash
verus listaccounts
```

**Live output (testnet):**
```json
{
  "": -404.33180000,
  "bootstrap-test": 0.00000000,
  "yourapp-registration": 527.21640000
}
```

**Related Commands**

- [`getaccount`](#getaccount) — Get account for address (deprecated)
- [`listreceivedbyaccount`](#listreceivedbyaccount) — Detailed received by account (deprecated)

**Notes**

- The account system is **deprecated**. Negative balances can occur due to the accounting model.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listaddressgroupings

> **Category:** Wallet | **Version:** v1.2.14-2+

Lists groups of addresses whose common ownership has been made public by being used together as inputs or change in past transactions.

**Syntax**

```
listaddressgroupings
```

**Parameters**

None.

**Result**

Nested JSON array: groups of `[address, amount, account]` tuples.

**Examples**

```bash
verus listaddressgroupings
```

**Live output (testnet, partial):**
```json
[
  [
    ["<R-address>", 52.88540000, "yourapp-registration"],
    ["<R-address>", 0.00000000, ""],
    ["<R-address>", 0.00000000, ""]
  ]
]
```

**Related Commands**

- [`listunspent`](#listunspent) — List unspent outputs
- [`listreceivedbyaddress`](#listreceivedbyaddress) — List received by address

**Notes**

- Reveals privacy information — addresses grouped together were likely controlled by the same user.
- The `account` field in each tuple is deprecated.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listlockunspent

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns a list of temporarily unspendable (locked) outputs. See `lockunspent` to lock/unlock.

**Syntax**

```
listlockunspent
```

**Parameters**

None.

**Result**

JSON array of locked outputs, each with `txid` and `vout`.

**Examples**

```bash
verus listlockunspent
```

**Live output (testnet):**
```json
[]
```

**Related Commands**

- [`lockunspent`](#lockunspent) — Lock/unlock specific outputs
- [`listunspent`](#listunspent) — List spendable outputs

**Notes**

- Locks are stored in memory only — cleared on node restart.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listreceivedbyaccount

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** List balances by account.

**Syntax**

```
listreceivedbyaccount ( minconf includeempty includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 2 | includeempty | boolean | No | Include accounts with no payments (default: false) |
| 3 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

JSON array of objects with `account`, `amount`, `confirmations`, and optionally `involvesWatchonly`.

**Examples**

```bash
verus listreceivedbyaccount
```

**Live output (testnet):**
```json
[
  {
    "account": "",
    "amount": 766.98690000,
    "confirmations": 1448
  },
  {
    "account": "yourapp-registration",
    "amount": 527.21640000,
    "confirmations": 333
  }
]
```

**Related Commands**

- [`listreceivedbyaddress`](#listreceivedbyaddress) — List received by address
- [`listaccounts`](#listaccounts) — List account balances (deprecated)

**Notes**

- The account system is **deprecated**.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listreceivedbyaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

List balances by receiving address.

**Syntax**

```
listreceivedbyaddress ( minconf includeempty includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 2 | includeempty | boolean | No | Include addresses with no payments (default: false) |
| 3 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

JSON array of objects:

| Field | Type | Description |
|-------|------|-------------|
| address | string | The receiving address |
| account | string | DEPRECATED. The account name |
| amount | numeric | Total amount received |
| confirmations | numeric | Number of confirmations of the most recent included tx |
| txids | array | Array of transaction IDs contributing to the balance |

**Examples**

```bash
verus listreceivedbyaddress
verus listreceivedbyaddress 6 true
```

**Live output (testnet, partial):**
```json
[
  {
    "address": "<R-address>",
    "account": "yourapp-registration",
    "amount": 527.21640000,
    "confirmations": 333,
    "txids": ["<txid>", "<txid>"]
  }
]
```

**Related Commands**

- [`listreceivedbyaccount`](#listreceivedbyaccount) — List by account (deprecated)
- [`getreceivedbyaddress`](#getreceivedbyaddress) — Get total for single address

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## listsinceblock

> **Category:** Wallet | **Version:** v1.2.14-2+

Get all transactions in blocks since a specified block hash, or all transactions if omitted.

**Syntax**

```
listsinceblock ( "blockhash" target-confirmations includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | blockhash | string | No | List transactions since this block |
| 2 | target-confirmations | numeric | No | Minimum confirmations required (≥1) |
| 3 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| transactions | array | Array of transaction objects |
| lastblock | string | Hash of the last block |

Each transaction contains: `account`, `address`, `category` (send/receive), `amount`, `vout`, `fee`, `confirmations`, `blockhash`, `blockindex`, `blocktime`, `txid`, `time`, `timereceived`.

**Examples**

```bash
## All transactions
verus listsinceblock

## Since a specific block with 6 confirmations
verus listsinceblock "000000000000000bacf66f7497b7dc45ef753ee9a7d38571037cdb1a57f663ad" 6
```

**Related Commands**

- [`listtransactions`](#listtransactions) — List recent transactions
- [`gettransaction`](#gettransaction) — Get single transaction details

**Notes**

- Useful for tracking new transactions since a known block.
- Can return very large result sets if no blockhash is specified.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## listtransactions

> **Category:** Wallet | **Version:** v1.2.x+

Returns up to `count` most recent transactions, optionally skipping the first `from`.

**Syntax**

```
listtransactions ( "account" count from includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | account | string | No | `"*"` | DEPRECATED. Use `"*"` for all accounts. Also accepts `'{queryobject}'` JSON filter syntax. |
| 2 | count | numeric | No | 10 | Number of transactions to return. |
| 3 | from | numeric | No | 0 | Number of transactions to skip. |
| 4 | includeWatchonly | bool | No | false | Include watch-only addresses. |

**Result**

Array of transaction objects with fields: `account`, `address`, `category` (send/receive/move), `amount`, `vout`, `fee`, `confirmations`, `blockhash`, `blockindex`, `txid`, `time`, `timereceived`, `comment`, `otheraccount` (for category "move"), `size`.

**Examples**

**Basic Usage**

```bash
verus -testnet listtransactions "*" 3
```

**Output (trimmed):**
```json
[
  {
    "account": "",
    "address": "<R-address>",
    "category": "send",
    "amount": -0.92700000,
    "vout": 1,
    "fee": -0.00100000,
    "confirmations": 326,
    "txid": "<txid>",
    "time": 1770429209,
    "size": 1155
  }
]
```

**Pagination**

```bash
verus -testnet listtransactions "*" 20 100
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"listtransactions","params":["*",20,100]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Transaction history** — display recent wallet activity
- **Pagination** — use `from` to page through history
- **Payment monitoring** — poll for new incoming transactions

**Common Errors**

| Error | Cause |
|-------|-------|
| `Negative from` | The `from` parameter must be ≥ 0 |

**Related Commands**

- [`gettransaction`](#gettransaction) — Detailed info for a specific tx
- [`listunspent`](#listunspent) — List spendable UTXOs

**Notes**

- Both `send` and `receive` entries appear for self-sends.
- The `account` parameter is deprecated — use `"*"`.
- Results are ordered newest-first.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## listunspent

> **Category:** Wallet | **Version:** v1.2.x+

Returns array of unspent transaction outputs (UTXOs) with between minconf and maxconf confirmations.

**Syntax**

```
listunspent ( minconf maxconf ["address",...] includeshared )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | minconf | numeric | No | 1 | Minimum confirmations. |
| 2 | maxconf | numeric | No | 9999999 | Maximum confirmations. |
| 3 | addresses | array | No | — | Filter by specific addresses. |
| 4 | includeshared | bool | No | false | Include outputs spendable by others. |

**Result**

Array of UTXO objects:

| Field | Type | Description |
|-------|------|-------------|
| txid | string | Transaction ID |
| vout | numeric | Output index |
| generated | boolean | True if coinbase/staking output |
| address | string | Address of the output |
| account | string | DEPRECATED. Associated account |
| scriptPubKey | string | Hex-encoded script |
| amount | numeric | Amount in native currency |
| currencyvalues | object | Non-native token amounts (if present) |
| confirmations | numeric | Number of confirmations |
| redeemScript | string | Redeem script (if P2SH) |
| spendable | boolean | Whether the wallet can spend this output |

**Examples**

**Basic Usage**

```bash
verus -testnet listunspent
```

**Output (first entry):**
```json
[
  {
    "txid": "<txid>",
    "vout": 2,
    "generated": false,
    "address": "<R-address>",
    "account": "yourapp-registration",
    "amount": 1.00000000,
    "confirmations": 649,
    "spendable": true
  }
]
```

**Filter by Address**

```bash
verus -testnet listunspent 6 9999999 '["<R-address>"]'
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"listunspent","params":[6,9999999,["<R-address>"]]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **UTXO management** — inspect available inputs before raw transactions
- **Coin selection** — find UTXOs of specific sizes
- **Multi-currency** — `currencyvalues` shows non-native token amounts
- **Address audit** — filter UTXOs by address

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid address` | Address in filter array is malformed |

**Related Commands**

- [`getbalance`](#getbalance) — Summarized balance
- [`getcurrencybalance`](#getcurrencybalance) — Per-address currency balances
- [`gettransaction`](#gettransaction) — Details for a specific tx

**Notes**

- UTXOs with `currencyvalues` may show `amount: 0.00000000` for the native coin while holding non-native tokens.
- The `generated` field indicates coinbase (mining/staking) outputs.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## lockunspent

> **Category:** Wallet | **Version:** v1.2.14-2+

Temporarily lock or unlock specified transaction outputs. Locked outputs are excluded from automatic coin selection when spending.

**Syntax**

```
lockunspent unlock [{"txid":"txid","vout":n},...]
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | unlock | boolean | Yes | `true` to unlock, `false` to lock |
| 2 | transactions | JSON array | Yes | Array of `{txid, vout}` objects |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | boolean | `true` if successful |

**Examples**

```bash
## Lock an output
verus lockunspent false '[{"txid":"a08e6907...","vout":1}]'

## Unlock it
verus lockunspent true '[{"txid":"a08e6907...","vout":1}]'
```

**Related Commands**

- [`listlockunspent`](#listlockunspent) — List currently locked outputs
- [`listunspent`](#listunspent) — List spendable outputs

**Notes**

- Locks are **in-memory only** — cleared on node restart.
- Useful for reserving specific UTXOs for manual transaction construction.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## move

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Move a specified amount from one account to another within the wallet. This is purely an accounting operation — no on-chain transaction is created.

**Syntax**

```
move "fromaccount" "toaccount" amount ( minconf "comment" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | fromaccount | string | Yes | Must be `""` for default account |
| 2 | toaccount | string | Yes | Must be `""` for default account |
| 3 | amount | numeric | Yes | Amount to move |
| 4 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 5 | comment | string | No | Optional comment |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | boolean | `true` if successful |

**Related Commands**

- [`listaccounts`](#listaccounts) — List account balances (deprecated)
- [`setaccount`](#setaccount) — Set account for address (deprecated)

**Notes**

- The account system is **deprecated**. This command only adjusts internal accounting labels.
- No blockchain transaction is created — this is purely a wallet-internal operation.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## prunespentwallettransactions

> **Category:** Wallet | **Version:** v1.2.14-2+

Remove all spent transactions from the wallet database. Optionally keep a specific transaction. **Back up your wallet.dat before running.**

**Syntax**

```
prunespentwallettransactions ( "txid" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | txid | string | No | Transaction ID to keep (preserve this one) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| total_transactions | numeric | Total transactions before pruning |
| remaining_transactions | numeric | Transactions remaining after pruning |
| removed_transactions | numeric | Number of transactions removed |

**Examples**

```bash
## Prune all spent transactions
verus prunespentwallettransactions

## Prune but keep a specific tx
verus prunespentwallettransactions "1075db55d416d3ca..."
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Wallet corruption | Always backup wallet.dat first |

**Related Commands**

- [`backupwallet`](#backupwallet) — Backup wallet before pruning
- [`listtransactions`](#listtransactions) — List wallet transactions

**Notes**

- ⚠️ **Destructive operation** — always `backupwallet` first.
- Reduces wallet.dat size for wallets with many historical transactions.
- Improves wallet performance by removing unnecessary transaction data.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## rescanfromheight

> **Category:** Wallet | **Version:** v1.2.14-2+

Rescans the blockchain from a specified height to find wallet transactions. Useful after importing keys.

**Syntax**

```
rescanfromheight ( height )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | height | numeric | No | Block height to start from (default: 0) |

**Result**

No return value documented.

**Examples**

```bash
## Rescan entire chain
verus rescanfromheight

## Rescan from block 1000000
verus rescanfromheight 1000000
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Long execution time | Rescanning large portions of the chain |

**Related Commands**

- [`importprivkey`](#importprivkey) — Import key (triggers optional rescan)
- [`importaddress`](#importaddress) — Import watch-only address
- [`z_importkey`](#z_importkey) — Import shielded key

**Notes**

- ⚠️ Can take **minutes to hours** on large wallets or full chain rescans.
- Use a specific height to limit scan time (e.g., the block when the key was first used).

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## resendwallettransactions

> **Category:** Wallet | **Version:** v1.2.14-2+

Immediately re-broadcasts unconfirmed wallet transactions to all peers. Intended for testing — the wallet periodically re-broadcasts automatically.

**Syntax**

```
resendwallettransactions
```

**Parameters**

None.

**Result**

JSON array of transaction IDs that were re-broadcast.

**Examples**

```bash
verus resendwallettransactions
```

**Live output (testnet):**
```json
[]
```

**Related Commands**

- [`listtransactions`](#listtransactions) — List wallet transactions
- [`gettransaction`](#gettransaction) — Get transaction details

**Notes**

- The wallet automatically re-broadcasts unconfirmed transactions periodically.
- This command forces an immediate re-broadcast — mainly useful for testing/debugging.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## sendfrom

> **Category:** Wallet | **Version:** v1.2.x+ | ⚠️ **DEPRECATED**

Send an amount from an account to a VRSCTEST address. Use `sendtoaddress` instead.

**Syntax**

```
sendfrom "fromaccount" "toVRSCTESTaddress" amount ( minconf "comment" "comment-to" )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | fromaccount | string | Yes | — | MUST be `""` for default account. |
| 2 | toVRSCTESTaddress | string | Yes | — | The destination address. |
| 3 | amount | numeric | Yes | — | Amount in VRSCTEST (fee added on top). |
| 4 | minconf | numeric | No | 1 | Minimum confirmations on inputs. |
| 5 | comment | string | No | — | Wallet-only comment. |
| 6 | comment-to | string | No | — | Wallet-only recipient note. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| transactionid | string | The transaction id. |

**Examples**

**Basic Usage**

```bash
verus -testnet sendfrom "" "RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV" 0.01
```

**With Confirmations and Comments**

```bash
verus -testnet sendfrom "" "RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV" 0.01 6 "donation" "seans outpost"
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"sendfrom","params":["","RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV",0.01,6,"donation","seans outpost"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid account name` | Using an account name other than `""` |
| `Insufficient funds` | Not enough confirmed balance |

**Related Commands**

- [`sendtoaddress`](#sendtoaddress) — Preferred replacement
- [`sendmany`](#sendmany) — Send to multiple addresses

**Notes**

- **DEPRECATED** — use `sendtoaddress` for all new code.
- The `fromaccount` parameter must be `""`. Named accounts are no longer supported.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## sendmany

> **Category:** Wallet | **Version:** v1.2.x+

Send to multiple addresses in a single transaction.

**Syntax**

```
sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | fromaccount | string | Yes | — | MUST be `""` for default account. |
| 2 | amounts | object | Yes | — | JSON object: `{"address": amount, ...}` |
| 3 | minconf | numeric | No | 1 | Minimum confirmations on inputs. |
| 4 | comment | string | No | — | Wallet-only comment. |
| 5 | subtractfeefromamount | array | No | — | Array of addresses to subtract fee from. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| transactionid | string | The transaction id (single tx for all recipients). |

**Examples**

**Basic Usage**

```bash
verus -testnet sendmany "" '{"RAddr1":0.01,"RAddr2":0.02}'
```

**With Comment**

```bash
verus -testnet sendmany "" '{"RAddr1":0.01,"RAddr2":0.02}' 6 "testing"
```

**Subtract Fee from Recipients**

```bash
verus -testnet sendmany "" '{"RAddr1":0.01,"RAddr2":0.02}' 1 "" '["RAddr1","RAddr2"]'
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"sendmany","params":["",{"RAddr1":0.01,"RAddr2":0.02},6,"testing"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Batch payments** — pay multiple recipients in one transaction (saves fees)
- **Payroll / distributions** — send to many addresses at once
- **Fee splitting** — deduct fee proportionally from selected recipients

**Common Errors**

| Error | Cause |
|-------|-------|
| `Invalid account name` | Using anything other than `""` |
| `Insufficient funds` | Total amounts + fee exceeds balance |
| `Invalid address` | One or more addresses are malformed |
| `Transaction too large` | Too many inputs/outputs |

**Related Commands**

- [`sendtoaddress`](#sendtoaddress) — Send to a single address
- [`listunspent`](#listunspent) — Check available UTXOs

**Notes**

- Creates a single transaction regardless of recipient count — more efficient than multiple `sendtoaddress` calls.
- The `fromaccount` parameter must be `""`.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## sendtoaddress

> **Category:** Wallet | **Version:** v1.2.x+

Send an amount to a given address. The amount is rounded to the nearest 0.00000001.

**Syntax**

```
sendtoaddress "VRSCTEST_address" amount ( "comment" "comment-to" subtractfeefromamount )
```

**Parameters**

| # | Name | Type | Required | Default | Description |
|---|------|------|----------|---------|-------------|
| 1 | address | string | Yes | — | The VRSCTEST address to send to. |
| 2 | amount | numeric | Yes | — | The amount in VRSCTEST to send (e.g. `0.1`). |
| 3 | comment | string | No | — | A wallet-only comment describing the transaction. |
| 4 | comment-to | string | No | — | A wallet-only note about the recipient. |
| 5 | subtractfeefromamount | boolean | No | false | If true, the fee is deducted from the amount sent. |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| transactionid | string | The transaction id (txid). |

**Examples**

**Basic Usage**

```bash
verus -testnet sendtoaddress "RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV" 0.1
```

**With Comment**

```bash
verus -testnet sendtoaddress "RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV" 0.1 "donation" "seans outpost"
```

**Subtract Fee from Amount**

```bash
verus -testnet sendtoaddress "RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV" 0.1 "" "" true
```

**RPC (curl)**

```bash
curl --user user:pass --data-binary \
  '{"jsonrpc":"1.0","id":"curltest","method":"sendtoaddress","params":["RD6GgnrMpPaTSMn8vai6yiGA7mN4QGPV",0.1,"donation","seans outpost"]}' \
  -H 'content-type:text/plain;' http://127.0.0.1:18843/
```

**Common Use Cases**

- **Simple payments** — send VRSCTEST to another address
- **Fee management** — use `subtractfeefromamount` to send exact wallet balance
- **Annotated transactions** — add comments for record-keeping

**Common Errors**

| Error | Cause |
|-------|-------|
| `Insufficient funds` | Wallet balance too low for amount + fee |
| `Invalid Verus address` | Address format is wrong or not valid |
| `Amount out of range` | Negative or excessively large amount |
| `Transaction too large` | Too many inputs required — consolidate UTXOs first |

**Related Commands**

- [`sendfrom`](#sendfrom) — Send from a specific account (deprecated)
- [`sendmany`](#sendmany) — Send to multiple addresses in one transaction
- [`gettransaction`](#gettransaction) — Look up the resulting transaction
- [`getbalance`](#getbalance) — Check available balance first

**Notes**

- Comments are stored locally in the wallet only — they are **not** on the blockchain.
- The wallet must be unlocked if encrypted.
- Transaction fee is set by `paytxfee` or estimated automatically.

**Tested On**

- **Network:** VRSCTEST (testnet)
- **Version:** 1.2.14-2
- **Block Height:** 926990

---

## setaccount

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Sets the account associated with the given address.

**Syntax**

```
setaccount "address" "account"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | The Verus address |
| 2 | account | string | Yes | Must be `""` for default account |

**Result**

No return value on success.

**Related Commands**

- [`getaccount`](#getaccount) — Get account for address (deprecated)
- [`listaccounts`](#listaccounts) — List all accounts (deprecated)

**Notes**

- The account system is **deprecated**.
- Only `""` (empty string) is accepted as the account parameter.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## settxfee

> **Category:** Wallet | **Version:** v1.2.14-2+

Set the transaction fee per kilobyte for wallet transactions.

**Syntax**

```
settxfee amount
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | amount | numeric | Yes | Fee in VRSC/kB (rounded to nearest 0.00000001) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | boolean | `true` if successful |

**Examples**

```bash
verus settxfee 0.0001
```

**Live output (testnet):**
```
true
```

**Related Commands**

- [`getwalletinfo`](#getwalletinfo) — Shows current fee settings
- [`sendtoaddress`](#sendtoaddress) — Send transaction (uses this fee)

**Notes**

- Affects all subsequent wallet transactions until changed or node restart.
- Default fee is typically 0.0001 VRSC/kB.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_exportkey

> **Category:** Wallet | **Version:** v1.2.14-2+

Reveals the spending key for a shielded (z) address. The key can be imported with `z_importkey`.

**Syntax**

```
z_exportkey "zaddr" ( outputashex )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | zaddr | string | Yes | The shielded address |
| 2 | outputashex | boolean | No | Output key as hex bytes (default: false) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | The private spending key |

**Examples**

```bash
verus z_exportkey "zs1..."
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid zaddr | Address not in wallet or malformed |

**Related Commands**

- [`z_importkey`](#z_importkey) — Import a shielded spending key
- [`z_exportviewingkey`](#z_exportviewingkey) — Export viewing key (read-only)
- [`dumpprivkey`](#dumpprivkey) — Export transparent address key

**Notes**

- **Security-sensitive** — the exported key grants full spending access.
- Keep exported keys secure and never share publicly.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_exportviewingkey

> **Category:** Wallet | **Version:** v1.2.14-2+

Reveals the viewing key for a shielded (z) address. Viewing keys allow monitoring incoming transactions without spending ability.

**Syntax**

```
z_exportviewingkey "zaddr"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | zaddr | string | Yes | The shielded address |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | The viewing key |

**Examples**

```bash
verus z_exportviewingkey "zs1jqpysk8t5tzfe2rs25qkf0t6pzt3xdc7cjemn2x67zs0txfv4fq6d5qklq9pet6nwr556u0mywj"
```

**Related Commands**

- [`z_importviewingkey`](#z_importviewingkey) — Import a viewing key
- [`z_exportkey`](#z_exportkey) — Export full spending key

**Notes**

- Viewing keys can see incoming funds but **cannot detect spends** — reported balance may be higher than actual.
- Safer to share than spending keys for monitoring purposes.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_exportwallet

> **Category:** Wallet | **Version:** v1.2.14-2+

Exports all wallet keys (both taddr and zaddr) in a human-readable format to a file. More complete than `dumpwallet`.

**Syntax**

```
z_exportwallet "filename" ( omitemptytaddresses )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | filename | string | Yes | Output filename (saved in `-exportdir` folder) |
| 2 | omitemptytaddresses | boolean | No | Only export addresses with UTXOs or IDs (default: false) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| path | string | Full path of the destination file |

**Examples**

```bash
verus z_exportwallet "full-backup"
```

**Common Errors**

| Error | Cause |
|-------|-------|
| `Cannot overwrite existing file` | File already exists |
| `exportdir` not configured | Start verusd with `-exportdir` |

**Related Commands**

- [`z_importwallet`](#z_importwallet) — Import from export file
- [`dumpwallet`](#dumpwallet) — Export taddr keys only
- [`backupwallet`](#backupwallet) — Copy wallet.dat

**Notes**

- Includes both transparent and shielded keys — **most complete export option**.
- Requires `-exportdir` to be set.
- Cannot overwrite existing files.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_getbalance

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns the balance of a transparent or shielded address belonging to the wallet. Supports wildcards.

**Syntax**

```
z_getbalance "address" ( minconf )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | Address (t-addr, z-addr, or wildcards: `z*`, `R*`, `i*`) |
| 2 | minconf | numeric | No | Minimum confirmations (default: 1) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | numeric | Total balance in VRSC |

**Examples**

```bash
verus z_getbalance "zs1..."
verus z_getbalance "zs1..." 5
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid address | Address not in wallet |

**Related Commands**

- [`z_gettotalbalance`](#z_gettotalbalance) — Get combined transparent + private balance
- [`getbalance`](#getbalance) — Get transparent balance
- [`z_listunspent`](#z_listunspent) — List shielded unspent notes

**Notes**

- ⚠️ If wallet only has a viewing key (not spending key), spends cannot be detected — balance may appear higher than actual.
- Supports wildcard patterns: `z*` (all z-addresses), `R*` (all R-addresses), `i*` (all i-addresses).

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_getencryptionaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Derives an encryption z-address from a wallet address, seed, or extended key, optionally scoped between two VerusIDs. Returns viewing key and optionally the spending key.

**Syntax**

```
z_getencryptionaddress '{
  "address": "zaddress",
  "seed": "wallet seed",
  "hdindex": n,
  "rootkey": "extended private key",
  "fromid": "id@",
  "toid": "id@",
  "encryptionindex": n,
  "returnsecret": true|false
}'
```

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | Optional* | z-address present in wallet |
| seed | string | Optional* | Raw wallet seed |
| hdindex | numeric | No | Address index to derive from seed (default: 0) |
| rootkey | string | Optional* | Extended private key |
| fromid | string | No | Source VerusID for scoped key derivation |
| toid | string | No | Target VerusID for scoped key derivation |
| encryptionindex | numeric | No | Index for deriving final encryption address (default: 0) |
| returnsecret | boolean | No | Return extended spending key (default: false) |

*One of `address`, `seed`, or `rootkey` is required.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| extendedviewingkey | string | Sapling extended viewing key |
| incomingviewingkey | string | Sapling hex incoming viewing key |
| address | string | The derived encryption address |
| extendedspendingkey | string | Spending key (only if `returnsecret: true`) |

**Examples**

```bash
verus z_getencryptionaddress '{"address":"zs1...","fromid":"bob@","toid":"alice@"}'
```

**Related Commands**

- [`decryptdata`](#decryptdata) — Decrypt data encrypted to a z-address
- [`signdata`](identity.md#signdata) — Sign/encrypt data
- [`z_getnewaddress`](#z_getnewaddress) — Generate new z-address

**Notes**

- Part of Verus's identity-linked encryption system.
- The `fromid`/`toid` scoping creates deterministic encryption addresses for communication between two identities.
- Useful for VDXF encrypted data exchange.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_getmigrationstatus

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns information about the status of Sprout to Sapling migration.

**Syntax**

```
z_getmigrationstatus
```

**Parameters**

None.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| enabled | boolean | Whether migration is enabled |
| destination_address | string | Sapling address receiving Sprout funds |
| unmigrated_amount | numeric | Total unmigrated VRSC |
| unfinalized_migrated_amount | numeric | Migrated but < 10 confirmations |
| finalized_migrated_amount | numeric | Migrated with ≥ 10 confirmations |
| finalized_migration_transactions | numeric | Number of finalized migration txs |
| time_started | numeric | Unix timestamp of first migration tx (optional) |
| migration_txids | array | All migration transaction IDs |

**Examples**

```bash
verus z_getmigrationstatus
```

**Live output (testnet):**
```json
{
  "enabled": false,
  "destination_address": "zs1jqpysk8t5tzfe2rs25qkf0t6pzt3xdc7cjemn2x67zs0txfv4fq6d5qklq9pet6nwr556u0mywj",
  "unmigrated_amount": "0.00",
  "unfinalized_migrated_amount": "0.00",
  "finalized_migrated_amount": "0.00",
  "finalized_migration_transactions": 0,
  "migration_txids": []
}
```

**Related Commands**

- [`z_setmigration`](#z_setmigration) — Enable/disable migration

**Notes**

- A transaction is "finalized" when it has ≥ 10 confirmations.
- Migration sends up to 5 transactions per interval (every 500 blocks at height ≡ 499 mod 500).
- Ends when Sprout balance falls below 0.01 VRSC.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_getnewaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns a new shielded address for receiving payments. Defaults to Sapling type.

**Syntax**

```
z_getnewaddress ( "type" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | type | string | No | Address type: `"sapling"` (default) or `"sprout"` |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | New shielded address |

**Examples**

```bash
verus z_getnewaddress
verus z_getnewaddress sapling
```

**Related Commands**

- [`z_listaddresses`](#z_listaddresses) — List all shielded addresses
- [`getnewaddress`](#getnewaddress) — Get new transparent address
- [`z_exportkey`](#z_exportkey) — Export private key for z-address

**Notes**

- Sapling addresses start with `zs1`.
- Sprout addresses are legacy — use Sapling for new addresses.
- Key generation may take a moment due to cryptographic operations.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_getoperationresult

> **Category:** Wallet | **Version:** v1.2.14-2+

Retrieves the result and status of finished operations, then **removes them from memory**. Use `z_getoperationstatus` to check without removing.

**Syntax**

```
z_getoperationresult ( ["operationid", ...] )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | operationid | array | No | List of operation IDs to check. If omitted, returns all. |

**Result**

JSON array of operation result objects with `id`, `status`, `creation_time`, and operation-specific result data.

**Examples**

```bash
## Get all finished operation results
verus z_getoperationresult

## Get specific operation
verus z_getoperationresult '["opid-42f729bf-106a-441e-868e-866a2a2c12ac"]'
```

**Related Commands**

- [`z_getoperationstatus`](#z_getoperationstatus) — Check status without removing
- [`z_listoperationids`](#z_listoperationids) — List all operation IDs
- [`z_sendmany`](#z_sendmany) — Returns an operation ID

**Notes**

- **Removes operations from memory** after returning — use `z_getoperationstatus` if you want to check without clearing.
- Operations include `z_sendmany`, `z_shieldcoinbase`, `z_mergetoaddress` results.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_getoperationstatus

> **Category:** Wallet | **Version:** v1.2.14-2+

Get operation status and any associated result or error data. The operation **remains in memory** (unlike `z_getoperationresult`).

**Syntax**

```
z_getoperationstatus ( ["operationid", ...] )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | operationid | array | No | Operation IDs to check. If omitted, returns all. |

**Result**

JSON array of operation status objects.

**Examples**

```bash
verus z_getoperationstatus
verus z_getoperationstatus '["opid-42f729bf-..."]'
```

**Live output (testnet, partial):**
```json
[
  {
    "id": "opid-42f729bf-106a-441e-868e-866a2a2c12ac",
    "status": "success",
    "creation_time": 1770423015
  }
]
```

**Related Commands**

- [`z_getoperationresult`](#z_getoperationresult) — Get result and remove from memory
- [`z_listoperationids`](#z_listoperationids) — List all operation IDs

**Notes**

- Does NOT remove the operation from memory — safe to call repeatedly.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_gettotalbalance

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns the total value of funds in the wallet, broken down by transparent, private (shielded), and total.

**Syntax**

```
z_gettotalbalance ( minconf includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 2 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| transparent | string | Total transparent balance |
| private | string | Total shielded balance (Sprout + Sapling) |
| total | string | Combined total |

**Examples**

```bash
verus z_gettotalbalance
verus z_gettotalbalance 5
```

**Live output (testnet):**
```json
{
  "transparent": "122.8845",
  "private": "1.00",
  "total": "123.8845"
}
```

**Related Commands**

- [`getbalance`](#getbalance) — Transparent balance only
- [`z_getbalance`](#z_getbalance) — Balance for specific address

**Notes**

- ⚠️ If wallet has viewing-key-only addresses, private balance may be overstated (spends undetectable).
- Values returned as strings, not numbers.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_importkey

> **Category:** Wallet | **Version:** v1.2.14-2+

Imports a shielded spending key (from `z_exportkey`) into the wallet.

**Syntax**

```
z_importkey "zkey" ( rescan startHeight )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | zkey | string | Yes | The spending key |
| 2 | rescan | string | No | `"yes"`, `"no"`, or `"whenkeyisnew"` (default) |
| 3 | startHeight | numeric | No | Block height to start rescan from (default: 0) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| type | string | `"sprout"` or `"sapling"` |
| address | string | Corresponding address |

**Examples**

```bash
## Import with automatic rescan
verus z_importkey "secret-extended-key..."

## Import without rescan
verus z_importkey "secret-extended-key..." no

## Import with partial rescan from height
verus z_importkey "secret-extended-key..." whenkeyisnew 30000
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Invalid spending key | Malformed key string |
| Rescan timeout | Large chain + low startHeight |

**Related Commands**

- [`z_exportkey`](#z_exportkey) — Export spending key
- [`z_importviewingkey`](#z_importviewingkey) — Import viewing key (read-only)
- [`importprivkey`](#importprivkey) — Import transparent key

**Notes**

- Rescan can take minutes to hours depending on startHeight and chain size.
- Use `startHeight` to limit rescan time if you know when the key was first used.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_importviewingkey

> **Category:** Wallet | **Version:** v1.2.14-2+

Imports a shielded viewing key (from `z_exportviewingkey`). Allows monitoring incoming transactions without spending ability.

**Syntax**

```
z_importviewingkey "vkey" ( rescan startHeight )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | vkey | string | Yes | The viewing key |
| 2 | rescan | string | No | `"yes"`, `"no"`, or `"whenkeyisnew"` (default) |
| 3 | startHeight | numeric | No | Block height to start rescan from (default: 0) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| type | string | `"sprout"` or `"sapling"` |
| address | string | Corresponding address |

**Examples**

```bash
verus z_importviewingkey "zxviews1..."
verus z_importviewingkey "zxviews1..." no
verus z_importviewingkey "zxviews1..." whenkeyisnew 30000
```

**Related Commands**

- [`z_exportviewingkey`](#z_exportviewingkey) — Export viewing key
- [`z_importkey`](#z_importkey) — Import full spending key
- [`importaddress`](#importaddress) — Import transparent watch-only

**Notes**

- ⚠️ Viewing keys **cannot detect spends** — balance may appear higher than actual.
- Creates a watch-only shielded address.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_importwallet

> **Category:** Wallet | **Version:** v1.2.14-2+

Imports both transparent and shielded keys from a wallet export file (created by `z_exportwallet`).

**Syntax**

```
z_importwallet "filename"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | filename | string | Yes | Path to the wallet export file |

**Result**

No return value on success.

**Examples**

```bash
verus z_exportwallet "backup"
verus z_importwallet "/path/to/exportdir/backup"
```

**Related Commands**

- [`z_exportwallet`](#z_exportwallet) — Export all keys
- [`importwallet`](#importwallet) — Import taddr keys only

**Notes**

- Imports both taddr and zaddr keys — most complete import option.
- Triggers a wallet rescan.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_listaddresses

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns the list of Sprout and Sapling shielded addresses belonging to the wallet.

**Syntax**

```
z_listaddresses ( includeWatchonly )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | includeWatchonly | boolean | No | Include watch-only addresses (default: false) |

**Result**

JSON array of shielded address strings.

**Examples**

```bash
verus z_listaddresses
```

**Live output (testnet):**
```json
[
  "zs1jqpysk8t5tzfe2rs25qkf0t6pzt3xdc7cjemn2x67zs0txfv4fq6d5qklq9pet6nwr556u0mywj"
]
```

**Related Commands**

- [`z_getnewaddress`](#z_getnewaddress) — Create new shielded address
- [`z_getbalance`](#z_getbalance) — Get balance for an address

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_listoperationids

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns the list of operation IDs currently known to the wallet, optionally filtered by status.

**Syntax**

```
z_listoperationids ( "status" )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | status | string | No | Filter by status (e.g., `"success"`, `"failed"`, `"executing"`) |

**Result**

JSON array of operation ID strings.

**Examples**

```bash
verus z_listoperationids
verus z_listoperationids "success"
```

**Live output (testnet):**
```json
[
  "opid-0b1d7fe5-a2e7-47ed-bf27-01cfb49fd094",
  "opid-92d661e2-588a-4b5a-9187-a041a92b9bf7",
  "opid-ea97f749-23d2-46d4-bb6a-5b91d148e079",
  "opid-9b96eb69-962e-4e26-a2e5-c194ba2e8d5e",
  "opid-a1e6b781-5020-4c8e-97b2-4c7749a94f1e",
  "opid-4e63f6fa-7ee2-42c7-8fad-dde7393d9952",
  "opid-42f729bf-106a-441e-868e-866a2a2c12ac"
]
```

**Related Commands**

- [`z_getoperationstatus`](#z_getoperationstatus) — Get operation details
- [`z_getoperationresult`](#z_getoperationresult) — Get result and clear

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_listreceivedbyaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns a list of amounts received by a shielded address belonging to the wallet.

**Syntax**

```
z_listreceivedbyaddress "address" ( minconf )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | address | string | Yes | The shielded address |
| 2 | minconf | numeric | No | Minimum confirmations (default: 1) |

**Result**

JSON array of note objects:

| Field | Type | Description |
|-------|------|-------------|
| txid | string | Transaction ID |
| amount | numeric | Value in the note |
| memo | string | Hex-encoded memo field |
| outindex (sapling) | numeric | Output index |
| jsindex (sprout) | numeric | JoinSplit index |
| jsoutindex (sprout) | numeric | JoinSplit output index |
| confirmations | numeric | Block confirmations |
| change | boolean | True if address is also a sender |

**Examples**

```bash
verus z_listreceivedbyaddress "zs1..."
```

**Related Commands**

- [`z_listunspent`](#z_listunspent) — List unspent shielded notes
- [`z_getbalance`](#z_getbalance) — Get balance for address

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_listunspent

> **Category:** Wallet | **Version:** v1.2.14-2+

Returns array of unspent shielded notes with between minconf and maxconf confirmations. Optionally filter by address.

**Syntax**

```
z_listunspent ( minconf maxconf includeWatchonly ["zaddr",...] )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | minconf | numeric | No | Minimum confirmations (default: 1) |
| 2 | maxconf | numeric | No | Maximum confirmations (default: 9999999) |
| 3 | includeWatchonly | boolean | No | Include watch-only (default: false) |
| 4 | addresses | JSON array | No | Filter to specific z-addresses |

**Result**

JSON array of unspent note objects with `txid`, `outindex`, `confirmations`, `spendable`, `address`, `amount`, `memo`, `change`.

**Examples**

```bash
verus z_listunspent
```

**Live output (testnet):**
```json
[
  {
    "txid": "7db301e131fe1edb78e2761f98a82b9440e073230f9f572f10f7f28b3eff7036",
    "outindex": 0,
    "confirmations": 4817,
    "spendable": true,
    "address": "zs1jqpysk8t5tzfe2rs25qkf0t6pzt3xdc7cjemn2x67zs0txfv4fq6d5qklq9pet6nwr556u0mywj",
    "amount": 1.00000000,
    "memo": "f600000000...",
    "change": false
  }
]
```

**Related Commands**

- [`z_listreceivedbyaddress`](#z_listreceivedbyaddress) — List all received notes
- [`listunspent`](#listunspent) — List transparent UTXOs
- [`z_getbalance`](#z_getbalance) — Get address balance

**Notes**

- Notes with 0 confirmations are returned when minconf=0 but are not immediately spendable.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 ✅ live tested

---

## z_mergetoaddress

> **Category:** Wallet | **Version:** v1.2.14-2+

Merges multiple UTXOs and/or shielded notes into a single UTXO or note. Asynchronous operation.

⚠️ **DISABLED by default.** Requires experimental features to be enabled.

**Syntax**

```
z_mergetoaddress ["fromaddress",...] "toaddress" ( fee transparent_limit shielded_limit "memo" )
```

**Enabling**

```
experimentalfeatures=1
zmergetoaddress=1
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | fromaddresses | JSON array | Yes | Source addresses or special strings: `"ANY_TADDR"`, `"ANY_SPROUT"`, `"ANY_SAPLING"` |
| 2 | toaddress | string | Yes | Destination t-addr or z-addr |
| 3 | fee | numeric | No | Fee amount (default: 0.0001) |
| 4 | transparent_limit | numeric | No | Max UTXOs to merge (default: 50) |
| 5 | shielded_limit | numeric | No | Max notes to merge (default: 20 Sprout / 200 Sapling) |
| 6 | memo | string | No | Hex-encoded memo (for z-addr destinations) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| remainingUTXOs | numeric | UTXOs still available |
| remainingTransparentValue | numeric | Value of remaining UTXOs |
| remainingNotes | numeric | Notes still available |
| remainingShieldedValue | numeric | Value of remaining notes |
| mergingUTXOs | numeric | UTXOs being merged |
| mergingTransparentValue | numeric | Value being merged (transparent) |
| mergingNotes | numeric | Notes being merged |
| mergingShieldedValue | numeric | Value being merged (shielded) |
| opid | string | Operation ID for tracking |

**Examples**

```bash
verus z_mergetoaddress '["ANY_SAPLING","RAddr..."]' "zs1..."
```

**Related Commands**

- [`z_sendmany`](#z_sendmany) — Send to multiple addresses
- [`z_shieldcoinbase`](#z_shieldcoinbase) — Shield coinbase UTXOs
- [`z_getoperationstatus`](#z_getoperationstatus) — Track operation

**Notes**

- Cannot merge from both Sprout and Sapling simultaneously.
- Selected UTXOs are locked during the operation.
- Protected coinbase UTXOs are ignored — use `z_shieldcoinbase` for those.
- Max transaction size: 100KB (pre-Sapling) or 2MB (post-Sapling).

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## z_sendmany

> **Category:** Wallet | **Version:** v1.2.14-2+

Send funds from one address to multiple recipients. Supports both transparent and shielded addresses. Returns an async operation ID.

**Syntax**

```
z_sendmany "fromaddress" [{"address":"...","amount":...},...] ( minconf fee )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | fromaddress | string | Yes | Source t-addr or z-addr |
| 2 | amounts | JSON array | Yes | Array of `{address, amount, memo}` objects |
| 3 | minconf | numeric | No | Minimum confirmations for inputs (default: 1) |
| 4 | fee | numeric | No | Fee amount (default: 0.0001) |

**amounts array objects**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| address | string | Yes | Recipient t-addr or z-addr |
| amount | numeric | Yes | Amount in VRSC (note: daemon help text incorrectly says "KMD" — this is an upstream bug) |
| memo | string | No | Hex-encoded memo (z-addr recipients only) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| (value) | string | Operation ID (use with `z_getoperationstatus`) |

**Examples**

```bash
## Send from t-addr to z-addr
verus z_sendmany "RAddr..." '[{"address":"zs1...","amount":5.0}]'

## Send with memo
verus z_sendmany "zs1..." '[{"address":"zs1...","amount":1.0,"memo":"f600..."}]'
```

**Common Errors**

| Error | Cause |
|-------|-------|
| Insufficient funds | Not enough balance at source address |
| Invalid address | Malformed recipient address |
| Too many outputs | Pre-Sapling limit: 54 z-addr outputs |

**Related Commands**

- [`z_getoperationstatus`](#z_getoperationstatus) — Track send progress
- [`z_getoperationresult`](#z_getoperationresult) — Get final result
- [`sendmany`](#sendmany) — Transparent-only multi-send
- [`z_mergetoaddress`](#z_mergetoaddress) — Consolidate UTXOs/notes

**Notes**

- Asynchronous — returns immediately with an operation ID.
- Change from t-addr goes to a new t-addr; change from z-addr returns to itself.
- When sending coinbase UTXOs to z-addr, the entire UTXO value must be consumed (no change allowed).

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## z_setmigration

> **Category:** Wallet | **Version:** v1.2.14-2+

Enables or disables the automatic Sprout to Sapling migration. When enabled, funds are gradually moved from Sprout to Sapling addresses.

**Syntax**

```
z_setmigration enabled
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | enabled | boolean | Yes | `true` to enable, `false` to disable |

**Result**

No return value on success.

**Examples**

```bash
verus z_setmigration true
verus z_setmigration false
```

**Related Commands**

- [`z_getmigrationstatus`](#z_getmigrationstatus) — Check migration progress

**Notes**

- Migration sends up to 5 transactions every 500 blocks (at height ≡ 499 mod 500).
- Transaction amounts follow the distribution specified in ZIP 308 to minimize information leakage.
- Migration completes when Sprout balance falls below 0.01 VRSC.
- Destination is the Sapling account 0 address or the `-migrationdestaddress` parameter.
- May take several weeks for large Sprout balances.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## z_shieldcoinbase

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED — THIS API IS DEPRECATED AND NOT NECESSARY TO USE ON VERUS OR STANDARD PBAAS NETWORKS.** Shields transparent coinbase UTXOs by sending to a shielded z-address. Asynchronous operation. On Verus, coinbase outputs can be spent directly without shielding.

**Syntax**

```
z_shieldcoinbase "fromaddress" "tozaddress" ( fee limit )
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | fromaddress | string | Yes | Source t-addr or `"*"` for all |
| 2 | toaddress | string | Yes | Destination z-addr |
| 3 | fee | numeric | No | Fee (default: 0.0001) |
| 4 | limit | numeric | No | Max UTXOs to shield (default: 50) |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| remainingUTXOs | numeric | Coinbase UTXOs still available |
| remainingValue | numeric | Value still available |
| shieldingUTXOs | numeric | UTXOs being shielded |
| shieldingValue | numeric | Value being shielded |
| opid | string | Operation ID |

**Examples**

```bash
verus z_shieldcoinbase "RAddr..." "zs1..."
verus z_shieldcoinbase "*" "zs1..."
```

**Related Commands**

- [`z_mergetoaddress`](#z_mergetoaddress) — Merge UTXOs and notes
- [`z_getoperationstatus`](#z_getoperationstatus) — Track operation

**Notes**

- **Deprecated** on Verus — coinbase shielding is not required on Verus/PBaaS networks.
- Selected UTXOs are locked during the operation.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## z_viewtransaction

> **Category:** Wallet | **Version:** v1.2.14-2+

Get detailed shielded information about an in-wallet transaction, including shielded spends and outputs.

**Syntax**

```
z_viewtransaction "txid"
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | txid | string | Yes | The transaction ID |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| txid | string | Transaction ID |
| spends | array | Shielded spend details |
| outputs | array | Shielded output details |

**spends array objects**

| Field | Type | Description |
|-------|------|-------------|
| type | string | `"sprout"` or `"sapling"` |
| spend (sapling) | numeric | Spend index |
| txidPrev | string | Source transaction ID |
| address | string | z-address |
| value | numeric | Amount in VRSC |
| valueZat | numeric | Amount in zatoshis |

**outputs array objects**

| Field | Type | Description |
|-------|------|-------------|
| type | string | `"sprout"` or `"sapling"` |
| output (sapling) | numeric | Output index |
| address | string | z-address |
| recovered | boolean | True if output not for wallet address |
| value | numeric | Amount in VRSC |
| memo | string | Hex-encoded memo |
| memoStr | string | UTF-8 memo (if valid text) |

**Examples**

```bash
verus z_viewtransaction "7db301e131fe1edb78e2761f98a82b9440e073230f9f572f10f7f28b3eff7036"
```

**Related Commands**

- [`gettransaction`](#gettransaction) — Get transparent transaction details
- [`z_listreceivedbyaddress`](#z_listreceivedbyaddress) — List received notes

**Notes**

- Only works for transactions involving this wallet's shielded addresses.
- Provides the shielded spend/output details not visible in `gettransaction`.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## zcbenchmark

> **Category:** Wallet | **Version:** v1.2.14-2+

Runs a benchmark of the selected type for a specified number of samples, returning running times.

**Syntax**

```
zcbenchmark benchmarktype samplecount
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | benchmarktype | string | Yes | Type of benchmark to run |
| 2 | samplecount | numeric | Yes | Number of times to run |

**Result**

JSON array of objects, each with a `runningtime` field.

```json
[
  {"runningtime": 0.123},
  {"runningtime": 0.125}
]
```

**Examples**

```bash
verus zcbenchmark createjoinsplit 5
```

**Related Commands**

- [`getinfo`](control.md#getinfo) — General node information

**Notes**

- Primarily a developer/testing tool for measuring cryptographic operation performance.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified)

---

## zcrawjoinsplit

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Low-level command to splice a JoinSplit into a raw transaction. Inputs are unilaterally confidential; outputs are confidential between sender/receiver.

**Syntax**

```
zcrawjoinsplit rawtx inputs outputs vpub_old vpub_new
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | rawtx | string | Yes | Raw transaction hex |
| 2 | inputs | JSON object | Yes | Map of `{note: zcsecretkey}` |
| 3 | outputs | JSON object | Yes | Map of `{zcaddr: value}` |
| 4 | vpub_old | numeric | Yes | Transparent value moving into confidential store |
| 5 | vpub_new | numeric | Yes | Transparent value moving out of confidential store |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| encryptednote1 | string | First encrypted note |
| encryptednote2 | string | Second encrypted note |
| rawtxn | string | Modified raw transaction |

**Notes**

- ⚠️ **DEPRECATED** — Do not use for new development.
- Low-level Sprout JoinSplit operation.
- The caller must deliver encrypted notes to recipients and sign/mine the transaction.
- Use `z_sendmany` for normal shielded transactions.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## zcrawkeygen

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Generates a raw zcash address with secret key and viewing key.

**Syntax**

```
zcrawkeygen
```

**Parameters**

None.

**Result**

| Field | Type | Description |
|-------|------|-------------|
| zcaddress | string | The generated z-address |
| zcsecretkey | string | The secret key |
| zcviewingkey | string | The viewing key |

**Notes**

- ⚠️ **DEPRECATED** — Use `z_getnewaddress` instead.
- Low-level Sprout key generation.
- Generated keys are NOT added to the wallet.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

---

## zcrawreceive

> **Category:** Wallet | **Version:** v1.2.14-2+

⚠️ **DEPRECATED.** Decrypts an encrypted note and checks if the coin commitment exists in the blockchain.

**Syntax**

```
zcrawreceive zcsecretkey encryptednote
```

**Parameters**

| # | Name | Type | Required | Description |
|---|------|------|----------|-------------|
| 1 | zcsecretkey | string | Yes | The secret key for decryption |
| 2 | encryptednote | string | Yes | The encrypted note to decrypt |

**Result**

| Field | Type | Description |
|-------|------|-------------|
| amount | numeric | Value of the note |
| note | string | Decrypted note plaintext |
| exists | boolean | Whether the commitment is in the blockchain |

**Notes**

- ⚠️ **DEPRECATED** — Use `z_listreceivedbyaddress` or `z_viewtransaction` instead.
- Low-level Sprout note decryption.

**Tested On**

- **VRSCTEST v1.2.14-2** — Block 926996 (help output verified — **not executed**)

--- PAGE: concepts/basket-currencies-defi.md ---

# Basket Currencies and DeFi on Verus

> Protocol-level automated market making, MEV resistance, and decentralized finance without smart contracts

---

## What Is a Basket Currency?

A basket currency is a token **backed by reserves** of one or more other currencies. Think of it like a mutual fund or ETF: the basket token represents a weighted share of the currencies in its reserves.

The critical feature: Verus has a **built-in automated market maker (AMM)** at the protocol level. Anyone can convert between a basket currency and its reserves at any time, with pricing determined by the reserve ratios — not by order books, not by smart contracts, but by the blockchain's consensus rules themselves.

```
┌─────────────────────────────────────────┐
│         MYBASKET (basket currency)       │
│         Total Supply: 1,000,000          │
├─────────────────────────────────────────┤
│  Reserves:                               │
│  ├─ VRSC:  100,000 (weight: 50%)        │
│  └─ USDC:  500,000 (weight: 50%)        │
│                                          │
│  1 MYBASKET ≈ 0.1 VRSC + 0.5 USDC      │
│  (price adjusts with supply/demand)      │
└─────────────────────────────────────────┘
```

When someone buys MYBASKET with VRSC, VRSC flows into reserves and MYBASKET tokens are minted. When someone sells MYBASKET for VRSC, tokens are burned and VRSC flows out of reserves. The price adjusts automatically based on the reserve ratios.

---

## How It Differs from Ethereum DEXes

If you've used Uniswap, SushiSwap, or Curve, basket currencies will feel familiar — but the implementation is fundamentally different:

| Feature | Ethereum DEX (Uniswap) | Verus Basket |
|---|---|---|
| Implementation | Smart contract (Solidity code) | Protocol-level (consensus rules) |
| Bug risk | Contract can have bugs, exploits | Logic is part of the blockchain itself |
| MEV/front-running | Rampant — bots extract value | Resistant — simultaneous execution |
| Upgradability | Contract owner can change rules | Rules are fixed at launch |
| Gas costs | High and variable | Standard transaction fees |
| Liquidity provision | LP tokens, impermanent loss | Reserve-based, different dynamics |
| Audit required | Yes (and still gets hacked) | No — same code secures every basket |

### The Smart Contract Risk Problem

On Ethereum, every DEX is a smart contract — a program running on the blockchain. These programs can have bugs. History is littered with DeFi exploits:

- Reentrancy attacks
- Flash loan manipulation
- Oracle manipulation
- Governance attacks

Verus baskets eliminate this entire category of risk. The AMM logic is part of the Verus node software itself, validated by every node in the network. It's as fundamental as the rule that says "you can't spend coins you don't have." There's no separate contract to exploit.

---

## MEV Resistance: Fair Pricing

MEV (Maximal Extractable Value) is one of the biggest problems in DeFi. On Ethereum:

1. You submit a trade
2. A bot sees your pending trade in the mempool
3. The bot front-runs you — buying before you, driving the price up
4. Your trade executes at a worse price
5. The bot sells immediately after, pocketing the difference

**You lose money. The bot profits. This happens on every single Ethereum block.**

Verus solves this with **simultaneous execution**: all conversions within a single block execute at the **same price**. There is no ordering advantage.

```
Ethereum (sequential execution):
  Tx 1: Bot buys    → price goes up
  Tx 2: You buy     → you pay more
  Tx 3: Bot sells   → bot profits from your loss

Verus (simultaneous execution):
  Tx 1: Bot buys  ┐
  Tx 2: You buy   ├→ ALL execute at the SAME price
  Tx 3: Bot sells ┘
  
  No ordering advantage = no front-running = no MEV
```

This doesn't just reduce MEV — it eliminates the economic incentive for it entirely. There's no profit in front-running when everyone gets the same price.

---

## Making Conversions

Conversions happen through the [sendcurrency](../command-reference/multichain.md#sendcurrency) command. You specify a source currency, a destination currency, and the amount:

```bash
# Convert 100 VRSC to MYBASKET
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 100,
  "convertto": "MYBASKET",
  "currency": "VRSCTEST"
}]'

# Convert 50 MYBASKET back to VRSC
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 50,
  "convertto": "VRSCTEST",
  "currency": "MYBASKET"
}]'
```

The blockchain calculates the conversion rate based on current reserve ratios. You don't set a price — the protocol determines it.

### Cross-Conversion (Reserve to Reserve)

You can also convert between two reserve currencies *through* the basket, without needing to hold the basket currency:

```bash
# Convert VRSC to USDC through MYBASKET
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 100,
  "convertto": "USDC",
  "via": "MYBASKET",
  "currency": "VRSCTEST"
}]'
```

This is like exchanging dollars for euros through a currency exchange — the basket is the exchange.

---

## Preconversion and Launch

Before a basket currency goes live, there's a **preconversion period** where early participants contribute reserve currencies in exchange for basket tokens at the initial price.

### The Launch Process

```
1. DEFINE
   Creator calls definecurrency with:
   - Reserve currencies and weights
   - Initial supply
   - Initial contributions (from creator)
   - Min/max preconversion limits
   - Prelaunch discount (optional)

2. PRECONVERT (before startblock)
   Anyone can contribute reserve currencies
   Tokens are allocated proportionally
   
3. LAUNCH CHECK (at startblock)
   If minpreconversion met → currency activates
   If not met → all contributions refunded

4. ACTIVE
   AMM is live, conversions begin
   Price floats based on supply/demand
```

### Preconversion Parameters

| Parameter | Purpose |
|---|---|
| `initialcontributions` | Creator's initial reserves (sets starting ratio) |
| `initialsupply` | Total basket tokens after launch |
| `minpreconversion` | Minimum reserves per currency to launch |
| `maxpreconversion` | Maximum reserves accepted per currency |
| `prelaunchdiscount` | % discount for preconversion participants |
| `prelaunchcarveout` | % of preconverted reserves kept by creator |

### Initial Pricing

The initial price of a basket token is determined by:

```
Price = Total Reserve Value / Initial Supply

Example:
  Reserves: 100,000 VRSC + 500,000 USDC
  Supply: 1,000,000 MYBASKET
  
  If VRSC = $5:
  Total reserve value = (100,000 × $5) + $500,000 = $1,000,000
  Price per MYBASKET = $1,000,000 / 1,000,000 = $1.00
```

After launch, the price adjusts dynamically as people buy (reserves grow, price rises) and sell (reserves shrink, price drops).

---

## Multi-Reserve Baskets

Baskets can have **multiple reserve currencies** (up to 10, including the native currency), each with a different weight. This enables sophisticated financial instruments:

```
Index Fund Basket:
┌──────────────────────────────────────┐
│  CRYPTO-INDEX                         │
│  ├─ VRSC    (weight: 0.40)  40%      │
│  ├─ BTC     (weight: 0.30)  30%      │
│  ├─ ETH     (weight: 0.20)  20%      │
│  └─ DAI     (weight: 0.10)  10%      │
└──────────────────────────────────────┘

Stablecoin Basket:
┌──────────────────────────────────────┐
│  STABLE-USD                           │
│  ├─ DAI     (weight: 0.34)  34%      │
│  ├─ USDC    (weight: 0.33)  33%      │
│  └─ USDT    (weight: 0.33)  33%      │
└──────────────────────────────────────┘
```

The weights determine the target composition. The AMM's pricing mechanism naturally incentivizes the reserves to stay near their target weights — if one reserve is over-represented, it becomes cheaper to buy through that reserve, attracting conversions that rebalance the basket.

---

## Use Cases

### 1. Stablecoins

Create a basket backed by multiple stablecoins (DAI, USDC, USDT). The result is a **meta-stablecoin** that's more resilient than any single stablecoin — if one depegs, the basket absorbs the impact across all reserves.

### 2. Index Funds

A basket of multiple crypto assets, weighted by market cap or equal-weight. Buying one token gives exposure to a diversified portfolio. No fund manager needed — the blockchain handles rebalancing through the AMM.

### 3. Liquidity Pools

Any basket with active trading volume is a liquidity pool. The reserves provide liquidity, and the AMM provides pricing. Unlike Uniswap LPs, the liquidity is part of the basket itself — there are no separate LP tokens to manage.

### 4. Synthetic Assets

By carefully choosing reserves and weights, you can create tokens that roughly track external assets. For example, a basket that's long on one asset and inversely weighted to another.

### 5. Cross-Currency Exchange

A basket with VRSC and a bridged USD stablecoin provides a built-in exchange between crypto and dollar-denominated assets. Anyone can swap at any time with no counterparty risk.

### 6. Agent Economy Tokens

AI agents can create service tokens backed by real reserves. The backing gives the token intrinsic value — it's always redeemable for the reserves — while the AMM provides instant liquidity.

---

## Fractional Reserve Mechanics

The term "fractional" in fractional basket currencies refers to the **reserve ratio** — the total weight of all reserves relative to the supply. A basket can be 100% backed by its reserves, 5%, or anything in between. This ratio determines how the AMM behaves:

- **100% reserve (weights sum to 1.0):** Price is very stable. The basket tracks the weighted average of its reserves closely.
- **Lower reserve ratios (weights sum to less than 1.0):** More volatile. Price amplifies movements in the underlying reserves. The basket behaves more like a leveraged position.
- **Minimum:** Each reserve currency must have a weight of at least **10%** (0.1). The total reserve ratio (sum of all weights) can range from 5% to 100%.

```
High Reserve Ratio (stable):
  Reserve goes up 10% → Basket goes up ~10%
  Reserve goes down 10% → Basket goes down ~10%

Low Reserve Ratio (amplified):
  Reserve goes up 10% → Basket goes up >10%
  Reserve goes down 10% → Basket goes down >10%
```

The reserve ratio is set at creation and doesn't change. Choose wisely based on your use case.

---

## Fees

Conversions through basket currencies incur small fees, split between reserves and block producers:

| Conversion Type | Total Fee | To Reserves | To Block Reward |
|---|---|---|---|
| Basket ↔ reserve | 0.025% | 0.0125% | 0.0125% |
| Reserve ↔ reserve (via basket) | 0.05% | 0.025% | 0.025% |

This means:
- Every trade slightly increases the reserves (half the fee stays in the basket)
- The basket naturally appreciates over time (more reserves per token)
- Miners and stakers earn the other half of conversion fees
- This is analogous to trading fees in a Uniswap pool going to LPs, but split with network validators

The fee structure incentivizes trading volume and rewards both long-term basket holders and network participants.

---

## Key Takeaways

1. **Protocol-level AMM** — No smart contracts means no contract risk. The AMM is as secure as the blockchain itself.
2. **MEV-resistant** — Simultaneous execution eliminates front-running. Everyone in a block gets the same price.
3. **Multi-reserve** — Baskets can hold multiple currencies with custom weights, enabling index funds, stablecoins, and more.
4. **Always liquid** — As long as reserves exist, conversions are always possible. No reliance on external liquidity providers.
5. **Fair launch** — Preconversion periods with minimum thresholds ensure currencies only launch with adequate backing.
6. **No code required** — Creating a basket is a single `definecurrency` command, not a smart contract deployment.

---

## Related Commands

- [definecurrency](../command-reference/multichain.md#definecurrency) — Create a basket currency
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Convert between currencies
- [getcurrency](../command-reference/multichain.md#getcurrency) — Check reserve ratios and currency details
- [getcurrencyconverters](../command-reference/multichain.md#getcurrencyconverters) — Find available conversion paths

---

*As of Verus v1.2.x.*


--- PAGE: concepts/bridge-and-crosschain.md ---

# Bridge and Cross-Chain Transfers

> Trustless interoperability between Verus and Ethereum via the Verus-Ethereum bridge

---

## What Is the Verus-Ethereum Bridge?

The Verus-Ethereum bridge is a **trustless, decentralized protocol** that enables transfers of value between the Verus and Ethereum blockchains. Unlike centralized bridges that rely on custodians holding funds, the Verus bridge uses **notarization proofs** validated by both chains — the same consensus mechanism that secures Verus itself.

The bridge allows you to:
- Send ETH and ERC-20 tokens (DAI, MKR) from Ethereum to Verus
- Send VRSC and Verus-side tokens from Verus back to Ethereum
- Convert between bridged assets using Verus's protocol-level AMM
- Move VerusIDs and currency definitions cross-chain

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   ETHEREUM                          VERUS                   │
│                                                             │
│   ETH ─────────────────────────→  vETH                     │
│   DAI ─────────────────────────→  DAI.vETH                 │
│   MKR ─────────────────────────→  MKR.vETH                 │
│                                                             │
│   ←─── Bridge.vETH (basket currency) ───→                  │
│                                                             │
│   VRSC token ←─────────────────  VRSC                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Key Concepts

### Bridge.vETH — The Bridge Currency

**Bridge.vETH** is a [basket currency](basket-currencies-defi.md) that sits at the heart of the bridge. It holds reserves of multiple currencies from both chains:

- **VRSC** — Native Verus currency
- **vETH** — Ethereum (ETH) represented on Verus
- **DAI.vETH** — DAI stablecoin represented on Verus
- **MKR.vETH** — MakerDAO governance token represented on Verus

Because Bridge.vETH is a basket, it functions as an automatic exchange. You can convert between any of its reserve currencies using the same AMM mechanism described in [Basket Currencies and DeFi](basket-currencies-defi.md).

### Mapped Tokens

When an Ethereum asset crosses the bridge, it gets a **mapped representation** on Verus:

| Ethereum Asset | Verus Representation | Type |
|---|---|---|
| ETH (native) | **vETH** | Mapped currency |
| DAI (ERC-20) | **DAI.vETH** | Mapped token |
| MKR (ERC-20) | **MKR.vETH** | Mapped token |
| NATI (ERC-20) | **NATI.vETH** | Mapped token |
| VRSC (ERC-20 on ETH) | **VRSC** (native) | Native currency |

> **Note:** Additional ERC-20 tokens can be mapped to the bridge. The list above includes the currently active mapped tokens. Check the bridge interface at [eth.verusbridge.io](https://eth.verusbridge.io) for the latest available tokens.

The `.vETH` suffix indicates the token originated from the Ethereum side of the bridge. These mapped tokens are fully fungible on Verus — you can hold them, trade them, use them in basket currencies, or bridge them back to Ethereum at any time.

### Currency IDs

Every currency on Verus has a permanent i-address identifier:

| Currency | Mainnet i-address |
|---|---|
| VRSC | `i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV` |
| vETH | `i9nwxtKuVYX4MSbeULLiK2ttVi6rUEhh4X` |
| Bridge.vETH | `i3f7tSctFkiPpiedY8QR5Tep9p4qDVebDx` |
| DAI.vETH | `iGBs4DWztRNvNEJBt4mqHszLxfKTNHTkhM` |
| MKR.vETH | `iCkKJuJScy4Z6NSDK7Mt42ZAB2NEnAE1o4` |

---

## How Cross-Chain Transfers Work

Every cross-chain transfer follows a three-phase process: **export → notarization → import**.

### Phase 1: Export

When you initiate a cross-chain transfer, the source chain creates an **export transaction**. This locks or burns the source currency and records the transfer details (destination, amount, fees) in a special output.

```bash
# Example: Send 10 VRSC to Ethereum
verus sendcurrency '*' '[{
  "address": "0xYourEthAddress",
  "amount": 10,
  "currency": "VRSC",
  "exportto": "vETH",
  "feecurrency": "veth"
}]'
```

The export is bundled with other exports in the same block into an **export bundle** — a batch of transfers that cross together.

### Phase 2: Notarization

**Notaries** are nodes that run both a Verus node and an Ethereum node. They observe finalized transactions on one chain and create **notarization proofs** for the other chain.

```
Source Chain                    Notaries                    Dest Chain
     │                            │                            │
     │  1. Export tx confirmed    │                            │
     │ ─────────────────────────→ │                            │
     │                            │  2. Create proof           │
     │                            │  3. Submit notarization    │
     │                            │ ─────────────────────────→ │
     │                            │                            │
     │                            │  4. Dest chain validates   │
     │                            │     proof against headers  │
```

Key properties of notarization:
- **Multiple notaries** must agree — no single point of failure
- Notarizations include **Merkle proofs** of the export transactions
- The destination chain **independently validates** the proofs
- Notaries cannot forge transfers — they can only attest to what actually happened

### Phase 3: Import

Once a valid notarization is accepted by the destination chain, the **import** is processed automatically. The destination chain mints or releases the appropriate currency to the recipient address.

For Ethereum-bound transfers, the import is processed by the **Delegator smart contract** on Ethereum. For Verus-bound transfers, the Verus blockchain processes the import natively.

### Complete Flow Diagram

```
ETH → VRSC Transfer:

  Ethereum                                              Verus
  ────────                                              ─────
  1. User sends ETH to              
     Delegator contract          
     with Verus destination      
           │                     
           │ (ETH locked)        
           ▼                     
  2. Export recorded on          
     Ethereum                    
           │                     
           │ (~15 min finality)  
           ▼                     
  3. Notaries observe ──────────────→ 4. Notarization proof
     finalized export                    submitted to Verus
                                              │
                                              ▼
                                  5. Verus validates proof
                                     against ETH headers
                                              │
                                              ▼
                                  6. Import processed:
                                     vETH minted to
                                     destination address
                                              │
                                              ▼
                                  7. User receives vETH
                                     (or auto-converts
                                      to VRSC via basket)
```

---

## Fees and Timing

### Fees

| Fee | Amount | Paid On |
|---|---|---|
| Ethereum gas | Variable (~$5-50) | Ethereum |
| Bridge export fee | ~0.003 ETH | Ethereum |
| Verus transaction fee | 0.0001 VRSC | Verus |
| Conversion fee (if converting) | 0.025% (basket↔reserve) or 0.05% (reserve↔reserve) | Verus (into basket reserves) |

When bridging **from Ethereum to Verus**, fees are paid in ETH. When bridging **from Verus to Ethereum**, if you don't set the `feecurrency` flag, VRSC is automatically converted to vETH via the Bridge.vETH basket to cover Ethereum gas costs. You can explicitly set `"feecurrency": "veth"` to pay fees in vETH directly.

### Timing

| Stage | Duration |
|---|---|
| Ethereum finality | ~15 minutes |
| Notarization propagation | ~10-20 minutes |
| Verus import processing | ~1-2 minutes |
| **Total (ETH → Verus)** | **~30-60 minutes** |

Verus-to-Ethereum transfers take a similar amount of time. Expect roughly **1 hour** for a complete bridge transfer in either direction, depending on network conditions.

---

## Security Model

The bridge's security rests on several layers:

### 1. Proof-Based Verification

Transfers are not trusted — they are **proven**. Each notarization includes cryptographic Merkle proofs that the destination chain verifies independently. A notary cannot claim a transfer happened if it didn't, because the proof wouldn't validate against the source chain's block headers.

### 2. Multi-Notary Consensus

Multiple independent notaries must agree on the state of the source chain. No single notary can authorize an import. This is similar to how multi-signature wallets require multiple keys — except here the "signatures" are notarization proofs from independent observers.

### 3. No Custodial Risk

Unlike wrapped-token bridges (e.g., WBTC), where a custodian holds the underlying asset, the Verus bridge locks assets in smart contracts (Ethereum side) or burns/mints them at the protocol level (Verus side). No entity holds custody of bridged funds.

### 4. Ethereum Smart Contract Security

The Ethereum side of the bridge uses a **Delegator contract** pattern. The contract:
- Validates notarization proofs from Verus
- Processes imports (releasing ETH/tokens to recipients)
- Processes exports (locking ETH/tokens for bridge transfers)
- Is upgradeable through Verus notarization consensus, not a single admin key

### 5. Rollback Protection

The bridge waits for sufficient confirmations (finality) on both chains before processing transfers. This protects against blockchain reorganizations that could invalidate transfers.

### Comparison to Other Bridges

| Feature | Verus Bridge | Typical Centralized Bridge | Typical MPC Bridge |
|---|---|---|---|
| Custody | Non-custodial | Custodial | Multi-party custody |
| Trust model | Proof-based | Trust the operator | Trust the MPC set |
| Single point of failure | No | Yes | Reduced but present |
| Exploit surface | Minimal (protocol-level) | Smart contract + custodian | Smart contract + MPC |
| Upgrade mechanism | Consensus-based | Admin key | Multi-sig |

---

## Using the Bridge

### From Ethereum to Verus (Web UI)

The simplest way to bridge is via the web interface:

1. Go to [eth.verusbridge.io](https://eth.verusbridge.io/)
2. Connect your Ethereum wallet (MetaMask, etc.)
3. Select the token to bridge (ETH, DAI, MKR)
4. Enter your Verus destination (R-address or VerusID)
5. Enter the amount
6. Confirm the transaction
7. Wait ~30-60 minutes for the transfer to complete

### From Verus to Ethereum (CLI)

Use [sendcurrency](../command-reference/multichain.md#sendcurrency) with `exportto`:

```bash
# Send VRSC to Ethereum
verus sendcurrency '*' '[{
  "address": "0xYourEthAddress",
  "amount": 10,
  "currency": "VRSC",
  "exportto": "vETH",
  "feecurrency": "veth",
  "refundto": "YourVerusRAddress"
}]'

# Send vETH back to Ethereum as ETH
verus sendcurrency '*' '[{
  "address": "0xYourEthAddress",
  "amount": 0.5,
  "currency": "vETH",
  "exportto": "vETH",
  "feecurrency": "veth",
  "refundto": "YourVerusRAddress"
}]'
```

### Bridge + Convert in One Step

You can bridge and convert simultaneously. For example, bridge ETH to Verus and receive VRSC (not vETH):

From the Verus side, if you hold vETH:
```bash
# Convert vETH → VRSC through Bridge.vETH basket
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 0.5,
  "currency": "vETH",
  "convertto": "VRSC",
  "via": "Bridge.vETH"
}]'
```

### Checking Bridge Status

```bash
# View Bridge.vETH currency details and reserves
verus getcurrency "Bridge.vETH"

# Check pending exports
verus getexports "Bridge.vETH"

# Check pending imports
verus getimports "Bridge.vETH"
```

---

## Contract Addresses

### Ethereum Mainnet

| Contract | Address |
|---|---|
| Delegator | See [eth.verusbridge.io](https://eth.verusbridge.io/) |
| VRSC Token | `0xBc2738BA63882891094C99E59a02141Ca1A1C36a` |
| vETH | `0x454CB83913D688795E237837d30258d11ea7c752` |
| Bridge.vETH | `0xE6052Dcc60573561ECef2D9A4C0FEA6d3aC5B9A2` |
| DAI.vETH | `0x8b72F1c2D326d376aDd46698E385Cf624f0CA1dA` |
| MKR.vETH | `0x65b5AaC6A4aa0Eb656AB6B8812184e7545b6A221` |

### Sepolia Testnet

| Contract | Address |
|---|---|
| VRSCTEST | `0xA6ef9ea235635E328124Ff3429dB9F9E91b64e2d` |
| vETH | `0x67460C2f56774eD27EeB8685f29f6CEC0B090B00` |
| Bridge.vETH | `0xffEce948b8A38bBcC813411D2597f7f8485a0689` |
| DAI | `0xCCe5d18f305474F1e0e0ec1C507D8c85e7315fdf` |
| MKR | `0x005005b2b10a897FeD36FbD71c878213a7a169BF` |

---

## Key Takeaways

1. **Trustless** — The bridge uses cryptographic proofs, not custodians. Notaries attest to what happened; the destination chain verifies independently.
2. **Bidirectional** — Assets flow both ways: Ethereum → Verus and Verus → Ethereum.
3. **Integrated AMM** — Bridge.vETH is a basket currency, so bridged assets can be converted instantly via the protocol-level AMM.
4. **Multi-asset** — ETH, DAI, MKR, and VRSC are all supported. Additional ERC-20 tokens can be added through governance.
5. **Protocol-level** — The bridge is not a third-party dApp. It's part of the Verus protocol, secured by the same consensus mechanism as the blockchain itself.
6. **~30-60 minutes** — Transfers take time because both chains must reach finality. This is a security feature, not a limitation.

---

## Related

- [Basket Currencies and DeFi](basket-currencies-defi.md) — How the Bridge.vETH basket works
- [How To: Bridge from Ethereum](../how-to/bridge-from-ethereum.md) — Step-by-step bridging guide
- [How To: Convert Currencies](../how-to/convert-currencies.md) — Converting bridged assets
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — The command that does it all
- [getcurrency](../command-reference/multichain.md#getcurrency) — Check bridge reserves and status

---

*As of Verus v1.2.x.*


--- PAGE: concepts/currencies-and-tokens.md ---

# Currencies and Tokens on Verus

> How to create tokens, basket currencies, and entire blockchains — without writing code

---

## Overview

On Verus, anyone with a VerusID can create a new currency. There are no smart contracts to write, no audits to pass, no permission to seek. You run a single command — [definecurrency](../command-reference/multichain.md#definecurrency) — and the blockchain handles the rest.

There are three types of currencies you can create, each with increasing complexity:

```
┌─────────────────────────────────────────────────────┐
│  Currency Types on Verus                            │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Simple Token (options: 32)                         │
│  → A standalone token. No reserves, no backing.     │
│  → Like creating an ERC-20 on Ethereum.             │
│                                                     │
│  Fractional Basket (options: 33)                    │
│  → Backed by one or more reserve currencies.        │
│  → Built-in AMM for automatic trading.              │
│  → Like a Uniswap pool, but at the protocol level.  │
│                                                     │
│  PBaaS Chain (options: 264)                         │
│  → An entirely new blockchain.                      │
│  → Own consensus, own miners, own identity system.  │
│  → Connected to Verus via cross-chain notarization. │
│                                                     │
└─────────────────────────────────────────────────────┘
```

---

## Simple Tokens

A simple token is the most basic currency type. It exists on the Verus blockchain as a named asset with a supply you control.

### Key Parameters

- **options: 32** — The `TOKEN` flag (0x20)
- **proofprotocol** — Controls who can mint and burn tokens

### Proof Protocol: Decentralized vs. Centralized

The `proofprotocol` setting determines the fundamental nature of your token:

| proofprotocol | Name | Meaning |
|---|---|---|
| 1 | PROOF_PBAASMMR | Decentralized — Verus MMR proof, no notaries required. Supply fixed at launch. |
| 2 | PROOF_CHAINID | Centralized — currency controller (rootID owner) can mint/burn tokens. For basket currencies, minting/burning affects the reserve ratio. |
| 3 | PROOF_ETHNOTARIZATION | Ethereum ERC-20 mapped — token supply follows an Ethereum contract. Used for bridged tokens. |

**proofprotocol: 2 (centralized)** is useful for:
- Stablecoins (mint/burn to maintain peg)
- Service credits (mint as needed, burn when redeemed)
- Platform tokens where the issuer needs supply control
- Testing and prototyping

**proofprotocol: 1 (decentralized)** is for tokens where fixed supply is a feature — similar to Bitcoin's 21 million cap.

### Creating a Simple Token

```bash
verus definecurrency '{
  "name": "mytoken",
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"myidentity@": 1000000}]
}'
```

This creates a token called `mytoken` with 1,000,000 tokens pre-allocated to `myidentity@`. Because `proofprotocol` is 2, the identity holder can mint more later.

---

## Fractional Basket Currencies

A fractional basket currency is backed by **reserve currencies**. It has a built-in automated market maker (AMM) that allows anyone to convert between the basket currency and its reserves at any time.

This is covered in depth in [Basket Currencies and DeFi](basket-currencies-defi.md). Here's the summary:

- **options: 33** — `FRACTIONAL` (0x01) + `TOKEN` (0x20) = 0x21 = 33. Add `ID_REFERRALS` (0x08) for 41, or other flags as needed
- **currencies** — Array of reserve currency names or i-addresses
- **weights** — How much each reserve currency contributes (must sum to 1.0; minimum 0.1 per reserve; up to 10 currencies total)
- **initialsupply** — Total supply of the basket token after launch

```bash
verus definecurrency '{
  "name": "mybasket",
  "options": 33,
  "currencies": ["VRSCTEST", "USDC"],
  "weights": [0.5, 0.5],
  "initialsupply": 1000000,
  "initialcontributions": [100000, 500000],
  "idregistrationfees": 5,
  "idreferrallevels": 3
}'
```

---

## PBaaS Chains

PBaaS (Public Blockchains as a Service) chains are **entirely new blockchains** launched from Verus. They have their own:

- Block production (mining/staking)
- Identity namespace
- Transaction history
- Currency system

But they remain connected to Verus through **notarization** — periodic proofs posted back to the Verus chain that prove the state of the PBaaS chain.

- **options: 264** — `IS_PBAAS_CHAIN` (0x100) + `IDREFERRALS` (0x8) = 0x108 = 264
- Requires `nodes` (bootstrap nodes for the new network)
- Requires `eras` (block reward schedule)
- Can include a gateway converter for cross-chain trading

```bash
verus definecurrency '{
  "name": "mychain",
  "options": 264,
  "idregistrationfees": 100,
  "idreferrallevels": 3,
  "notarizationreward": 0.0001,
  "eras": [{"reward": 600000000, "halving": 1051924, "eraend": 0}],
  "nodes": [{"networkaddress": "1.2.3.4:12345", "nodeidentity": "mynode@"}],
  "blocktime": 60
}'
```

---

## Currency Lifecycle

Every currency goes through a lifecycle from definition to active trading:

```
  ┌──────────┐     ┌──────────────┐     ┌────────┐     ┌───────┐
  │  Define   │ ──→ │ Preconvert   │ ──→ │ Launch │ ──→ │ Trade │
  │           │     │ (optional)   │     │        │     │       │
  └──────────┘     └──────────────┘     └────────┘     └───────┘
```

### 1. Define

You call `definecurrency` with your parameters. This creates a pending currency definition on the blockchain. The currency is not yet active.

**Requirements:**
- You must own the VerusID matching the currency name
- That identity must not already have an active currency
- You must pay the definition fee

### 2. Preconvert (Fractional Baskets Only)

For basket currencies, there's a **preconversion period** before launch. During this time, people can contribute reserve currencies in exchange for basket tokens at the initial price.

Key preconversion parameters:
- **minpreconversion** — Minimum reserves needed for the currency to launch. If not met, contributors are refunded.
- **maxpreconversion** — Maximum reserves accepted (caps participation)
- **prelaunchdiscount** — Early contributors can get a discount
- **prelaunchcarveout** — Percentage of preconverted reserves kept by the creator

### 3. Launch

Once the preconversion period ends (at the specified `startblock`), the currency activates. For baskets, the initial price is determined by the ratio of contributed reserves to initial supply.

### 4. Trade

After launch:
- **Simple tokens** can be sent via `sendcurrency`
- **Basket currencies** can be converted to/from their reserves via `sendcurrency` using the built-in AMM
- **PBaaS chains** operate independently with cross-chain bridges back to Verus

---

## Currency as Namespace

When you define a currency, its name becomes a **namespace** for identities. This means:

- People can register SubIDs under your currency's name (e.g., `user.mycurrency@`)
- You control the registration fee via `idregistrationfees`
- You control referral levels via `idreferrallevels`

This creates a natural business model: launch a currency, set a SubID registration fee, and earn revenue as people register identities in your namespace.

```
mycurrency (currency + namespace)
├── alice.mycurrency@     ← pays idregistrationfees
├── bob.mycurrency@       ← pays idregistrationfees
└── service.mycurrency@   ← pays idregistrationfees
```

---

## Minting and Burning (Centralized Tokens)

For tokens with `proofprotocol: 2`, the identity holder can:

- **Mint** new tokens — increasing total supply
- **Burn** tokens — decreasing total supply

This is done through `sendcurrency` with special mint/burn operations. The identity holder acts as the central authority for supply management.

**Important:** Only the identity that matches the currency name can mint/burn. If `mytoken@` is the currency, only the holder of the `mytoken` VerusID can mint or burn `mytoken` tokens.

This makes centralized tokens on Verus **accountable** — there's always a known identity behind the supply decisions, unlike anonymous smart contract deployments on other chains.

---

## Costs to Launch

| Currency Type | Network | Approximate Cost |
|---|---|---|
| Simple Token | Mainnet | 200 VRSC |
| Simple Token | Testnet | 200 VRSCTEST |
| Fractional Basket | Mainnet | 200 VRSC |
| Fractional Basket | Testnet | 200 VRSCTEST |
| PBaaS Chain | Mainnet | 10,000 VRSC |
| PBaaS Chain | Testnet | 10,000 VRSCTEST |

*Plus the cost of a VerusID (~100 VRSC for a root ID on mainnet, 80 with referral (as low as ~20 net with a full referral chain)). Free IDs available via Valu; subIDs and PBaaS chain IDs can cost pennies or less.*

**Where the fees go:**
- **Token/Basket (200 VRSC):** Goes to Verus miners and stakers
- **PBaaS Chain (10,000 VRSC):** 5,000 goes to Verus block producers, 5,000 goes to block producers of the newly launched chain

These fees serve as an anti-spam measure — launching a currency should be a deliberate act, not something done carelessly.

---

## Options Bitfield Reference

The `options` parameter is a bitfield. Combine flags by adding their values:

| Flag | Value (decimal) | Hex | Meaning |
|---|---|---|---|
| OPTION_FRACTIONAL | 1 | 0x01 | Fractional reserve basket |
| OPTION_ID_ISRESTRICTED | 2 | 0x02 | Only the controlling ID (rootID) can create subIDs |
| OPTION_ID_STAKING | 4 | 0x04 | All IDs on chain stake equally (ID-based staking, not value-based) |
| OPTION_ID_REFERRALS | 8 | 0x08 | Enable ID referral rewards |
| OPTION_ID_REFERRALSREQUIRED | 16 | 0x10 | Referral required to register an ID |
| OPTION_TOKEN | 32 | 0x20 | Is a token (not a native coin) |
| OPTION_SINGLECURRENCY | 64 | 0x40 | Restrict PBaaS chain or gateway to single currency |
| OPTION_GATEWAY | 128 | 0x80 | Is a gateway currency |
| OPTION_IS_PBAAS_CHAIN | 256 | 0x100 | Is a PBaaS blockchain |
| OPTION_GATEWAY_CONVERTER | 512 | 0x200 | Is a gateway converter |
| OPTION_GATEWAY_NAMECONTROLLER | 1024 | 0x400 | Gateway name controller |
| OPTION_NFT_TOKEN | 2048 | 0x800 | Single-satoshi NFT with tokenized control of root ID |

**Common combinations:**
- **32** (TOKEN) — Simple token
- **33** (FRACTIONAL + TOKEN) — Basket currency
- **40** (TOKEN + IDREFERRALS) — Token with ID referrals
- **41** (FRACTIONAL + TOKEN + IDREFERRALS) — Basket with referrals
- **264** (IS_PBAAS_CHAIN + IDREFERRALS) — PBaaS chain with referrals

---

## Key Takeaways

1. **No code required** — Currency creation is a single CLI command, not a smart contract deployment.
2. **Three tiers** — Simple tokens for basic assets, baskets for DeFi, PBaaS chains for full blockchains.
3. **Identity-linked** — Every currency is tied to a VerusID, ensuring accountability.
4. **Namespace bonus** — Every currency automatically becomes a namespace for SubID registration.
5. **Configurable supply** — Choose between fixed supply (proofprotocol 1) or centrally managed (proofprotocol 2).

---

## Related Commands

- [definecurrency](../command-reference/multichain.md#definecurrency) — Create a new currency
- [getcurrency](../command-reference/multichain.md#getcurrency) — Look up currency details
- [listcurrencies](../command-reference/multichain.md#listcurrencies) — List all currencies
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Send, convert, and trade currencies
- [getidentity](../command-reference/identity.md#getidentity) — Check the identity behind a currency

---

*As of Verus v1.2.x.*


--- PAGE: concepts/currency-options-reference.md ---

# Currency Options & Protocol Reference

Quick reference for the numeric values used in `definecurrency`. See also: [definecurrency command reference](../command-reference/multichain.md#definecurrency)

## `options` (Bitfield)

Options is a bitfield — you can combine values by adding them together.

| Value | Hex | Name | Meaning |
|-------|-----|------|---------|
| 1 | 0x01 | FRACTIONAL | Basket/reserve currency with automatic AMM |
| 2 | 0x02 | IDRESTRICTED | Only the controlling ID (rootID) can create subIDs |
| 4 | 0x04 | IDSTAKING | All IDs on chain stake equally (ID-based, not value-based) |
| 8 | 0x08 | IDREFERRALS | Referral rewards for ID registration |
| 16 | 0x10 | IDREFERRALSREQUIRED | Referral required to register an ID |
| 32 | 0x20 | TOKEN | Is a token (not a native coin) |
| 64 | 0x40 | SINGLECURRENCY | Restrict PBaaS chain or gateway to single currency |
| 128 | 0x80 | GATEWAY | Is a gateway currency |
| 256 | 0x100 | IS_PBAAS_CHAIN | Is a PBaaS blockchain (not just a token) |
| 512 | 0x200 | GATEWAY_CONVERTER | Is a gateway converter |
| 1024 | 0x400 | GATEWAY_NAMECONTROLLER | Gateway name controller |
| 2048 | 0x800 | NFT_TOKEN | Single-satoshi NFT with tokenized control of root ID |

**Common combinations:**
- `32` (TOKEN) — Simple token
- `33` (FRACTIONAL + TOKEN) — Basket currency with reserves and AMM
- `40` (TOKEN + IDREFERRALS) — Token with ID referral rewards
- `41` (FRACTIONAL + TOKEN + IDREFERRALS) — Basket with referrals
- `264` (IS_PBAAS_CHAIN + IDREFERRALS) — PBaaS chain with referrals

*(Source: [docs.verus.io — Defining Parameters](https://docs.verus.io/currencies/launch-currency.html#defining-parameters))*

## `proofprotocol`

| Value | Name | Meaning |
|-------|------|---------|
| 1 | PROOF_PBAASMMR | Decentralized — default for decentralized currencies and PBaaS chains. SubID fees are burned. |
| 2 | PROOF_CHAINID | Centralized — the identity owner can mint and burn tokens. Used for tokens, namespace currencies, and platform tokens. |
| 3 | PROOF_ETHNOTARIZATION | Ethereum-mapped — token supply follows an Ethereum contract. Used for bridged tokens. |

**When to use what:**
- **Running a platform that issues subIDs?** → `proofprotocol: 2` (you control the token supply)
- **Launching a PBaaS blockchain?** → `proofprotocol: 1` (decentralized mining)
- **Bridging an ERC-20 token?** → `proofprotocol: 3` (tracks Ethereum supply)

## `idregistrationfees`

The cost (in this currency's tokens) to register a subID under this namespace.

- `0.01` = costs 0.01 namespace tokens per subID
- `0` = free subID registration (not recommended — spam risk)
- The namespace owner must **mint tokens first** and distribute them to users who want subIDs

## `idreferrallevels`

How many levels of referral rewards to pay out when a new ID is registered under this currency. Min 0, max 5, default 3.

The registration fee is divided into **(levels + 2) equal parts**: 1 part discount to registrant, 1 part burned/to rootID (miners), and 1 part per referral level. Unfilled levels' portions go to miners.

- `0` = fee split 1/2 discount + 1/2 burned (registrant pays half)
- `1` = fee split into 3 (1/3 discount, 1/3 burned, 1/3 to referrer)
- `2` = fee split into 4
- `3` = fee split into 5 (default — registrant pays 80% with referral)
- `4` = fee split into 6
- `5` = fee split into 7 (max — registrant pays ~85.7% with referral)

Requires `"options": 8` (IDREFERRALS flag) to be set. See [Referral System](identity-system.md#referral-system) for full details and examples.

## See Also

- [Currencies and Tokens on Verus](currencies-and-tokens.md) — overview of currency types
- [Basket Currencies and DeFi](basket-currencies-defi.md) — how fractional currencies work
- [definecurrency](../command-reference/multichain.md#definecurrency) — full command reference
- [How to Launch a Token](../how-to/launch-token.md) — step-by-step guide
- [How to Manage SubIDs](../how-to/manage-subids.md) — creating subIDs under your namespace


--- PAGE: concepts/data-descriptor.md ---

# DataDescriptor — Structured On-Chain Data Containers

> Wrap your VDXF data with metadata: labels, MIME types, encryption, and more

---

## What Is a DataDescriptor?

A `DataDescriptor` is a **structured container** for on-chain data. Instead of storing raw hex blobs in a contentmultimap, you can wrap data in a DataDescriptor to add:

- **Labels** — human-readable name for the data (max 64 UTF-8 bytes)
- **MIME types** — content type declaration (max 128 UTF-8 bytes)
- **Encryption** — full encryption support with salt, public keys, viewing keys
- **Versioning** — forward-compatible schema evolution

Think of it as an envelope around your data. The data itself goes in `objectdata`, and the envelope carries metadata about what's inside.

```
Raw storage:
  contentmultimap[key] = "68656c6c6f"   ← What is this? Who knows.

DataDescriptor storage:
  contentmultimap[key] = DataDescriptor {
    label: "greeting",
    mimeType: "text/plain",
    objectdata: "68656c6c6f"             ← "hello", and now we know what it is
  }
```

---

## Structure

| Field | Type | Description |
|---|---|---|
| `version` | integer | Schema version (currently 1) |
| `flags` | bitmask | Indicates which optional fields are present |
| `objectdata` | bytes | The actual data payload (serialized via VdxfUniValue) |
| `label` | string | Human-readable label, max 64 UTF-8 bytes |
| `mimeType` | string | MIME type (e.g., `text/plain`, `application/json`), max 128 UTF-8 bytes |
| `salt` | bytes | Encryption salt |
| `epk` | bytes | Encryption public key |
| `ivk` | bytes | Incoming viewing key (for selective disclosure) |
| `ssk` | bytes | Specific symmetric key (decrypts only this object) |

### Flags

Flags are automatically calculated based on which fields are present:

| Flag | Value | Meaning |
|---|---|---|
| `FLAG_ENCRYPTED_DATA` | 0x01 | Data is encrypted |
| `FLAG_SALT_PRESENT` | 0x02 | Salt field is included |
| `FLAG_ENCRYPTION_PUBLIC_KEY_PRESENT` | 0x04 | EPK field is included |
| `FLAG_INCOMING_VIEWING_KEY_PRESENT` | 0x08 | IVK field is included |
| `FLAG_SYMMETRIC_ENCRYPTION_KEY_PRESENT` | 0x10 | SSK field is included |
| `FLAG_LABEL_PRESENT` | 0x20 | Label field is included |
| `FLAG_MIME_TYPE_PRESENT` | 0x40 | MIME type field is included |

You don't set flags manually — the library calculates them from which fields you provide.

---

## Usage with TypeScript

### Creating a DataDescriptor

```typescript
import { DataDescriptor } from 'verus-typescript-primitives';

// Simple descriptor with label and MIME type
const descriptor = DataDescriptor.fromJson({
  version: 1,
  objectdata: { message: "Hello, Verus!" },
  label: "greeting",
  mimetype: "text/plain"
});

// Serialize to hex for on-chain storage
const hex = descriptor.toBuffer().toString('hex');
```

### Reading a DataDescriptor

```typescript
const descriptor = new DataDescriptor();
descriptor.fromBuffer(Buffer.from(hexData, 'hex'));

console.log('Label:', descriptor.label);        // "greeting"
console.log('MIME:', descriptor.mimeType);       // "text/plain"
console.log('Encrypted:', descriptor.HasEncryptedData()); // false
```

### From JSON (RPC response)

```typescript
// When you get a DataDescriptor from getidentity or similar RPC calls
const dd = DataDescriptor.fromJson({
  version: 1,
  flags: 0x60,  // label + mime present
  objectdata: { message: "Hello" },
  label: "greeting",
  mimetype: "text/plain"
});
```

---

## The objectdata Field

The `objectdata` field holds the actual payload, serialized as a [VdxfUniValue](vdxf-uni-value.md). This means it supports multiple data types natively:

```typescript
// Plain text message
DataDescriptor.fromJson({
  objectdata: { message: "Hello world" }
});

// Raw hex bytes
DataDescriptor.fromJson({
  objectdata: "48656c6c6f"
});

// Structured VDXF data (nested objects)
DataDescriptor.fromJson({
  objectdata: {
    [VDXF_Data.DataStringKey.vdxfid]: "some string value"
  }
});
```

The `objectdata` is serialized via `VdxfUniValue.fromJson()` and stored as raw bytes internally. When reading back, it's deserialized via `VdxfUniValue.fromBuffer()`.

---

## Encryption Support

DataDescriptor has built-in encryption fields for privacy:

```typescript
// Encrypted data descriptor
const encrypted = DataDescriptor.fromJson({
  version: 1,
  flags: 1,  // FLAG_ENCRYPTED_DATA
  objectdata: "encrypted_hex_here",
  salt: "random_salt_hex",
  epk: "encryption_public_key_hex"
});

// Check encryption status
encrypted.HasEncryptedData();  // true
encrypted.HasSalt();           // true
encrypted.HasEPK();            // true
```

### Selective Disclosure with Viewing Keys

The `ivk` (incoming viewing key) field enables selective disclosure — you can encrypt data but give specific parties the ability to read it without giving them your private key:

```typescript
const withViewingKey = DataDescriptor.fromJson({
  version: 1,
  flags: 1,
  objectdata: "encrypted_data",
  salt: "...",
  epk: "...",
  ivk: "viewing_key_for_auditor"
});
```

The `ssk` (specific symmetric key) is even more targeted — it decrypts only this specific data object, not others encrypted with the same master key.

---

## Storing DataDescriptors On-Chain

DataDescriptors are stored in contentmultimaps using the `DataDescriptorKey` VDXF type:

```typescript
import * as VDXF_Data from 'verus-typescript-primitives/vdxf/vdxfdatakeys';

// The system key for DataDescriptor values
const DATA_DESCRIPTOR_KEY = VDXF_Data.DataDescriptorKey.vdxfid;

// Store via updateidentity
// The hex-encoded DataDescriptor goes into the contentmultimap
```

Or you can store the raw serialized bytes directly under your own VDXF keys — the DataDescriptor is just the envelope format.

---

## Hash Vectors

DataDescriptors can contain hash vectors (arrays of 256-bit hashes) for Merkle tree proofs:

```typescript
// Decode hash vector from a descriptor
const hashes = descriptor.DecodeHashVector();
// Returns: Array<Buffer> of 32-byte hashes

// This is used internally for MMR (Merkle Mountain Range) proofs
// and data verification across chains
```

---

## JSON Representation

When a DataDescriptor is returned from RPC or serialized to JSON:

```json
{
  "version": 1,
  "flags": 96,
  "objectdata": { "message": "Hello, Verus!" },
  "label": "greeting",
  "mimetype": "text/plain"
}
```

For encrypted data:
```json
{
  "version": 1,
  "flags": 7,
  "objectdata": "a1b2c3d4...",
  "salt": "f1e2d3c4...",
  "epk": "04a1b2c3..."
}
```

---

## Size Considerations

- **Label**: max 64 UTF-8 bytes
- **MIME type**: max 128 UTF-8 bytes
- **Objectdata**: limited by transaction size (~4KB practical limit for contentmultimap)
- **Overhead**: ~10-20 bytes for version, flags, and length prefixes
- A DataDescriptor with label + MIME type adds ~200 bytes of overhead vs raw data

For large data, store a hash on-chain in the DataDescriptor and keep the full data off-chain.

---

## How Schema Discovery Works (DefinedKey vs DataDescriptor)

A common point of confusion: **DataDescriptor labels are per-value**, while **DefinedKey labels are per-key and shared across all identities in a namespace**. Here's how the full schema discovery pattern works:

### The Pattern: Namespace → Schema → SubIDs

```
yourapp@  (namespace/root identity)
  └── contentmultimap:
        └── DATA_TYPE_DEFINEDKEY → [
              DefinedKey("yourapp::data.v1.name"),    ← iNAME means "data.v1.name"
              DefinedKey("yourapp::data.v1.type"),    ← iTYPE means "data.v1.type"
              DefinedKey("yourapp::data.v1.version"), ← iVERS means "data.v1.version"
              ...
            ]

alice.yourapp@  (subID)
  └── contentmultimap:
        ├── iNAME → ["416c696365"]           ← "Alice"
        ├── iTYPE → ["4149204167656e74"]      ← "AI Agent"
        └── iVERS → ["312e30"]                ← "1.0"
```

**How an app/wallet reads alice.yourapp@:**

1. Fetch `alice.yourapp@` → sees i-addresses as keys
2. Recognize the parent namespace → `yourapp@`
3. Fetch `yourapp@` → find DefinedKey blobs
4. Decode DefinedKeys → now knows `iNAME` = `data.v1.name`
5. Display: `data.v1.name: "Alice"` instead of `iNAME: 416c696365`

**The namespace identity is the schema registry.** Any app that understands DefinedKey can discover your schema automatically by reading the parent identity.

### DataDescriptor's Role

DataDescriptor is **not** the schema discovery mechanism — that's DefinedKey's job. DataDescriptor is for when individual values need their own metadata:

- A document that needs a MIME type (`application/pdf`)
- Encrypted data that carries its own decryption keys
- A value that needs a per-instance label different from the schema key name

For simple profiles (name, type, version, status), you don't need DataDescriptor at all — just raw hex values + DefinedKeys on the namespace.

## When to Use DataDescriptor

| Scenario | Use DataDescriptor? |
|---|---|
| Simple key-value string data | Not needed — raw hex is fine |
| Data that needs a label for wallets | Not needed — use [DefinedKey](vdxf-data-standard.md) on the namespace instead |
| Content with a known format | ✅ Yes — use `mimeType` |
| Encrypted on-chain data | ✅ Yes — encryption fields built in |
| Merkle proofs / hash trees | ✅ Yes — hash vector support |
| App profile fields | Not needed — DefinedKey + raw hex is simpler and cheaper |
| Documents / large payloads | ✅ Yes — label + MIME + optional encryption |

---

## Related

- [VdxfUniValue — Universal Value Serialization](vdxf-uni-value.md) — How objectdata is serialized
- [DefinedKey — Human-Readable VDXF Labels](vdxf-data-standard.md) — Alternative approach for key labeling
- [VDXF — Verus Data Exchange Format](vdxf-data-standard.md) — The overall data standard
- [The Verus Identity System](identity-system.md) — Where DataDescriptors are stored

---

*As of verus-typescript-primitives (generic-signed-request branch).*


--- PAGE: concepts/identity-system.md ---

# The Verus Identity System

> Understanding VerusID — self-sovereign, on-chain, human-readable identity

---

## What Is a VerusID?

A VerusID is a blockchain-native identity. Unlike a wallet address (a string of random characters), a VerusID has a **human-readable name** like `alice@` that maps permanently to a cryptographic identity address (an "i-address" like `i...`).

Think of it as **a domain name + a bank account + a passport**, all in one:

- **Domain name:** A friendly name anyone can look up
- **Bank account:** Can hold and send funds
- **Passport:** Cryptographically proves who you are

The critical difference from traditional accounts: **no company controls it**. Once registered, your VerusID exists on the blockchain. No one can ban, freeze, or delete it — not even the Verus developers.

```
Traditional Account:
  You → Platform → Your Data
         ↓
  (Platform can lock you out)

VerusID:
  You → Blockchain → Your Data
         ↓
  (No single point of failure)
```

---

## Anatomy of a VerusID

When you look up an identity with [getidentity](../command-reference/identity.md#getidentity), you see its full structure. Here are the key components:

### Name and Addresses

Every VerusID has:

- **Name** — The human-readable part (e.g., `alice`)
- **Fully qualified name** — Includes the chain namespace (e.g., `alice.VRSCTEST@` on testnet, `alice@` on mainnet)
- **Identity address (i-address)** — A permanent, deterministic address derived from the name. This never changes, even if the identity is updated.
- **Primary addresses** — One or more standard addresses (R-addresses) that control the identity. These *can* be changed.

### Primary Addresses and Multisig

A VerusID can have **multiple primary addresses** and a **minimum signature threshold**. This enables multisig control:

```
Single-sig (default):
  primaryaddresses: ["R_address_1"]
  minimumsignatures: 1
  → One key controls everything

2-of-3 Multisig:
  primaryaddresses: ["R_addr_1", "R_addr_2", "R_addr_3"]
  minimumsignatures: 2
  → Any two of three keyholders must agree
```

This is powerful for organizations, shared treasuries, or high-security setups. You can change your primary addresses at any time by updating the identity — so if a key is compromised, you can rotate it out without losing your name or identity.

### Revocation and Recovery Authorities

Every VerusID has two special authorities:

- **Revocation authority** — An identity that can revoke (disable) this ID
- **Recovery authority** — An identity that can recover (re-enable) a revoked ID and assign new keys

By default, both point to the identity itself. But you can set them to *different* identities for security:

```
┌──────────────────────┐
│  alice@               │
│  Revocation: bob@     │  ← Bob can disable Alice's ID if compromised
│  Recovery: carol@     │  ← Carol can restore it with new keys
└──────────────────────┘
```

**Why this matters:** In traditional crypto, if your private key is stolen, your funds are gone forever. With VerusID, your recovery authority can revoke the compromised identity and restore control to you with new keys. It's like having a trusted friend who can freeze your credit card and issue you a new one.

**Important constraints:**
- Only the current **revocation authority** can change the revocation authority
- Only the current **recovery authority** can change the recovery authority
- This prevents an attacker who compromises your primary keys from reassigning these safety nets

**Best practice:** Set revocation and recovery to *different* identities that you control with separate keys, ideally stored in different locations. If all three (identity, revocation, recovery) share the same keys, you lose the safety net.

---

## Content Multimap: On-Chain Data Storage

Every VerusID includes a **content multimap** — a key-value data store that lives directly on the blockchain. Keys are VDXF addresses (standardized identifiers in the Verus Data eXchange Format), and values can be any hex-encoded data.

```
┌─────────────────────────────────────────┐
│  Identity: yourapp@                     │
├─────────────────────────────────────────┤
│  contentmultimap:                       │
│  ├─ iK7a5FEI...  →  "profile data v1"  │
│  ├─ i8bC2xPQ...  →  "public key data"  │
│  └─ iD9eR3vW...  →  "service listing"  │
└─────────────────────────────────────────┘
```

VDXF keys are created deterministically from human-readable strings. For example, `yourapp::data.v1.name` always maps to the same i-address. This means anyone who knows the key name can look up the data — it's a universal namespace.

**Use cases for content multimap:**
- Store public profiles or service descriptions
- Publish public keys for encrypted communication
- Attach metadata (website links, social handles, configuration)
- Create attestations (proof of qualification, membership)

The content multimap is **versioned** — every update creates a new on-chain transaction. You can look up any historical version of an identity using [getidentity](../command-reference/identity.md#getidentity) with a specific block height. This creates an immutable audit trail: data can be updated but never erased from history.

---

## VerusID vs. Traditional Accounts and Wallets

| Feature | Traditional Wallet | Platform Account | VerusID |
|---------|-------------------|------------------|---------|
| Human-readable name | ❌ (hex address) | ✅ (username) | ✅ (on-chain name) |
| Self-sovereign | ✅ | ❌ (platform owns it) | ✅ |
| Key recovery | ❌ (lose key = lose funds) | ✅ (password reset) | ✅ (recovery authority) |
| On-chain data storage | ❌ | ❌ | ✅ (content multimap) |
| Multisig built-in | Varies | ❌ | ✅ |
| Can launch currencies | ❌ | ❌ | ✅ |
| Works across chains | ❌ | ❌ | ✅ (PBaaS ecosystem) |
| Can be censored | ❌ | ✅ | ❌ |

The key insight: VerusID combines the **self-sovereignty of a wallet** (no one can take it from you) with the **usability of a platform account** (human-readable name, key recovery) and adds capabilities neither has (on-chain data, currency creation).

---

## SubIDs and Namespaces

### Name Qualification and Hierarchy

Understanding how names resolve is essential:

```
Format:              Resolves to:
─────────────────────────────────────────────
alice@               Top-level identity "alice" on current chain
alice.VRSCTEST@      Same as alice@ on testnet (fully qualified)
alice.yourapp@       SubID "alice" under "yourapp" namespace
alice.VRSC@          Same as alice@ on mainnet (fully qualified)
```

**Key rule:** `alice@` and `alice.yourapp@` are *completely different identities*. The first is a top-level ID; the second is a SubID under yourapp. If you use the wrong form, you'll get "Identity not found."

On testnet, the system appends `.VRSCTEST` to fully qualified names, so `myid@` displays as `myid.VRSCTEST@` in the `fullyqualifiedname` field. On mainnet, top-level names show as `alice.VRSC@` in fully qualified form but can be referenced simply as `alice@`.

### Namespaces

Every VerusID exists within a **namespace** — the chain or identity that serves as its parent. On the Verus mainnet, top-level identities like `alice@` are in the `VRSC` namespace. On testnet, they're in the `VRSCTEST` namespace, appearing as `alice.VRSCTEST@`.

When you launch a currency or PBaaS chain, that currency's name becomes a new namespace. Anyone can register identities within it (if allowed by the currency's configuration).

### SubIDs

A SubID is an identity registered *under* another identity's namespace. For example, if `yourapp@` exists and has an active currency, someone could register `alice.yourapp@`.

```
Namespace hierarchy:

VRSC (root)
├── alice@                 ← Top-level identity
├── yourapp@               ← Identity with active currency
│   ├── alice.yourapp@     ← SubID
│   ├── bob.yourapp@       ← SubID
│   └── service.yourapp@   ← SubID
└── mypbaas@               ← PBaaS chain namespace
    ├── user1.mypbaas@     ← Identity on that chain
    └── user2.mypbaas@
```

SubIDs are useful for:
- **Platforms** that want to issue identities to users under their brand
- **Organizations** managing member identities
- **Applications** that need named, on-chain identities for components

The identity that owns the namespace controls the **registration fee** for SubIDs. This is set via [definecurrency](../command-reference/multichain.md#definecurrency) with the `idregistrationfees` parameter.

---

## Identity Registration and Costs

### How Registration Works

Registering a VerusID is a two-step process to prevent front-running:

1. **Name commitment** — You broadcast a commitment transaction that contains a hash of the desired name plus a secret salt. This locks in your claim without revealing the name. (See `registernamecommitment`)
2. **Identity registration** — After the commitment is confirmed (1 block), you broadcast the actual registration using the commitment's transaction ID and salt. (See `registeridentity`)

This two-step process ensures no one can see your desired name and race to register it first.

### Costs

| Network | Top-level ID Cost | Notes |
|---------|-------------------|-------|
| Mainnet root ID (VRSC) | 100 VRSC | 80 VRSC with referral (referrer gets 20 VRSC) |
| Testnet (VRSCTEST) | 100 VRSCTEST | Free testnet coins available from faucet |
| PBaaS / basket chains | Varies | Some chains charge pennies for IDs |
| SubIDs | Set by namespace owner | Can be fractions of a cent |
| Valu community program | Free | Free root IDs on mainnet via the Verus Discord `#valu` channel (`/getid` command) |

For SubIDs, the cost is set by the parent currency's `idregistrationfees` parameter. Verus uses 8 decimal places (satoshi values), so fees can potentially go very low. The 0.0001 VRSC standard transaction fee always applies on top.

### Referral System

When registering a root identity, you can specify a **referral identity**. This activates a multi-level referral chain that reduces the registrant's cost and rewards referrers.

**How it works:**

The registration fee (e.g., 100 VRSC) is divided into **(levels + 2) equal parts**, where "levels" is the `idreferrallevels` setting on the currency (min 0, max 5, **default 3**):

| `idreferrallevels` | Parts | Each part | Registrant discount | Registrant pays |
|---|---|---|---|---|
| 0 | 2 | 1/2 = 50 VRSC | 50 VRSC | 50 VRSC |
| 1 | 3 | 1/3 ≈ 33.3 VRSC | 33.3 VRSC | ~66.7 VRSC |
| 2 | 4 | 1/4 = 25 VRSC | 25 VRSC | 75 VRSC |
| **3 (default)** | **5** | **1/5 = 20 VRSC** | **20 VRSC** | **80 VRSC** |
| 4 | 6 | 1/6 ≈ 16.7 VRSC | 16.7 VRSC | ~83.3 VRSC |
| 5 | 7 | 1/7 ≈ 14.3 VRSC | 14.3 VRSC | ~85.7 VRSC |

The parts are distributed as follows:
1. **1 part → discount** (registrant pays less)
2. **1 part → burned / to rootID** (miners/stakers)
3. **1 part per referral level** → each referrer in the chain

If a referral level is **unfilled** (the chain isn't deep enough), that level's portion goes to miners/stakers instead.

Referral rewards are sent to each referrer's **i-address** (not their R-address).

**Example — `idreferrallevels=3` with a 2-level chain (verified on VRSCTEST):**

We registered `AgentOversight@` using `SafeChat@` as referrer. SafeChat@ was registered using `Verus Coin Foundation@` as referrer. The fee split into 5 parts of 20 VRSC each:

| Recipient | Amount | Role |
|---|---|---|
| Discount | 20 VRSC | Registrant pays 80 instead of 100 |
| SafeChat@ (i-address) | 20 VRSC | Level 1 referrer (direct) |
| Verus Coin Foundation@ (i-address) | 20 VRSC | Level 2 (SafeChat's referrer) |
| Miners/stakers | 20 VRSC | Burned/to rootID |
| Miners/stakers | 20 VRSC | Unfilled level 3 (no deeper chain) |
| **Total** | **100 VRSC** | |

**Power user strategy:** If you own a chain of 3 identities (A → B → C, each referred the next), registering a 4th identity D using C as referrer costs 80 VRSC — but 60 VRSC flows back to your own identities (20 to C, 20 to B, 20 to A). Your **net cost is only ~20 VRSC** (the burned/rootID portion that goes to miners).

| Referral depth (levels=3) | Registrant pays | Back to your IDs | Net cost |
|---|---|---|---|
| No referral used | 100 VRSC | 0 | 100 VRSC |
| 1 level filled | 80 VRSC | 20 VRSC | 60 VRSC |
| 2 levels filled | 80 VRSC | 40 VRSC | 40 VRSC |
| 3 levels filled (full chain) | 80 VRSC | 60 VRSC | **20 VRSC** |

Note: The referral chain is visible on the public blockchain.

**Command syntax:**
```bash
verus registernamecommitment "newname" "controladdress" "referralidentity" "" "sourceoffunds"
```

The third parameter (`referralidentity`) accepts a friendly name like `SafeChat@` or an i-address.

To enable referrals on your own currency, add `"options": 8` (IDREFERRALS flag) to `definecurrency` and set `idreferrallevels` (0-5).

*(Source: [docs.verus.io — Defining Parameters](https://docs.verus.io/currencies/launch-currency.html#defining-parameters))*

---

## Real-World Analogies

To tie it all together, here's how VerusID maps to familiar concepts:

| Real World | VerusID Equivalent |
|---|---|
| Your legal name | Identity name (`alice@`) |
| Government ID number | i-address (`i4aNjr...`) |
| Home address (can change) | Primary addresses (R-addresses) |
| Power of attorney | Revocation/recovery authorities |
| Business card | Content multimap data |
| Company with employees | Namespace with SubIDs |
| Notarized document | Identity transaction (on-chain, timestamped) |

---

## Additional Features

### Private Address (z-address)

Each VerusID can optionally have attached **private z-addresses** (Sapling shielded addresses). This enables receiving private, shielded transactions directly to your VerusID. See [Privacy & Shielded Transactions](privacy-shielded-tx.md).

### Verus Vault (Timelocking)

**Verus Vault** allows you to lock funds on your VerusID with a time delay. When locked:
- Funds cannot be spent until the timelock expires
- The identity can still stake its locked coins ("safe staking")
- Useful for trusts, vesting schedules, and protecting large holdings from theft

### Signatures

VerusIDs can create **unforgeable, verifiable signatures** on files, hashes, and messages. Anyone can verify the signature against the on-chain identity — providing non-repudiation tied to a human-readable name.

### VerusID Login (SSID)

VerusID supports **passwordless login** to supported services. Instead of creating a username and password, you authenticate with your VerusID — proving ownership of the identity without exposing any private keys. This is similar to "Sign in with Google" but self-sovereign and decentralized.

### Marketplace

VerusIDs, currencies, and tokens can be traded on the **peer-to-peer on-chain marketplace** using atomic offers. See [Marketplace and Offers](marketplace-and-offers.md).

### Name Restrictions

VerusID names can include all characters from all character sets **except**: `/ : * ? " < > | @ .` — names are case-insensitive.

---

## Key Takeaways

1. **VerusID is more than a wallet** — it's a complete identity system with naming, key management, data storage, and recovery built in.
2. **You own it** — Only you (or your designated revocation authority) can revoke your identity. No external party can shut it down.
3. **It's recoverable** — Unlike traditional crypto wallets, compromised keys don't mean permanent loss.
4. **It's a namespace** — Your identity can become a platform for SubIDs and currencies.
5. **It's an on-chain database** — The content multimap lets you publish verifiable data tied to your identity.

---

## Related Commands

- [getidentity](../command-reference/identity.md#getidentity) — Look up any identity's full details
- [registernamecommitment](../command-reference/identity.md#registernamecommitment) — First step to register a new identity
- [listidentities](../command-reference/identity.md#listidentities) — List identities in your wallet
- [definecurrency](../command-reference/multichain.md#definecurrency) — Launch a currency under your identity's namespace

---

*As of Verus v1.2.x. Identity protocol version 3.*


--- PAGE: concepts/marketplace-and-offers.md ---

# Marketplace and Offers

> Trustless, on-chain atomic swaps for currencies, tokens, and identities — no intermediary required

---

## What Is the Verus Marketplace?

The Verus marketplace is a **decentralized, on-chain trading system** built into the protocol. It enables peer-to-peer atomic swaps of any blockchain asset — currencies, tokens, and VerusIDs — without intermediaries, escrow services, or centralized order books.

Every offer is a blockchain transaction. Every trade is an atomic swap. Either both sides complete, or neither does. There's nothing to trust except the blockchain's consensus rules.

```
┌────────────────────────────────────────────────────┐
│                VERUS MARKETPLACE                    │
│                                                     │
│  Seller                              Buyer          │
│  ┌──────────┐                  ┌──────────┐        │
│  │ makeoffer │                  │ takeoffer │        │
│  │          │                  │          │        │
│  │ Offers:  │   On-chain       │ Accepts: │        │
│  │ 10 VRSC  │ ←─ atomic ─────→ │ myid@    │        │
│  │ for      │    swap          │ for      │        │
│  │ myid@    │                  │ 10 VRSC  │        │
│  └──────────┘                  └──────────┘        │
│                                                     │
│  Either BOTH sides execute, or NEITHER does.        │
└────────────────────────────────────────────────────┘
```

---

## What Can Be Traded?

The marketplace supports trading **any combination** of these asset types:

| You Offer | You Receive | Example |
|---|---|---|
| Currency | Currency | 100 VRSC for 0.1 vETH |
| Currency | Identity | 50 VRSC for `coolname@` |
| Identity | Currency | `myoldid@` for 25 VRSC |
| Identity | Identity | `name1@` for `name2@` |
| Token | Currency | 1000 MYTOKEN for 10 VRSC |
| Token | Token | 500 TOKENA for 200 TOKENB |

This flexibility means the marketplace handles use cases that would require multiple different platforms in other ecosystems — token exchanges, NFT marketplaces, domain name auctions, and identity sales — all in one system.

---

## How Offers Work

### Creating an Offer (makeoffer)

When you create an offer with [makeoffer](../command-reference/marketplace.md#makeoffer), you specify:

1. **What you're offering** — a currency amount or an identity
2. **What you want in return** — a currency amount or an identity definition
3. **Expiry height** — when the offer expires (default: ~20 blocks / ~20 minutes)
4. **Change address** — where leftover funds go

```bash
# Offer 10 VRSC for the identity "coolname@"
verus makeoffer "*" '{
  "changeaddress": "RMyAddress",
  "expiryheight": 930000,
  "offer": {
    "currency": "VRSCTEST",
    "amount": 10
  },
  "for": {
    "name": "coolname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RMyAddress"],
    "minimumsignatures": 1
  }
}'
```

The offer is posted on-chain as a **partial transaction**. Your funds (or identity) are committed but not yet spent — they're locked until someone takes the offer, or it expires.

### Taking an Offer (takeoffer)

When you find an offer you want to accept, you use `takeoffer` to complete the swap:

```bash
# Accept the offer — pay 10 VRSC, receive "coolname@"
verus takeoffer "*" '{
  "txid": "abc123...",
  "changeaddress": "RBuyerAddress",
  "deliver": {
    "currency": "VRSCTEST",
    "amount": 10
  },
  "accept": {
    "name": "coolname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RBuyerAddress"],
    "minimumsignatures": 1
  }
}'
```

The `takeoffer` command completes the partial transaction, creating a single atomic transaction where:
- The seller's offered asset goes to the buyer
- The buyer's payment goes to the seller
- Both transfers happen in the **same transaction** — atomic and indivisible

### Finding Offers (getoffers)

Browse existing offers for any identity or currency:

```bash
# Find offers involving an identity
verus getoffers "coolname@" false true

# Find offers involving a currency
verus getoffers "VRSCTEST" true true
```

The third parameter (`true`) includes raw transaction hex, which is needed to take the offer.

### Listing Your Offers (listopenoffers)

```bash
# List your active offers
verus listopenoffers

# Include expired offers
verus listopenoffers true
```

### Closing Offers (closeoffers)

Cancel active offers or reclaim funds from expired ones:

```bash
# Cancel specific offers
verus closeoffers '["txid1", "txid2"]' "RMyAddress"

# Close all expired offers (reclaim locked funds)
verus closeoffers
```

---

## Offer Lifecycle

```
1. CREATE (makeoffer)
   ├─ Funds/identity locked in partial transaction
   ├─ Offer visible via getoffers
   └─ Offer visible in listopenoffers

2. ACTIVE (waiting for taker)
   ├─ Anyone can view the offer
   ├─ Anyone can take the offer
   └─ Seller can close/cancel at any time

3. RESOLUTION (one of three outcomes)
   ├─ TAKEN (takeoffer) → Atomic swap completes
   │   ├─ Seller receives payment
   │   └─ Buyer receives asset
   ├─ EXPIRED (expiryheight reached)
   │   └─ Seller reclaims funds via closeoffers
   └─ CANCELLED (closeoffers before expiry)
       └─ Seller reclaims funds immediately
```

---

## The Identity Marketplace

One of the most distinctive features of the Verus marketplace is **identity trading**. VerusIDs are first-class blockchain objects that can be bought, sold, and traded just like currencies.

### Selling an Identity

```bash
# Sell "premiumname@" for 100 VRSC
verus makeoffer "premiumname@" '{
  "changeaddress": "RSellerAddress",
  "expiryheight": 950000,
  "offer": {
    "identity": "premiumname@"
  },
  "for": {
    "address": "RSellerAddress",
    "currency": "VRSCTEST",
    "amount": 100
  }
}'
```

**Important:** The identity itself must have funds to cover the transaction fee. Send a small amount first:
```bash
verus sendtoaddress "premiumname@" 0.1
```

### Buying an Identity

When buying an identity, the `accept` field defines the new ownership — who controls it after the swap:

```bash
verus takeoffer "*" '{
  "txid": "offer_txid_here",
  "changeaddress": "RBuyerAddress",
  "deliver": {
    "currency": "VRSCTEST",
    "amount": 100
  },
  "accept": {
    "name": "premiumname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RBuyerAddress"],
    "minimumsignatures": 1
  }
}'
```

### Trading Existing Identities

You can make offers to **buy existing identities** from their current owners. The offer specifies the identity you want and what you're willing to pay. The current owner can accept by taking the offer, which atomically transfers ownership.

> **Note:** You cannot make offers for identities that don't exist yet. The identity must already be registered on-chain.

---

## Currency-to-Currency Trading

The marketplace also handles direct currency swaps without going through a basket AMM:

```bash
# Offer 1000 MYTOKEN for 5 VRSC
verus makeoffer "*" '{
  "changeaddress": "RMyAddress",
  "expiryheight": 940000,
  "offer": {
    "currency": "MYTOKEN",
    "amount": 1000
  },
  "for": {
    "address": "RMyAddress",
    "currency": "VRSCTEST",
    "amount": 5
  }
}'
```

This is useful when:
- There's no basket currency connecting the two tokens
- You want a specific price (limit order) rather than the AMM price
- You're trading large amounts and want to avoid AMM slippage

---

## Marketplace vs. AMM Conversions

Verus offers **two** ways to exchange assets, each suited to different scenarios:

| Feature | Marketplace (makeoffer/takeoffer) | AMM (sendcurrency + convertto) |
|---|---|---|
| Price discovery | Set by the offer creator | Determined by reserve ratios |
| Execution | Requires a counterparty to take | Instant (always-available liquidity) |
| Assets supported | Any: currencies, tokens, identities | Only basket reserve currencies |
| Order type | Limit order (fixed price) | Market order (current AMM price) |
| MEV risk | None (atomic swap) | None (simultaneous execution) |
| Slippage | None (price is fixed) | Possible on large trades |
| Best for | Identity trades, specific prices, large OTC | Quick swaps, small-medium amounts |

In practice, users often use both: the AMM for routine currency conversions, and the marketplace for identity trading and large block trades.

---

## Comparison to Centralized Exchanges

| Feature | Verus Marketplace | Centralized Exchange |
|---|---|---|
| Custody | Non-custodial (your keys, your coins) | Exchange holds your funds |
| KYC required | No | Usually yes |
| Counterparty risk | None (atomic swaps) | Exchange can be hacked, freeze funds |
| Downtime | Never (blockchain is always on) | Maintenance windows, outages |
| Trading pairs | Any asset combination | Limited to listed pairs |
| Identity trading | Native support | Not possible |
| Fees | Only blockchain transaction fees | Trading fees + withdrawal fees |
| Speed | ~1 minute per block confirmation | Instant (internal ledger) |
| Privacy | Pseudonymous (blockchain addresses) | Full identity required |

The tradeoff: centralized exchanges offer faster execution, deeper liquidity, and familiar UIs. The Verus marketplace offers trustlessness, self-custody, and unique capabilities (identity trading) that centralized platforms cannot provide.

---

## Security Considerations

1. **Verify before taking** — Always inspect offer details with `getoffers` before committing funds
2. **Set reasonable expiry** — Don't leave offers open for thousands of blocks; use `expiryheight` appropriate to your timeframe
3. **Close expired offers** — Run `closeoffers` periodically to reclaim funds locked in expired offers
4. **Double-check `primaryaddresses`** — When buying an identity, the addresses in `accept` determine who controls it. Get this wrong and you lose the identity.
5. **Fund identities before selling** — The identity must have a small balance to cover the `makeoffer` transaction fee

---

## Key Takeaways

1. **Fully on-chain** — Every offer is a blockchain transaction. No off-chain order books, no centralized matching engines.
2. **Truly atomic** — Swaps either complete entirely or not at all. No partial fills, no stuck states.
3. **Universal asset support** — Trade currencies, tokens, and identities in any combination.
4. **No intermediary** — Direct peer-to-peer trades. The blockchain is the only "exchange."
5. **Identity marketplace** — Buy, sell, and auction VerusIDs — a capability unique to Verus.
6. **Complements the AMM** — Use the marketplace for limit orders and identity trades; use baskets for instant liquidity.

---

## Related Commands

- [makeoffer](../command-reference/marketplace.md#makeoffer) — Create a swap offer
- [takeoffer](../command-reference/marketplace.md#takeoffer) — Accept an existing offer
- [getoffers](../command-reference/marketplace.md#getoffers) — Browse offers for an asset
- [listopenoffers](../command-reference/marketplace.md#listopenoffers) — List your open offers
- [closeoffers](../command-reference/marketplace.md#closeoffers) — Cancel or reclaim offers

## Related Guides

- [How To: Create a Marketplace Offer](../how-to/create-marketplace-offer.md) — Step-by-step trading guide
- [Basket Currencies and DeFi](basket-currencies-defi.md) — AMM-based conversions

---

*As of Verus v1.2.x.*


--- PAGE: concepts/mining-and-staking.md ---

# Mining and Staking on Verus

> How Verus secures its network with a 50/50 hybrid of Proof of Work and Proof of Stake

---

## The Hybrid Consensus Model

Verus uses a **50/50 hybrid** of Proof of Work (PoW) and Proof of Stake (PoS). This means that roughly half of all blocks are found by miners (using computational power) and half by stakers (using coin holdings).

```
Block N   [PoW] ← Miner solves hash puzzle
Block N+1 [PoS] ← Staker selected by UTXO size
Block N+2 [PoW] ← Miner solves hash puzzle
Block N+3 [PoS] ← Staker selected by UTXO size
  ...
```

The alternation isn't strictly every-other-block, but over time the ratio balances to approximately 50/50. The protocol enforces this by adjusting difficulty independently for PoW and PoS.

### Why Hybrid?

Each consensus mechanism has weaknesses. Combining them provides stronger security:

| Attack | PoW Only | PoS Only | Verus Hybrid |
|---|---|---|---|
| 51% hashrate attack | Vulnerable | N/A | Need hashrate AND stake |
| Nothing-at-stake | N/A | Vulnerable | PoW blocks anchor the chain |
| Centralization via ASICs | High risk | N/A | VerusHash equalizes FPGAs, no ASICs exist |
| Wealth concentration | N/A | Rich get richer | Mining provides alternative path |

To attack Verus, you'd need to control both significant hashrate *and* significant coin holdings simultaneously — a much harder proposition than attacking either mechanism alone.

---

## Proof of Work: VerusHash 2.2

### What Is VerusHash?

VerusHash 2.2 is Verus's custom mining algorithm, designed with a specific goal: **keep mining accessible to everyday CPUs**.

Most crypto mining algorithms eventually get dominated by specialized hardware:
- **SHA-256** (Bitcoin) → ASICs dominate, home mining is dead
- **Ethash** (old Ethereum) → GPUs dominated
- **RandomX** (Monero) → CPU-friendly but still FPGA-vulnerable

VerusHash 2.2 uses a combination of techniques — including AES and AVX instructions — that map well to modern CPU architectures. FPGAs **can** mine Verus but are intentionally equalized to roughly ~2x CPU cost-performance, preventing them from dominating. No ASICs exist for VerusHash. GPUs can also mine (ccminer has a `Verus2.2gpu` branch) but generally perform worse than modern CPUs. CPUs remain the primary and most cost-effective mining hardware.

**The result:** As of v1.2.x, CPU mining remains competitive on Verus. A modern desktop CPU can meaningfully participate in mining, which supports decentralization.

### Mining in Practice

To start mining:

```bash
# Enable mining with 4 CPU threads
verus setgenerate true 4

# Check mining status
verus getmininginfo
```

The [getmininginfo](../command-reference/mining.md#getmininginfo) command shows key metrics:

- **localhashps** — Your local hash rate
- **networkhashps** — Estimated total network hash rate
- **difficulty** — Current PoW difficulty
- **generate** — Whether mining is active
- **numthreads** — How many CPU threads are mining

### Mining Pools vs. Solo Mining

**Solo mining** means your node finds blocks independently. You get the full block reward when you find a block, but blocks may be infrequent depending on your hashrate relative to the network.

**Pool mining** means you contribute hashrate to a pool that combines many miners' power. Rewards are split proportionally. More consistent payouts, but you pay a pool fee (0.1–5% depending on the pool).

For most miners, pools provide more predictable income. Solo mining is viable mainly for those with significant hashrate.

---

## Proof of Stake: Staking

### How Staking Works

Staking on Verus works differently from delegated PoS systems (like Ethereum). There's no minimum stake, no validators to delegate to, and no slashing.

Here's the process:

1. You hold VRSC in your wallet
2. You enable staking (`verus setgenerate true 0` — 0 threads means staking only, no mining)
3. Your wallet must remain **unlocked** and **online**
4. The protocol selects stakers based on **UTXO size** — larger UTXOs have a higher probability of being selected to stake a block
5. When selected, your wallet automatically creates a PoS block and earns the block reward

```
Staking Selection (simplified):

  Larger UTXO → Higher probability of being selected
  
  After staking, the UTXO is consumed → prevents monopolization
```

### Staking Requirements

| Requirement | Details |
|---|---|
| Minimum amount | Effectively none (minimum 0.00000001 VRSC) |
| Coin maturity | UTXOs must have 150 confirmations (~2.5 hours) |
| Wallet state | Must be unlocked (or unlocked for staking only) |
| Node state | Must be running and synced to the network |
| Network | Must be connected to peers |

### Staking Tips

- **Keep your wallet running 24/7** for maximum staking opportunity
- **Larger UTXOs stake more often**, but after staking they reset coin age
- **Split large holdings** into multiple UTXOs for more consistent staking (though this has diminishing returns)
- Use `verus setgenerate true 0` to stake without mining (saves CPU)

---

## Block Rewards and Halving

### Reward Schedule

Verus follows a halving schedule similar to Bitcoin, but with its own parameters:

| Era | Block Range | Block Reward | Notes |
|---|---|---|---|
| 1 | 1 – 10,080 | Variable (~0 → 384) | Launch phase (~485K VRSC, timelocked), linearly increasing |
| 2 | 10,080 – 53,280 | 384 VRSC | Timelocked |
| 3 | 53,280 – 96,480 | 192 VRSC | Timelocked |
| 4 | 96,480 – 139,680 | 96 VRSC | |
| 5 | 139,680 – 226,080 | 48 VRSC | |
| 6 | 226,080 – 1,278,000 | 24 VRSC | |
| 7 | 1,278,000 – 2,329,920 | 12 VRSC | |
| 8 | 2,329,920 – 3,381,840 | 6 VRSC | |
| 9 | 3,381,840 – 4,433,760 | **3 VRSC** (current on mainnet) | |
| 10 | 4,433,760+ | 1.5 VRSC | Next halving ~Aug 2026 |

Halving interval: **1,051,920 blocks** (~2 years at ~60s average block time).

*(Source: [docs.verus.io — Economy](https://docs.verus.io/economy/))*

> **Tip:** Use `getblocksubsidy` to check the current block reward. Use `getcurrency VRSC` to see the halving interval in the `eras` field.

Each block reward is split between the miner/staker who found the block. Since blocks alternate between PoW and PoS, both miners and stakers earn comparable total rewards over time.

### Supply

Verus has a **max supply of 83,540,184 VRSC**. The halving schedule means emission decreases geometrically, approaching this limit over time.

---

## Merged Mining

Verus supports **merged mining** — the ability to mine Verus and up to **22 PBaaS chains** simultaneously, with the same hashrate.

```
Your CPU Hashrate
       │
       ├──→ Verus (VRSC) blocks
       ├──→ PBaaS Chain A blocks
       └──→ PBaaS Chain B blocks
       
Same work, multiple rewards
```

When PBaaS chains are launched with PoW consensus, Verus miners can opt in to merged mining. The [getmininginfo](../command-reference/mining.md#getmininginfo) output includes `mergemining` (number of chains being merge-mined) and `mergeminedchains` (their names).

This is significant because:
- New chains get security from the existing Verus mining network from day one
- Miners earn additional rewards without additional hardware
- It strengthens the entire PBaaS ecosystem

---

## Staking Pools

While mining pools are straightforward (combine hashrate, split rewards), **staking pools** on Verus come in two forms:

### Non-Custodial (VerusID-based)

Your coins remain in your wallet. Using VerusID, you can delegate staking power to a pool without transferring custody. The pool combines staking power from multiple participants without holding anyone's coins.

Example: **Synergy Pool** uses this model.

### Custodial

A pool operator runs a 24/7 node and participants send coins to a shared wallet. Rewards are distributed proportionally. This requires trusting the operator with your coins.

**Recommendation:** Prefer non-custodial VerusID staking pools when available — you retain full control of your funds.

---

## Mining Distribution

The `setminingdistribution` command allows miners to automatically distribute their mining rewards to multiple destinations:

```bash
verus setminingdistribution '[
  {"address": "RAddress1", "percentage": 50},
  {"address": "RAddress2", "percentage": 30},
  {"identity": "myid@", "percentage": 20}
]'
```

This is useful for:
- Automatically paying pool participants
- Splitting rewards between a hot wallet and cold storage
- Directing a percentage of mining income to a specific identity or project
- Tax management (separate mining income into different addresses)

---

## Practical Setup Guide

### Mining Only (CPU)

```bash
# Start mining with all available threads
verus setgenerate true -1

# Start mining with specific thread count
verus setgenerate true 4

# Stop mining
verus setgenerate false
```

### Staking Only

```bash
# Unlock wallet for staking only
verus walletpassphrase "your-passphrase" 0 true

# Enable staking (0 mining threads = staking only)
verus setgenerate true 0
```

### Mining + Staking

```bash
# Unlock wallet
verus walletpassphrase "your-passphrase" 0 true

# Mine with 4 threads AND stake
verus setgenerate true 4
```

### Check Status

```bash
# Full mining info
verus getmininginfo

# Quick generate status
verus getgenerate
```

---

## Key Takeaways

1. **50/50 hybrid** — Verus combines PoW and PoS for stronger security than either alone.
2. **CPU-friendly** — VerusHash 2.2 keeps mining accessible to regular computers.
3. **Low barrier to stake** — No minimum stake, no delegation, no slashing. Just hold coins and keep your wallet open.
4. **Merged mining** — Mine Verus and PBaaS chains simultaneously for additional rewards.
5. **Halving schedule** — Block rewards decrease over time, creating a deflationary emission curve.

---

## Related Commands

- [getmininginfo](../command-reference/mining.md#getmininginfo) — Check mining and staking status
- [setgenerate](../command-reference/generating.md#setgenerate) — Enable/disable mining and staking
- [getgenerate](../command-reference/generating.md#getgenerate) — Check generate status
- [getnetworksolps](../command-reference/mining.md#getnetworksolps) — Network hash rate details

---

*As of Verus v1.2.x. VerusHash 2.2.*


--- PAGE: concepts/on-chain-file-storage.md ---

# On-Chain File Storage (Multipart Data)

Verus has a complete decentralized file storage system built into its identity layer. Files and data objects can be stored directly on-chain, split across multiple transaction outputs or even multiple blocks, with cryptographic verification and optional encryption.

This is one of the least documented features of the protocol — this page is the first comprehensive guide to how it works.

!!!success Proven at Scale
An 18.6MB PDF was stored and retrieved with perfect byte-for-byte SHA256 verification on vrsctest — 19 chunks across 19 transactions, fully automated. The methods below are battle-tested.
!!!

## Overview

The system has three layers:

| Layer | What It Does | Key Component |
|-------|-------------|---------------|
| **Data Creation** | Build structured data with MMR integrity | `signdata` RPC |
| **Storage** | Store data in identity contentmultimap, auto-chunk if too large | `updateidentity` + `BreakApart()` |
| **Retrieval** | Aggregate data across blocks, reassemble chunks | `getidentitycontent` + `Reassemble()` |

---

## Proven Storage Methods

There are three tested methods for storing file data on-chain. Each has different cost, complexity, and size characteristics.

### Method 1: `updateidentity` + Data Wrapper ⭐ RECOMMENDED

The simplest and cheapest method. Place a `"data"` object inside a `contentmultimap` value — this triggers the daemon to internally call `signdata`, wrap the result in `CNotaryEvidence`, encrypt with a random Sapling key (publishing the `ivk` for retrieval), and auto-chunk via `BreakApart()` if the data exceeds ~6KB.

**Cost:** ~6–7 VRSCTEST per 999KB chunk

```bash
# Create a JSON-RPC request file (required for large payloads — CLI has arg length limits)
cat > /tmp/upload-chunk.json << 'EOF'
{
  "jsonrpc": "1.0",
  "method": "updateidentity",
  "params": [{
    "parent": "iE2CDG1vRDAG5EqZp5KJW3Gx8NNAe9KVC3",
    "name": "trial1",
    "primaryaddresses": ["RCizCfGxAbFuHp8dGnEHQwTwBtu3pdkQWD"],
    "minimumsignatures": 1,
    "contentmultimap": {
      "iRwRJ2JxndAkmdRGs7yLF6iheFReBzKkLR": [{
        "data": {
          "address": "trial1.filestorage@",
          "filename": "/tmp/chunks/chunk_aa",
          "createmmr": true,
          "label": "chunk-0",
          "mimetype": "application/octet-stream"
        }
      }]
    }
  }]
}
EOF

# Send via curl
curl --user "$RPCUSER:$RPCPASS" --data-binary @/tmp/upload-chunk.json \
  -H 'content-type: text/plain;' http://127.0.0.1:$RPCPORT/
```

!!!danger Critical: The `"data"` wrapper placement
The `"data"` object **MUST** be inside `contentmultimap`, not at the top level of the identity update. A top-level `"data"` field does NOT trigger BreakApart — it will be silently ignored.

```json
// ❌ WRONG — top-level data, no chunking happens
{"name": "id", "data": {"filename": "/path/to/file"}}

// ✅ CORRECT — data inside contentmultimap triggers BreakApart
{"name": "id", "contentmultimap": {"<vdxf-key>": [{"data": {"filename": "/path/to/file"}}]}}
```
!!!

### Method 2: `sendcurrency` to z-address

Send file data to a shielded address. The daemon creates VDXF cryptocondition outputs (transparent, not shielded memo fields) encrypted to the z-address viewing key.

**Cost:** ~10.3 VRSCTEST per 999KB chunk

```bash
# Generate z-address and get viewing key
verus -chain=vrsctest z_getnewaddress
verus -chain=vrsctest z_exportviewingkey "zs1..."

# Upload a chunk
verus -chain=vrsctest sendcurrency '*' '[{
  "address": "zs1vq3khkucu9pfya3xwseajhqds5m0ass68dakefuaq53smys92p3ll7dl89atn9t7fdpmjwssnvx",
  "amount": 0.0001,
  "data": {
    "filename": "/tmp/chunk_aa.bin",
    "createmmr": true,
    "label": "chunk-0"
  }
}]'
```

**Pros:** Built-in encryption, private access control (share EVK to grant read access).
**Cons:** Most expensive method, async operation (returns opid), txids must be tracked manually.

### Method 3: Raw `contentmultimap` (Small Data Only)

For data under ~5KB, hex-encode it and place directly in `contentmultimap`. Essentially free (just the tx fee).

```bash
# Convert text to hex
echo -n "hello world" | xxd -p | tr -d '\n'

verus -chain=vrsctest updateidentity '{
  "parent": "iE2CDG1vRDAG5EqZp5KJW3Gx8NNAe9KVC3",
  "name": "trial1",
  "primaryaddresses": ["RCizCfGxAbFuHp8dGnEHQwTwBtu3pdkQWD"],
  "minimumsignatures": 1,
  "contentmultimap": {
    "iDMrLivrh1fnidgxsBmUJxyf5hoZV7dHE2": "68656c6c6f20776f726c64"
  }
}'
```

**Limit:** 5,500 bytes (11,000 hex chars) max. Above this → `bad-txns-failed-precheck`. Data approaching this limit may be **silently truncated** with no error.

### Method Comparison

| | updateidentity + data ⭐ | sendcurrency | Raw contentmultimap |
|---|---|---|---|
| **Cost per 999KB** | ~6–7 VRSCTEST | ~10.3 VRSCTEST | ~0.0001 (tx fee) |
| **Max per call** | 1,000,000 bytes | 1,000,000 bytes | ~5KB |
| **Auto-chunking** | ✅ Yes | ✅ Yes | ❌ No |
| **Encryption** | ✅ Auto (ivk published) | ✅ To z-address | ❌ None |
| **Linked to identity** | ✅ Yes | ❌ Manual tracking | ✅ Yes |
| **Operation** | Synchronous | Async (opid) | Synchronous |

### Cost Breakdown

| Input Size | On-chain Size | Overhead |
|-----------|--------------|----------|
| 10KB | ~12KB | ~20% |
| 100KB | ~107KB | ~7% |
| 500KB | ~528KB | ~5.6% |
| 999KB | ~1,030KB | ~3% |

**Cost per KB** (updateidentity method): ~0.0067 VRSCTEST/KB (~6.8 VRSCTEST/MB)

### Hard Limit

Every storage call has a hard limit of exactly **1,000,000 bytes** per invocation, enforced in `signdata` before processing. For files larger than ~999KB, split them into chunks first:

```bash
split -b 999000 myfile.pdf /tmp/chunks/chunk_
```

---

## Retrieval

### Via `decryptdata` (for data wrapper / updateidentity uploads)

```bash
# Step 1: Get encrypted descriptors from the identity
verus -chain=vrsctest getidentitycontent "trial1.filestorage@"

# Step 2: For each chunk key, extract the first datadescriptor entry
# Each key has 2 entries: [0] = encrypted data reference, [1] = signature proof

# Step 3: Decrypt and retrieve the chunk
verus -chain=vrsctest decryptdata '{
  "datadescriptor": {
    "version": 1,
    "flags": 13,
    "objectdata": "<objectdata_hex_from_step2>",
    "epk": "<epk_from_step2>",
    "ivk": "<ivk_from_step2>"
  },
  "ivk": "<same_ivk>",
  "txid": "<txid_of_the_updateidentity_call>",
  "retrieve": true
}'
```

**Returns:**
```json
[{
  "version": 1,
  "flags": 98,
  "mimetype": "application/octet-stream",
  "objectdata": "<hex_encoded_file_data>",
  "label": "chunk-0",
  "salt": "..."
}]
```

Convert `objectdata` hex to binary to get the original chunk bytes.

**Key points:**
- The `txid` parameter is **required** — the on-chain reference uses `txid=0000...0000` (self-referencing), so `decryptdata` needs the real txid to locate the BreakApart outputs.
- The `ivk` is published in the identity output — anyone can retrieve the data.
- Retrieval is fast (~1–5 seconds per chunk).

### Via `decryptdata` with EVK (for sendcurrency uploads)

```bash
verus -chain=vrsctest decryptdata '{
  "datadescriptor": {
    "version": 1, "flags": 0,
    "objectdata": {
      "iP3euVSzNcXUrLNHnQnR9G6q8jeYuGSxgw": {
        "type": 0, "version": 1, "flags": 1,
        "output": {"txid": "0000000000000000000000000000000000000000000000000000000000000000", "voutnum": 0},
        "objectnum": 0, "subobject": 0
      }
    }
  },
  "txid": "<chunk_txid>",
  "retrieve": true,
  "evk": "<extended_viewing_key>"
}'
```

### Via `getidentitycontent` (metadata / encrypted descriptors)

```bash
# All content
verus getidentitycontent "myidentity@"

# Specific height range
verus getidentitycontent "myidentity@" 100000 100500

# Specific VDXF key
verus getidentitycontent "myidentity@" 0 0 false 0 "iXXX..."

# Include mempool (unconfirmed)
verus getidentitycontent "myidentity@" 0 -1
```

!!!warning z_listreceivedbyaddress does NOT work for retrieval
Data stored via `sendcurrency` with `data.filename` is stored in transparent VDXF cryptocondition outputs, NOT in shielded memo fields. `z_listreceivedbyaddress` returns entries but memo fields are empty.
!!!

---

## Schema Design: Namespace Pattern

For organized file storage, use a namespace identity with a TOKEN currency and VDXF DefinedKeys. This makes your file storage discoverable by any wallet.

```
filestorage@  (namespace identity — TOKEN currency, schema registry)
│
├── DefinedKeys (25 keys):
│     chunk.0 .. chunk.18, manifest, filename, mimetype,
│     filesize, hash, chunkcount
│
└── trial1.filestorage@  (sub-ID — one per stored file)
      └── contentmultimap:
            ├── filestorage::chunk.0  → encrypted data (999KB)
            ├── filestorage::chunk.1  → encrypted data (999KB)
            ├── ...
            ├── filestorage::filename → "document.pdf"
            ├── filestorage::mimetype → "application/pdf"
            ├── filestorage::filesize → "18586159"
            ├── filestorage::hash     → "<sha256>"
            └── filestorage::chunkcount → "19"
```

### Setup Steps

1. **Register namespace identity** with a TOKEN currency (`definecurrency` with `options: 32, proofprotocol: 2`)
2. **Mint tokens** (required before sub-IDs can be registered)
3. **Register VDXF keys** — get i-addresses via `getvdxfid`:
   ```bash
   verus -chain=vrsctest getvdxfid "filestorage::chunk.0"
   # Returns: { "vdxfid": "iRwRJ2JxndAkmdRGs7yLF6iheFReBzKkLR", ... }
   ```
4. **Store DefinedKeys** on the namespace identity under key `iD3yzD6KnrSG75d8RzirMD6SyvrAS2HxjH`
5. **Register sub-IDs** per file (e.g., `trial1.filestorage@`)
6. **Upload chunks** to the sub-ID's contentmultimap using VDXF key i-addresses

---

## Key Gotchas

### 1. Sub-IDs on centralized currencies need full identity spec
```json
{
  "parent": "<currency_i-address>",
  "name": "<sub-id-name>",
  "primaryaddresses": ["<R-address>"],
  "minimumsignatures": 1,
  "contentmultimap": { ... }
}
```
Omitting `parent`, `primaryaddresses`, or `minimumsignatures` causes `bad-txns-failed-precheck`.

### 2. Sequential identity updates only
Each `updateidentity` spends the previous identity output. You **cannot parallelize** uploads to the same identity — each must wait for the previous to confirm (~60s per block).

### 3. Silent truncation of raw contentmultimap data
Raw hex strings >~5KB in contentmultimap are silently truncated — no error returned. Always use the `"data"` wrapper for anything above a few KB.

### 4. Track your txids
The system does NOT store upload txids in identity metadata. Track them during upload or store them in a manifest. Without txids, `decryptdata` cannot locate BreakApart chunks.

### 5. CPU-intensive processing
Each 999KB chunk takes 3–5 minutes to process (encryption + BreakApart into ~177 outputs). Mining competes for CPU — consider reducing mining threads during bulk uploads.

### 6. `definecurrency` requires manual broadcast
`definecurrency` returns the transaction object but does NOT auto-broadcast. Extract the hex and call `sendrawtransaction` manually.

### 7. Two entries per chunk key in `getidentitycontent`
Each chunk key returns two datadescriptor entries: `[0]` is the encrypted data reference (use this), `[1]` is the signature proof.

---

## How Data Gets Stored (Protocol Detail)

### Small Data (< 6KB)

For small data, it's straightforward — store it directly in the identity's `contentmultimap` via `updateidentity`. The data goes into a single transaction output.

### Medium Data (6KB – 2MB)

When data exceeds `MAX_SCRIPT_ELEMENT_SIZE` (~6,000 bytes with PBaaS active), the protocol automatically splits it:

1. `updateidentity` detects the oversized data
2. Calls `CNotaryEvidence::BreakApart()` internally
3. Each chunk gets a `CMultiPartDescriptor` header with:
   - `index` — sequential chunk number (0, 1, 2, ...)
   - `totalLength` — total bytes of the complete data
   - `start` — byte offset of this chunk
4. Each chunk becomes a separate transparent output **in the same transaction**

A single transaction can be up to **2MB** (the maximum block size), so ~348 chunks of ~5,744 bytes each can fit in one tx.

### Large Data (> 2MB)

For data larger than 2MB, you need multiple transactions across multiple blocks:

1. Split your data into segments, each under the 1,000,000-byte limit
2. Store each segment via a separate `updateidentity` call with the data wrapper
3. Use different VDXF keys per chunk (e.g., `chunk.0`, `chunk.1`, ...)
4. `getidentitycontent` retrieves all entries; `decryptdata` retrieves each chunk by txid

## Size Limits

| What | Limit | Notes |
|------|-------|-------|
| Single script element | ~6,000 bytes | `MAX_SCRIPT_ELEMENT_SIZE_PBAAS` |
| Chunk after overhead | ~5,744 bytes | Element minus 256 byte overhead |
| Raw contentmultimap hex | 5,500 bytes (11,000 hex chars) | Above this causes `bad-txns-failed-precheck` |
| Data wrapper input | 1,000,000 bytes | Hard limit in `signdata` |
| Single transaction | 2,000,000 bytes (2MB) | Can fill an entire block |
| Single block | 2,000,000 bytes (2MB) | `MAX_BLOCK_SIZE` |
| Multiple blocks | **Unlimited** | Via sequential `updateidentity` txs |

### Practical Examples

| File Size | Chunks Needed | Time (~60s/block + processing) | Est. Cost (updateidentity) |
|-----------|--------------|-------------------------------|---------------------------|
| 5 KB | 1 | ~1 minute | ~0.0001 (raw) or ~6 VRSCTEST |
| 100 KB | 1 | ~4 minutes | ~6 VRSCTEST |
| 500 KB | 1 | ~4 minutes | ~6 VRSCTEST |
| 1 MB | 1 | ~4 minutes | ~6–7 VRSCTEST |
| 5 MB | 6 | ~30 minutes | ~40 VRSCTEST |
| 10 MB | 11 | ~55 minutes | ~72 VRSCTEST |
| 18.6 MB | 19 | ~2 hours | ~125 VRSCTEST |

---

## The Key Functions

### `CNotaryEvidence::BreakApart()` — The Splitter

**Location**: `src/primitives/block.cpp:820`

This is the core chunking function. It:
1. Serializes the entire evidence object to a byte array
2. Iterates through the bytes, cutting chunks of `maxChunkSize`
3. Wraps each chunk in a `CEvidenceData` with `TYPE_MULTIPART_DATA` and a `CMultiPartDescriptor`
4. Returns a vector of `CNotaryEvidence` objects, each containing one chunk

```
Data: [AAAA BBBB CCCC DDDD EEEE]
           ↓
BreakApart(chunkSize=4)
           ↓
Chunk 0: [AAAA] index=0, start=0,  totalLength=20
Chunk 1: [BBBB] index=1, start=4,  totalLength=20
Chunk 2: [CCCC] index=2, start=8,  totalLength=20
Chunk 3: [DDDD] index=3, start=12, totalLength=20
Chunk 4: [EEEE] index=4, start=16, totalLength=20
```

### `CNotaryEvidence(evidenceVec)` — The Reassembler

**Location**: `src/primitives/block.cpp:851`

The constructor that takes a vector of evidence chunks and reassembles them:
1. Validates first chunk is TYPE_MULTIPART_DATA
2. Reads `totalLength` from first chunk
3. Iterates all chunks, validating:
   - Sequential index numbers
   - Matching total length
   - Correct byte offset
4. Concatenates all chunk data
5. Deserializes the complete original object

If any validation fails, the result is marked `VERSION_INVALID`.

### `signdata` — The MMR Builder

**Location**: `src/wallet/rpcwallet.cpp:1231`

Creates a Merkle Mountain Range from one or more data objects. Supports:
- **Files**: `"filename": "/path/to/file"`
- **Text messages**: `"message": "hello world"`
- **Hex data**: `"serializedhex": "deadbeef"`
- **Base64 data**: `"serializedbase64": "..."`
- **Pre-computed hashes**: `"datahash": "256bithex"`
- **VDXF data**: `"vdxfdata": {...}`

Returns a `CMMRDescriptor` containing:
- The MMR root hash (signed by the identity)
- All leaf hashes
- All data descriptors with the actual data

### `getidentitycontent` — The Retrieval RPC

**Location**: `src/rpc/pbaasrpc.cpp:17215`

Retrieves aggregated contentmultimap data across a height range:

```bash
verus getidentitycontent "name@" [heightstart] [heightend] [txproofs] [txproofheight] [vdxfkey] [keepdeleted]
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| `name@` | required | Identity to query |
| `heightstart` | 0 | Start block height |
| `heightend` | current | End block height (-1 for mempool) |
| `txproofs` | false | Include transaction proofs |
| `txproofheight` | heightend | Proof reference height |
| `vdxfkey` | null | Filter by specific VDXF key |
| `keepdeleted` | false | Include deleted entries |

This calls `GetAggregatedIdentityMultimap()` internally, which walks through every identity update in the height range and collects all contentmultimap entries.

---

## The Reference System

Data stored on-chain can be referenced from anywhere using `CCrossChainDataRef`, which supports three reference types:

### 1. Cross-Chain UTXO Reference (`CPBaaSEvidenceRef`)
Points to a specific transaction output:
- Transaction hash + output index
- Object number + sub-object number
- System ID (for cross-chain)
- Data hash for verification

### 2. Identity Multimap Reference (`CIdentityMultimapRef`)
Points to data stored in an identity's contentmultimap:
- Identity i-address
- VDXF key
- Block height range (start/end)
- Data hash for verification
- System ID (for cross-chain)

This is the key mechanism for cross-block data retrieval. When you store a large file across multiple blocks, you can create a reference that says "get all data from identity X, key Y, between blocks 1000 and 1003."

### 3. URL Reference (`CURLRef`)
Points to external data:
- URL string (up to 4096 characters)
- Optional data hash for verification

This enables hybrid on-chain/off-chain storage: store the hash on-chain, data off-chain, and the protocol can verify integrity.

## Data Operations on contentmultimap

The `GetAggregatedIdentityMultimap` function supports these operations via `ContentMultiMapRemoveKey`:

| Action | Operation | Effect |
|--------|-----------|--------|
| 1 | `ACTION_REMOVE_ONE_KEYVALUE` | Remove one specific value under a key (by hash) |
| 2 | `ACTION_REMOVE_ALL_KEYVALUE` | Remove all values matching a hash under a key |
| 3 | `ACTION_REMOVE_ALL_KEY` | Remove a VDXF key and all its values |
| 4 | `ACTION_CLEAR_MAP` | Clear all entries from the map |

This means you can update and delete on-chain data — the aggregation system processes these operations in block order.

Pass `contentmultimapremove` as a field in the `updateidentity` JSON. It is processed **before** any `contentmultimap` additions in the same transaction, so you can atomically remove old values and write new ones in a single call.

### Action 3: Remove Entire Key

Removes a VDXF key and all its values from the contentmultimap.

```bash
verus updateidentity '{
  "name": "myidentity",
  "contentmultimapremove": {
    "version": 1,
    "action": 3,
    "entrykey": "iLy373iaKafmRCY43ahty4m8aLQx32y8Fh"
  }
}'
```

### Action 4: Clear Entire Map

Wipes all entries from the contentmultimap. Useful for schema migrations.

```bash
verus updateidentity '{
  "name": "myidentity",
  "contentmultimapremove": {
    "version": 1,
    "action": 4
  }
}'
```

### Action 1: Remove One Value by Hash

Removes a single value under a key, identified by its hash.

```bash
verus updateidentity '{
  "name": "myidentity",
  "contentmultimapremove": {
    "version": 1,
    "action": 1,
    "entrykey": "iLy373iaKafmRCY43ahty4m8aLQx32y8Fh",
    "valuehash": "<hex_hash_of_value>"
  }
}'
```

### Action 2: Remove All Values Matching Hash

Same as action 1 but removes **all** values matching the hash under the key (useful if the same value was written multiple times).

### JSON Format Reference

```
contentmultimapremove {
  version: 1              // Always 1
  action: 1 | 2 | 3 | 4
  entrykey?: string       // Required for actions 1–3 (VDXF i-address)
  valuehash?: string      // Required for actions 1–2 (hex hash of value)
}
```

### Key Findings from Testing

1. **`updateidentity` appends — it does NOT replace.** To update a value, you must first remove the old one with `contentmultimapremove`, then write the new value. A plain `updateidentity` adds entries on top of existing ones.

2. **Atomic remove + write.** `contentmultimapremove` and `contentmultimap` can be in the same `updateidentity` call. The remove is processed first.

3. **Action 4 (clear) confirmed on VRSCTEST** — cleared an identity with 8 parent group keys and re-wrote 25 flat entries successfully.

4. **Action 3 (remove key) confirmed on VRSCTEST** — individual VDXF keys removed cleanly.

5. **`getidentitycontent` still shows history after removal** — `contentmultimapremove` only affects the current aggregated state (visible via `getidentity`). Historical entries remain in `getidentitycontent`.

6. **`returntx=true` for dry runs** — pass `true` as the second argument to `updateidentity` to get a signed raw transaction without broadcasting it.

### Practical Use Case: Schema Migration

```bash
# Phase 1: Clear everything (atomic — also writes new format in same tx if desired)
verus updateidentity '{"name":"myid","contentmultimapremove":{"version":1,"action":4}}'

# Wait for confirmation (~60s)

# Phase 2: Write new format
verus updateidentity '{"name":"myid","contentmultimap":{"iAddr1":["hexvalue1"],"iAddr2":["hexvalue2"]}}'
```

## Encryption

The entire system supports optional encryption via Sapling z-addresses:

```bash
verus signdata '{
  "address": "myidentity@",
  "filename": "/path/to/secret.pdf",
  "createmmr": true,
  "encrypttoaddress": "zs1..."
}'
```

When `encrypttoaddress` is specified:
- Each data descriptor is encrypted to the z-address
- The MMR root and hashes can also be encrypted
- All data can be decrypted with the incoming viewing key
- Individual sub-objects can have unique symmetric decryption keys (SSKs)

This enables **private on-chain storage** where only the z-address holder can read the data.

## The CMMRDescriptor — Structured Multi-Object Container

When you store multiple objects together, they're organized in a Merkle Mountain Range:

```
                    MMR Root (signed)
                   /                \
              Hash(0,1)          Hash(2,3)
             /        \         /        \
         Hash(0)   Hash(1)  Hash(2)   Hash(3)
            |         |        |         |
         Data 0    Data 1   Data 2    Data 3
         (file)    (file)   (text)    (image)
```

Each leaf (data object) has:
- Raw data bytes
- Optional label
- Optional MIME type
- Optional salt (privacy — hides data from hash observers)
- Optional encryption

The MMR root is signed by the identity, providing cryptographic proof that:
- All data objects are authentic
- No objects have been added, removed, or modified
- The signer authorized this exact set of data

## Hash Types

Four hash algorithms are supported throughout the system:

| Type | Name | Use |
|------|------|-----|
| `sha256` | SHA-256 | Default for single objects |
| `sha256D` | Double SHA-256 | Bitcoin-style |
| `blake2b` | BLAKE2b | Default for MMR trees (fast) |
| `keccak256` | Keccak-256 | Ethereum-compatible |

## Architecture Diagram

```
    ┌─────────────────────────────────────────────────────┐
    │                   User Data                         │
    │            (files, messages, hex, etc.)              │
    └──────────────────────┬──────────────────────────────┘
                           │
                    ┌──────▼──────┐
                    │  signdata   │  Build MMR, hash, sign, encrypt
                    └──────┬──────┘
                           │
                  ┌────────▼────────┐
                  │ updateidentity  │  Store in contentmultimap
                  └────────┬────────┘
                           │
                    ┌──────▼──────┐
                    │  < 6KB ?    │
                    └──┬──────┬──┘
                  YES  │      │  NO
                       │      │
              ┌────────▼┐  ┌──▼───────────┐
              │ Single  │  │ BreakApart() │
              │ output  │  │ N chunks     │
              └────┬────┘  └──┬───────────┘
                   │          │
                   │    ┌─────▼─────┐
                   │    │ Output 0  │──┐
                   │    │ Output 1  │  │ Same transaction
                   │    │ Output N  │──┘ (up to 2MB)
                   │    └─────┬─────┘
                   │          │
              ┌────▼──────────▼────┐
              │   On-Chain Block   │  Mined into blockchain
              └────────┬───────────┘
                       │
             ┌─────────▼──────────┐
             │ getidentitycontent │  Retrieve + aggregate
             └─────────┬──────────┘
                       │
              ┌────────▼────────┐
              │  Reassemble()   │  Validate + concatenate chunks
              └────────┬────────┘
                       │
              ┌────────▼────────┐
              │  Original Data  │  Fully reconstructed
              └─────────────────┘
```

## Hidden/Undocumented RPC

| Command | Category | Notes |
|---------|----------|-------|
| `hashdata` | `hidden` | Not visible in `help` output. Hashes arbitrary hex data with configurable hash type and personal string. |

```bash
# Usage (undocumented):
verus hashdata "hexdata" "hashtype" "personalstring"
```

## Use Cases

### Decentralized Document Storage
Store contracts, certificates, or legal documents permanently on-chain with cryptographic proof of authorship via the signing identity.

### NFT Media Storage
Store the actual media for NFTs on-chain rather than relying on IPFS or centralized servers. The MMR provides integrity verification.

### Encrypted Private Data
Using Sapling z-address encryption, store private data that only specific parties can decrypt. Useful for medical records, private keys, or confidential business data.

### Agent Data Storage
AI agents can store their state, models, or outputs on-chain under their VerusID, creating a permanent, verifiable record of their work.

### Cross-Chain Data Availability
Using `CCrossChainDataRef`, data stored on one PBaaS chain can be referenced and verified from another chain without moving the actual data.

### Versioned Data with History
Each `updateidentity` creates a new version. Using `getidentitycontent` with height ranges, you can retrieve any historical version of the data. The `ContentMultiMapRemoveKey` operations enable clean updates.

## Important Notes

- **Cost**: Each transaction requires fees. Storing large data means paying proportionally more in transaction fees. See the [cost breakdown](#cost-breakdown) above for real numbers.
- **Permanence**: On-chain data is permanent. Even "deleted" entries remain in the blockchain history — the removal operations only affect the aggregated view.
- **Block time**: Each block takes ~60 seconds. Multi-block storage of very large files will take proportionally longer.
- **Pruning**: Nodes that prune old blocks may not have historical data. Use `txproofs` parameter for portable proofs.

## Source Code References

| Component | File | Line |
|-----------|------|------|
| `CMultiPartDescriptor` | `src/primitives/block.h` | 1153 |
| `CEvidenceData` | `src/primitives/block.h` | 1170 |
| `CIdentityMultimapRef` | `src/primitives/block.h` | 2504 |
| `CCrossChainDataRef` | `src/primitives/block.h` | 2669 |
| `BreakApart()` | `src/primitives/block.cpp` | 820 |
| `Reassemble constructor` | `src/primitives/block.cpp` | 851 |
| `CMMRDescriptor` | `src/pbaas/vdxf.h` | 1391 |
| `CDataDescriptor` | `src/pbaas/vdxf.h` / `vdxf.cpp` | 697+ |
| `ContentMultiMapRemove` | `src/pbaas/identity.cpp` (daemon), `src/pbaas/ContentMultiMapRemove.ts` (TS) | — |
| `GetAggregatedIdentityMultimap` | `src/pbaas/identity.cpp` | 454 |
| `signdata` | `src/wallet/rpcwallet.cpp` | 1231 |
| `updateidentity` (chunking trigger) | `src/rpc/pbaasrpc.cpp` | 16186 |
| `getidentitycontent` | `src/rpc/pbaasrpc.cpp` | 17215 |
| `hashdata` (hidden) | `src/rpc/misc.cpp` | 746 |
| `MAX_SCRIPT_ELEMENT_SIZE_PBAAS` | `src/script/script.h` | 36 |
| `MAX_BLOCK_SIZE` | `src/consensus/consensus.h` | 22 |

## Related Pages

- [Data Descriptor](data-descriptor.md) — Deep dive into `CDataDescriptor`, `CMMRDescriptor`, and the structured data format used by `signdata`
- [VDXF Data Pipeline](vdxf-data-pipeline.md) — End-to-end flow from `signdata` through `updateidentity` to on-chain storage, including the encryption and BreakApart pipeline


--- PAGE: concepts/privacy-shielded-tx.md ---

# Privacy & Shielded Transactions

Verus supports full transaction privacy using **Sapling zero-knowledge proofs**. This guide explains how privacy works, the commands involved, and best practices.

## Transparent vs Shielded Addresses

| | Transparent | Shielded |
|---|------------|----------|
| **Prefix** | `R...` | `zs...` |
| **Balances** | Public on blockchain | Hidden |
| **Amounts** | Visible | Encrypted |
| **Sender/Receiver** | Visible | Hidden |
| **Memo field** | No | Yes (512 bytes, encrypted) |
| **Speed** | Fast | Slightly slower (proof generation) |

Both types coexist on the same chain. You choose your privacy level per transaction.

## How It Works — Sapling Protocol

Verus uses the **Sapling** upgrade of Zcash's zero-knowledge proof system. When you send a shielded transaction:

1. A **zero-knowledge proof** proves the transaction is valid without revealing details
2. The sender, receiver, and amount are encrypted on-chain
3. Only the parties involved (and anyone with a viewing key) can see the details

Sapling proofs are fast to generate (a few seconds) and small in size.

## Sending Private Transactions

### Create a Shielded Address

```bash
./verus z_getnewaddress
```

Returns a `zs...` address.

> **Important limitation:** Z-addresses can only hold the **native blockchain currency** (e.g., VRSC on the Verus chain). Tokens and basket currencies cannot be held in shielded addresses.

> **Tip:** If your VerusID has a linked z-address, you can send native currency to it using the `VerusID@:private` syntax (e.g., `sendcurrency "*" '[{"address":"MyID@:private","amount":10}]'`).

### Shield Transparent Coins

Move coins from a transparent address to a shielded one:

```bash
./verus z_sendmany "RYourTransparentAddress" '[{"address":"zsYourShieldedAddress","amount":10.0}]'
```

This returns an **operation ID** (e.g., `opid-abc123`). Check its status:

```bash
./verus z_getoperationstatus '["opid-abc123"]'
```

### Shield Mining/Staking Rewards

> **Note:** As of block **800,200** on mainnet, coinbase shielding is **no longer required** before spending mining/staking rewards. Prior to this block, coinbase outputs had to be shielded (sent to a z-address and back) before they could be spent transparently.

Miners can shield coinbase rewards directly:

```bash
./verus z_shieldcoinbase "RYourMiningAddress" "zsYourShieldedAddress"
```

Or shield from all transparent addresses:

```bash
./verus z_shieldcoinbase "*" "zsYourShieldedAddress"
```

### Send Privately (Shielded → Shielded)

For maximum privacy, send from a shielded address to another shielded address:

```bash
./verus z_sendmany "zsYourShieldedAddress" '[{"address":"zsRecipientAddress","amount":5.0,"memo":"encrypted memo here"}]'
```

The optional `memo` field lets you include an encrypted message (up to 512 bytes) visible only to the recipient.

### Check Shielded Balances

```bash
# Single shielded address
./verus z_getbalance "zsYourShieldedAddress"

# All balances (transparent + shielded)
./verus z_gettotalbalance
```

### View a Shielded Transaction

```bash
./verus z_viewtransaction "txid"
```

Shows decoded details of a shielded transaction — inputs, outputs, amounts, and memos — from your wallet's perspective.

## Viewing Keys

Viewing keys let a third party **see** your shielded transactions without the ability to **spend** your funds. Useful for audits, tax reporting, or monitoring.

### Export a Viewing Key

```bash
./verus z_exportviewingkey "zsYourShieldedAddress"
```

### Import a Viewing Key

```bash
./verus z_importviewingkey "viewing-key-string"
```

After importing, the wallet rescans the blockchain to find matching transactions.

> ⚠️ **Viewing keys reveal all transactions for that address.** Share them only with trusted parties.

## Encryption Addresses

VerusIDs can have encryption addresses for receiving encrypted messages:

```bash
./verus z_getencryptionaddress "zsYourShieldedAddress"
```

This is used in protocol-level encrypted messaging between VerusIDs.

## Privacy Best Practices

### Do ✅

- **Use shielded-to-shielded** transactions for maximum privacy
- **Shield all at once** rather than in recognizable amounts
- **Wait between shielding and spending** to break timing correlation
- **Use unique shielded addresses** for different purposes
- **Shield mining rewards** with `z_shieldcoinbase` before spending

### Don't ❌

- **Don't shield and immediately unshield** the same amount — this links the transactions
- **Don't reuse shielded addresses** publicly — each exposure reduces privacy
- **Don't send exact round-trip amounts** (e.g., shield 10, unshield 10) — amount correlation
- **Don't ignore transparent change** — it can leak information

### Privacy Levels

| Transaction Type | Privacy Level |
|-----------------|---------------|
| Transparent → Transparent | None (fully public) |
| Transparent → Shielded | Partial (shielding is visible, destination hidden) |
| Shielded → Shielded | **Full** (sender, receiver, amount all hidden) |
| Shielded → Transparent | Partial (source hidden, destination visible) |

## Transaction Flow Summary

```
Mining Reward (coinbase)
  └─ z_shieldcoinbase ──→ Shielded Pool
                              │
Transparent Balance            │
  └─ z_sendmany ──────→ Shielded Pool
                              │
                     z_sendmany (zs→zs)
                              │
                         Full Privacy ✓
```

## Related

- [Send a Private Transaction](../how-to/send-private-transaction.md) — Step-by-step how-to
- [Wallet Setup](../getting-started/wallet-setup.md) — Address types explained
- [Command Reference: Wallet](../command-reference/wallet.md) — All z_* commands


--- PAGE: concepts/utxo-model.md ---

# Understanding UTXOs on Verus

> How Verus tracks ownership of funds — the "digital cash" model explained

---

## What Is a UTXO?

UTXO stands for **Unspent Transaction Output**. It's how Verus (and Bitcoin) tracks who owns what. Instead of maintaining account balances like a bank, the blockchain tracks individual "chunks" of coins.

Think of it like physical cash:

```
Bank Account Model (Ethereum):
  Alice's balance: 150 VRSC
  → One number that goes up and down

UTXO Model (Verus/Bitcoin):
  Alice has:
  ├─ 50 VRSC   (received from mining reward)
  ├─ 30 VRSC   (received from Bob)
  └─ 70 VRSC   (change from a previous transaction)
  → Three separate "coins" that add up to 150 VRSC
```

Each UTXO is like a bill in your wallet. You don't have "a balance" — you have a collection of individual unspent outputs from previous transactions.

---

## How Transactions Work with UTXOs

When you send VRSC, you don't subtract from a balance. You **spend one or more UTXOs** and create new ones.

### Example: Alice sends 45 VRSC to Bob

Alice has three UTXOs: 50, 30, and 70 VRSC.

```
INPUTS (UTXOs being spent):         OUTPUTS (new UTXOs created):
┌─────────────────────┐             ┌──────────────────────┐
│ Alice's 50 VRSC     │────────────→│ Bob: 45 VRSC         │  (Bob's new UTXO)
└─────────────────────┘             │ Alice: 4.9999 VRSC   │  (change back to Alice)
                                    │ Fee: 0.0001 VRSC     │  (miner fee)
                                    └──────────────────────┘
```

What happened:
1. Alice's 50 VRSC UTXO is **consumed** (spent entirely — you can't partially spend a UTXO)
2. A new 45 VRSC UTXO is created for Bob
3. A new 4.9999 VRSC UTXO is created as **change** back to Alice
4. The 0.0001 VRSC difference is the transaction fee

Alice's remaining UTXOs are now: **4.9999**, 30, and 70 VRSC.

> **Key insight:** UTXOs are always spent in full. If you have a 50 VRSC UTXO and want to send 10, the transaction consumes the entire 50 and sends you 39.9999 back as change. Just like paying with a $50 bill for a $10 item — you get change back.

---

## UTXOs vs Account Model

| Feature | UTXO Model (Verus) | Account Model (Ethereum) |
|---------|-------------------|-------------------------|
| Balance tracking | Collection of unspent outputs | Single balance number |
| Privacy | Better — different UTXOs can use different addresses | Worse — all activity tied to one address |
| Parallel processing | UTXOs can be spent independently | Transactions must be sequential (nonce) |
| Transaction size | Larger (references all inputs) | Smaller (just amount + nonce) |
| Mental model | Physical cash / coins in a jar | Bank account balance |
| Double-spend prevention | Each UTXO can only be spent once | Nonce ordering prevents replays |

---

## Why UTXOs Matter for Verus Users

### 1. Staking

This is where UTXOs matter most on Verus. **Each UTXO stakes independently.** A larger UTXO has a higher probability of being selected to stake a block.

```
Scenario A — One big UTXO:
  └─ 10,000 VRSC (single UTXO)
  → Stakes frequently, but all-or-nothing

Scenario B — Many small UTXOs:
  ├─ 100 VRSC
  ├─ 100 VRSC
  ├─ ... (100 UTXOs)
  └─ 100 VRSC
  → Each has a small chance to stake independently
```

**Which is better?** Over time, the expected staking reward is roughly the same regardless of UTXO size. However:
- **Fewer large UTXOs** = simpler wallet, fewer transactions to track
- **More smaller UTXOs** = more frequent but smaller rewards (smoother income)
- **Very tiny UTXOs** (dust) = may never stake and waste resources

> **Staking eligibility:** A UTXO must have at least **150 confirmations** (~2.5 hours at ~60s/block) before it can stake.

### 2. Privacy

Each UTXO can be associated with a different address. When you receive VRSC, your wallet may generate a new address for each transaction. This makes it harder for observers to link all your funds together.

However, when you **spend** multiple UTXOs in a single transaction, they become linked — an observer can infer they belong to the same person. This is called a **common input ownership heuristic**.

For maximum privacy, use [shielded transactions](privacy-shielded-tx.md) which hide UTXOs entirely using zero-knowledge proofs.

### 3. Transaction Fees

Transactions that consume more UTXOs (more inputs) are physically larger in bytes. Verus uses a flat 0.0001 VRSC fee for standard transactions, but extremely complex transactions with many inputs could cost more.

### 4. Currency Tokens

On Verus, tokens and currencies also use the UTXO model. When you hold 500 `yourapp` tokens, you might actually have several UTXOs:

```
Token UTXOs:
├─ 200 yourapp tokens (from minting)
├─ 150 yourapp tokens (from a trade)
└─ 150 yourapp tokens (from a payment)
```

These work exactly like VRSC UTXOs — spent in full, with change returned.

---

## Managing Your UTXOs

### View Your UTXOs

```bash
# List all unspent outputs in your wallet
./verus listunspent

# List UTXOs with at least 6 confirmations
./verus listunspent 6

# List UTXOs for a specific address
./verus listunspent 1 9999999 '["RYourAddress"]'
```

Each entry shows:
- `txid` — The transaction that created this UTXO
- `vout` — The output index within that transaction
- `amount` — How much VRSC this UTXO holds
- `confirmations` — How many blocks since it was created
- `spendable` — Whether your wallet can spend it

### Check UTXOs for Any Address (requires `-addressindex=1`)

```bash
# Get UTXOs for any address (not just your wallet)
./verus getaddressutxos '{"addresses":["RAddress..."]}'
```

### Consolidate UTXOs

If you have many small UTXOs (dust), you can consolidate them by sending your full balance to yourself:

```bash
# Send all to yourself — combines many UTXOs into one
./verus sendtoaddress "RYourAddress" $(./verus getbalance) "" "" true
```

The `true` at the end subtracts the fee from the amount, so it sends your entire balance.

### Split UTXOs for Staking

If you have one large UTXO and want to split it for more frequent staking rewards:

```bash
# Split into multiple UTXOs
./verus sendcurrency "*" '[
  {"address":"RYourAddress","amount":2500},
  {"address":"RYourAddress","amount":2500},
  {"address":"RYourAddress","amount":2500},
  {"address":"RYourAddress","amount":2500}
]'
```

This turns one 10,000 VRSC UTXO into four 2,500 VRSC UTXOs.

---

## UTXO Lifecycle

```
   Created                    Mature                    Spent
      │                         │                         │
      ▼                         ▼                         ▼
 ┌─────────┐  150 blocks   ┌─────────┐  Used as     ┌─────────┐
 │  New     │──────────────→│ Eligible│──input in──→ │ Spent   │
 │  UTXO    │  (~2.5 hrs)  │ to stake│  a new tx    │ (gone)  │
 └─────────┘               └─────────┘              └─────────┘
                                │                        │
                                │ Selected for staking   │ Creates new UTXOs
                                ▼                        ▼
                           ┌─────────┐             ┌─────────┐
                           │ Staking │             │ Change  │
                           │ reward  │             │ + Output│
                           └─────────┘             └─────────┘
                           (new UTXO,              (new UTXOs for
                            needs 150              recipient and
                            confirms               sender change)
                            again)
```

> **Important:** When a UTXO stakes successfully, it's consumed and a new UTXO is created with the original amount plus the staking reward. This new UTXO needs another 150 confirmations before it can stake again.

---

## Common Questions

**Q: Do I need to manage my UTXOs manually?**
A: For basic use, no. Your wallet handles UTXO selection automatically when you send transactions. UTXO management mainly matters for optimizing staking.

**Q: What is "dust"?**
A: Very small UTXOs (fractions of a coin) that cost more in transaction fees to spend than they're worth. They clutter your wallet and are unlikely to ever stake.

**Q: Why does my balance show different amounts in different commands?**
A: Some commands show only confirmed UTXOs, others include unconfirmed (mempool) transactions. Use `getbalance` for confirmed balance and `getunconfirmedbalance` for pending.

**Q: Can someone see my UTXOs?**
A: On the transparent chain, yes — anyone can query an address's UTXOs. Use [shielded addresses](privacy-shielded-tx.md) (z-addresses) if you want privacy. Note that z-addresses can only hold the native currency (VRSC), not tokens.

---

## Related Commands

- [`listunspent`](../command-reference/wallet.md#listunspent) — List your wallet's UTXOs
- [`getaddressutxos`](../command-reference/addressindex.md#getaddressutxos) — Query UTXOs for any address
- [`getaddressbalance`](../command-reference/addressindex.md#getaddressbalance) — Quick balance check by address
- [`sendcurrency`](../command-reference/multichain.md#sendcurrency) — Send funds (automatically selects UTXOs)
- [`z_sendmany`](../command-reference/wallet.md#z_sendmany) — Send with explicit source address

---

## Related Concepts

- [Mining and Staking](mining-and-staking.md) — How UTXOs participate in consensus
- [Privacy and Shielded Transactions](privacy-shielded-tx.md) — Hiding UTXOs with zero-knowledge proofs
- [Key Concepts](../introduction/key-concepts.md) — Foundational Verus concepts

---

*As of Verus v1.2.x.*


--- PAGE: concepts/vdxf-data-pipeline.md ---

# The VDXF Data Pipeline — From Application Data to On-Chain Storage

> How DefinedKey, DataDescriptor, and VdxfUniValue work together to create a complete structured data layer

---

## Overview

Verus has three complementary systems for structured on-chain data. Each solves a different problem:

| Component | Problem It Solves | Layer |
|---|---|---|
| [VdxfUniValue](vdxf-uni-value.md) | How to **serialize** typed data into bytes | Encoding |
| [DataDescriptor](data-descriptor.md) | How to **annotate** data with metadata | Container |
| [DefinedKey](vdxf-data-standard.md) | How to **label** keys so wallets can read them | Discovery |

Together, they form a pipeline:

```
         ┌──────────────────────────────────────────────────┐
         │               Application Layer                  │
         │  "Store app profile with name, type, version"    │
         └──────────────────────┬───────────────────────────┘
                                │
         ┌──────────────────────▼───────────────────────────┐
         │             DefinedKey (Labels)                   │
         │  Register human-readable names for your keys      │
         │  yourapp::data.v1.name → i...                     │
         │  Published on namespace owner's identity          │
         └──────────────────────┬───────────────────────────┘
                                │
         ┌──────────────────────▼───────────────────────────┐
         │          DataDescriptor (Container)               │
         │  Optional: wrap data with label, MIME, encryption │
         │  { label: "name", mime: "text/plain", data: ... } │
         └──────────────────────┬───────────────────────────┘
                                │
         ┌──────────────────────▼───────────────────────────┐
         │           VdxfUniValue (Serializer)               │
         │  Encode typed values into binary bytes            │
         │  String → key + version + length + UTF-8 bytes    │
         └──────────────────────┬───────────────────────────┘
                                │
         ┌──────────────────────▼───────────────────────────┐
         │           contentmultimap (Storage)               │
         │  { "i...": ["hex_bytes"] }                        │
         │  Stored on a VerusID on-chain                     │
         └──────────────────────────────────────────────────┘
```

---

## When to Use What

### Scenario 1: Simple App Profile (Most Common)

You just want to store key-value data on an identity — name, type, version, etc.

**What you need:**
- `VdxfUniValue` — to hex-encode your values
- `DefinedKey` — so wallets show key names instead of i-addresses
- DataDescriptor — **NOT needed** (overhead not worth it for simple fields)

```bash
# Store data with plain hex-encoded values
verus updateidentity '{
  "name": "alice.yourapp@",
  "parent": "i...",
  "contentmultimap": {
    "i...": ["416c696365"],          # yourapp::data.v1.name → "Alice"
    "i...": ["4149204167656e74"]     # yourapp::data.v1.type → "AI Agent"
  }
}'
```

Then publish DefinedKeys on the namespace identity (`yourapp@`) so wallets know each i-address means the corresponding field name.

### Scenario 2: Rich Content with Metadata

You're storing a document, image hash, or structured payload that benefits from a label and MIME type.

**What you need:**
- `DataDescriptor` — wrap the data with label + MIME type
- `VdxfUniValue` — serializes the DataDescriptor's inner data
- `DefinedKey` — optional (DataDescriptor already has its own label field)

```typescript
const descriptor = DataDescriptor.fromJson({
  version: 1,
  objectdata: { message: "Agent service agreement v2.1..." },
  label: "service-agreement",
  mimetype: "text/plain"
});

// Store the serialized descriptor
const hex = descriptor.toBuffer().toString('hex');
```

### Scenario 3: Encrypted Private Data

You're storing sensitive data (private credentials, encrypted messages) on-chain.

**What you need:**
- `DataDescriptor` — encryption fields (salt, EPK, IVK, SSK)
- `VdxfUniValue` — serializes the encrypted payload
- `DefinedKey` — optional

```typescript
const encrypted = DataDescriptor.fromJson({
  version: 1,
  flags: 0x07,  // encrypted + salt + EPK
  objectdata: "encrypted_hex_payload",
  salt: "random_salt_hex",
  epk: "encryption_public_key_hex"
});
```

### Scenario 4: Cross-Chain Data Proofs

You need to prove data exists on one chain to another chain.

**What you need:**
- `DataDescriptor` — hash vector support
- `MMRDescriptor` — Merkle Mountain Range proofs
- `CrossChainDataRef` — references to data on other chains
- All serialized through `VdxfUniValue`

---

## Example: Setting Up a Data Schema

Here's how to set up a data schema for your app:

### Step 1: Define the Schema Keys

```bash
# Generate VDXF keys under your namespace
verus getvdxfid "yourapp::data.v1.name"
# → i...

verus getvdxfid "yourapp::data.v1.type"
# → i...

verus getvdxfid "yourapp::data.v1.version"
# → i...
# ... one call per schema key
```

> See [Generating Your VDXF Key i-Addresses](#generating-your-vdxf-key-i-addresses) below for how these IDs are derived.

### Step 2: Store Data on Sub-Identities

```bash
# Hex-encode values
echo -n "Alice" | xxd -p  # → 416c696365
echo -n "AI Agent" | xxd -p  # → 4149204167656e74
echo -n "1.0" | xxd -p  # → 312e30

# Update the identity
verus updateidentity '{
  "name": "alice.yourapp@",
  "parent": "i...",
  "contentmultimap": {
    "i...": ["312e30"],            # yourapp::data.v1.version → "1.0"
    "i...": ["4149204167656e74"],  # yourapp::data.v1.type    → "AI Agent"
    "i...": ["416c696365"],        # yourapp::data.v1.name    → "Alice"
    "i...": ["616374697665"],      # yourapp::data.v1.status  → "active"
    "i...": [                      # yourapp::data.v1.capabilities
      "636f64652d726576696577",
      "73656375726974792d616e616c79736973"
    ]
  }
}'
```

### Step 3: Publish DefinedKeys (Next Step)

```typescript
import { DefinedKey } from 'verus-typescript-primitives';

const keys = [
  'yourapp::data.v1.name',
  'yourapp::data.v1.type',
  'yourapp::data.v1.version',
  // ... all schema keys
];

const hexBlobs = keys.map(uri => {
  const dk = new DefinedKey({
    version: DefinedKey.DEFINEDKEY_VERSION_CURRENT,
    flags: DefinedKey.DEFINEDKEY_DEFAULT_FLAGS,
    vdxfuri: uri,
  });
  return dk.toBuffer().toString('hex');
});

// Publish on yourapp@ identity
// verus updateidentity '{ "name": "yourapp@", "contentmultimap": { "<DATA_TYPE_DEFINEDKEY>": [...hexBlobs] } }'
```

### Result

After all three steps:
1. App data is stored on SubIDs with proper VDXF keys ✅
2. Keys are scoped to the `yourapp` namespace ✅
3. (Pending) Wallets can display human-readable labels via DefinedKeys

---

## Decision Guide

```
Do you need encryption?
  YES → Use DataDescriptor (encryption fields)
  NO  ↓

Is it simple key-value data?
  YES → Plain hex in contentmultimap + DefinedKey for labels
  NO  ↓

Does the data need a MIME type or label?
  YES → Use DataDescriptor (label + mimeType)
  NO  ↓

Is it a complex nested structure?
  YES → Use VdxfUniValue typed keys (DataStringKey, etc.)
  NO  → Plain hex encoding is fine
```

---

## Size Budget

All of this must fit within Verus transaction limits:

| Component | Typical Size |
|---|---|
| Single hex-encoded string value | 10-200 bytes |
| DataDescriptor (with label + MIME) | +50-200 bytes overhead |
| DefinedKey blob | ~60-80 bytes each |
| Full app profile (10 fields) | ~1-2 KB |
| 26 DefinedKey labels | ~2 KB |
| **Transaction limit** | **~4 KB per update** |

A typical app profile plus all its DefinedKey labels can fit in 2 transactions.

---

## Generating Your VDXF Key i-Addresses

VDXF IDs are **deterministic** — the same namespaced string always hashes to the
same i-address. Generate yours by running `getvdxfid` for each key:

```bash
verus getvdxfid "yourapp::data.v1.name"
verus getvdxfid "yourapp::data.v1.type"
verus getvdxfid "yourapp::data.v1.version"
# ... one call per schema key
```

Each call returns the i-address to use as the `contentmultimap` key for that field.
Because the mapping is deterministic, anyone who knows your namespace string can
re-derive the same IDs.

---

## Related

- [VDXF — Verus Data Exchange Format](vdxf-data-standard.md) — Foundation concepts
- [DefinedKey — Human-Readable Labels](vdxf-data-standard.md) — Key labeling
- [DataDescriptor — Structured Containers](data-descriptor.md) — Data wrappers
- [VdxfUniValue — Universal Serialization](vdxf-uni-value.md) — Type encoding
- [The Verus Identity System](identity-system.md) — Where all this data lives

---

*As of verus-typescript-primitives (generic-signed-request branch) on VRSCTEST.*


--- PAGE: concepts/vdxf-data-standard.md ---

# VDXF — Verus Data Exchange Format

> A universal, namespaced data standard for storing structured information on VerusIDs and across blockchains

---

## What Is VDXF?

VDXF (Verus Data Exchange Format) is a **namespaced key-value data standard** that provides a universal way to store, retrieve, and interpret structured data on the Verus blockchain. It solves a fundamental problem: how do you store arbitrary data on a blockchain in a way that any application can understand?

Think of VDXF as a universal schema system. Instead of each application inventing its own data format, VDXF provides:

- **Globally unique keys** — derived from human-readable names via the Verus namespace
- **Standardized encoding** — consistent hex-encoded values
- **Identity-anchored storage** — data attached to VerusIDs via content multimaps
- **Cross-chain portability** — data definitions work across all Verus-connected chains

```
Traditional blockchain data:
  key: "0x1a2b3c"  →  value: "0x4d5e6f"
  (What does this mean? Only the original app knows.)

VDXF data:
  key: "vrsc::identity.profile.name"  →  value: "Alice"
  (Any app can look up the key definition and interpret it.)
```

---

## Namespaced Keys

Every VDXF key is derived from a **human-readable name** using the `getvdxfid` command. The name follows a namespace pattern:

```
vrsc::identity.profile.name
 │        │       │      │
 │        │       │      └─ Specific field
 │        │       └──────── Category
 │        └──────────────── Domain
 └───────────────────────── Namespace (Verus root)
```

### Generating a VDXF Key

```bash
verus getvdxfid "vrsc::identity.profile.name"
```

Returns:
```json
{
  "vdxfid": "iK7a5JNJnbeuYWVHCDRpJosj4jY7NgjauS",
  "hash160result": "b9c55a975ec6e01e7f8e4eb1aab357b27d3e23e6",
  "qualifiedname": {
    "name": "vrsc::identity.profile.name",
    "namespace": "i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV"
  }
}
```

The `vdxfid` is a deterministic i-address derived from the name. The same name always produces the same key, on any chain, in any wallet. This is what makes VDXF universal.

### Key Namespacing

Keys are namespaced to prevent collisions. Different applications can define their own keys without conflicting:

```
vrsc::identity.profile.name     → Profile display name
vrsc::identity.profile.email    → Contact email
myapp::user.preferences.theme   → App-specific setting
agent::capabilities.tools       → Agent-specific schema
```

The namespace is typically the root currency or identity of the system defining the keys. The `vrsc::` namespace is reserved for Verus protocol-level definitions.

---

## Content Multimaps

The primary storage mechanism for VDXF data is the **content multimap** — a key-value store attached to every VerusID. Each identity can hold arbitrary VDXF data in its `contentmultimap` field.

### Structure

```json
{
  "contentmultimap": {
    "iK7a5JNJnbeuYWVHCDRpJosj4jY7NgjauS": [
      "4d79204e616d65"
    ],
    "iAnother_VDXF_Key_Here": [
      "76616c756531",
      "76616c756532"
    ]
  }
}
```

Key points:
- Keys are VDXF i-addresses (from `getvdxfid`)
- **Values are ALWAYS arrays** — even for single values, use the array format
- Values can be **hex-encoded** strings OR **structured JSON objects** (DataDescriptor objects)
- A single key can have **multiple values** (hence "multimap")

### Writing Data to an Identity

Use `updateidentity` to set content multimap data:

```bash
verus updateidentity '{
  "name": "myidentity@",
  "contentmultimap": {
    "iK7a5JNJnbeuYWVHCDRpJosj4jY7NgjauS": [
      "416c696365"
    ]
  }
}'
```

The hex value `416c696365` is "Alice" encoded in hexadecimal.

### Hex Encoding

All values in content multimaps are hex-encoded. To convert:

```bash
# String to hex
echo -n "Alice" | xxd -p
# Output: 416c696365

# Hex to string
echo "416c696365" | xxd -r -p
# Output: Alice
```

### ⚠️ ALWAYS Use Array Format

When setting content multimap values, **always use arrays**, even for single values:

```json
// ✅ CORRECT — array format
{
  "contentmultimap": {
    "iSomeVDXFKey": ["68656c6c6f"]
  }
}

// ❌ WRONG — scalar format (may cause errors)
{
  "contentmultimap": {
    "iSomeVDXFKey": "68656c6c6f"
  }
}
```

This is a common source of errors. The multimap expects arrays because each key can have multiple values.

---

## Use Cases

### 1. Identity Profiles

Store human-readable profile information on a VerusID:

```bash
# Define keys
verus getvdxfid "vrsc::identity.profile.name"        # → iKeyName
verus getvdxfid "vrsc::identity.profile.description"  # → iKeyDesc

# Set profile data
verus updateidentity '{
  "name": "alice@",
  "contentmultimap": {
    "iKeyName": ["416c696365"],
    "iKeyDesc": ["446576656c6f706572"]
  }
}'
```

Any application that knows the VDXF key definitions can read and display this profile data — wallets, explorers, social apps, etc.

### 2. Attestations and Credentials

Third parties can attest to claims about an identity. For example, a KYC provider could store a signed attestation:

```
Key: vrsc::identity.attestation.kyc.verified
Value: [signed attestation data with provider's signature]
```

Because attestations are on-chain and tied to identities, they're:
- **Verifiable** — anyone can check the attestation
- **Portable** — the identity carries its attestations everywhere
- **Revocable** — the attester can update or remove the attestation

### 3. Application Data

Applications can store configuration and state on identities:

```
Key: myapp::user.settings.notifications
Value: [hex-encoded JSON preferences]

Key: myapp::user.subscription.tier
Value: [hex-encoded tier level]
```

This means user data travels with the identity, not locked in a specific application's database.

### 4. Agent Schemas

AI agents on Verus can publish their capabilities, endpoints, and schemas via VDXF:

```
Key: agent::capabilities.tools
Value: [hex-encoded JSON array of tool definitions]

Key: agent::endpoints.api
Value: [hex-encoded API endpoint URL]

Key: agent::metadata.version
Value: [hex-encoded version string]
```

Other agents can discover and interpret these schemas by reading the identity's content multimap.

### 5. Data Anchoring

Store hashes of off-chain data on-chain for proof of existence:

```
Key: vrsc::data.hash.sha256
Value: [32-byte SHA-256 hash in hex]
```

This creates a timestamped, immutable record that specific data existed at a specific time.

---

## Cross-Chain Data Portability

Because VDXF keys are derived deterministically from names (not chain-specific IDs), the same key has the same meaning on every Verus-connected chain. A profile stored on a VerusID on the main chain can be read and interpreted by applications on any PBaaS (Public Blockchains as a Service) chain.

```
Verus Main Chain          PBaaS Chain A          PBaaS Chain B
     │                         │                       │
     │  vrsc::profile.name     │  vrsc::profile.name   │  vrsc::profile.name
     │  = same key everywhere  │  = same key everywhere │  = same key everywhere
     │                         │                       │
```

When an identity is exported cross-chain (via [sendcurrency](../command-reference/multichain.md#sendcurrency) with `exportid`), its content multimap data travels with it.

---

## Reading VDXF Data

### From an Identity

```bash
# Get full identity including content multimap
verus getidentity "alice@"

# For selective retrieval with height filtering, use getidentitycontent:
verus getidentitycontent "alice@" '{"heightstart":0,"heightend":0,"vdxfkey":"iKeyAddress"}'
```

`getidentitycontent` is the preferred retrieval command — it supports filtering by block height range, specific VDXF keys, and transaction proofs. `getidentity` returns the full current identity state including the `contentmultimap`.

### Interpreting Keys

To understand what a key represents:

```bash
# Look up the human-readable name for a VDXF key
# (reverse lookup — check known key registries)
verus getvdxfid "vrsc::identity.profile.name"
# Compare the returned vdxfid with the key in the multimap
```

In practice, applications maintain a registry of known VDXF key definitions so they can automatically interpret the data they encounter.

---

## Technical Details

### Key Derivation

VDXF keys are derived using the same process as VerusID addresses:

1. Take the qualified name string (e.g., `vrsc::identity.profile.name`)
2. Hash it with the namespace (the parent identity/currency)
3. Produce a Hash160 (RIPEMD-160 of SHA-256)
4. Encode as an i-address

This process is deterministic and collision-resistant.

### Value Encoding

Values are stored as raw hex bytes. The interpretation depends on the key definition:

| Data Type | Encoding | Example |
|---|---|---|
| UTF-8 string | Direct hex of UTF-8 bytes | `"Alice"` → `416c696365` |
| Integer | Little-endian hex | `42` → `2a00000000000000` |
| JSON | Hex of UTF-8 JSON string | `{"a":1}` → `7b2261223a317d` |
| Binary | Direct hex | Hash → `a1b2c3d4...` |
| Boolean | Single byte | true → `01`, false → `00` |

### Size Limits

Content multimap data is stored in identity transactions, which are subject to standard transaction size limits. For large data, store a hash or reference on-chain and keep the full data off-chain.

---

## Best Practices

1. **Use established namespaces** — Check if a VDXF key already exists for your use case before creating new ones. The `vrsc::` namespace covers common needs.

2. **Always use array format** — Even for single values. This prevents bugs and maintains consistency.

3. **Document your keys** — If you define custom VDXF keys, publish the definitions so others can interpret your data.

4. **Minimize on-chain data** — Store hashes on-chain and full data off-chain when possible. Blockchain storage is permanent and replicated to every node.

5. **Use hex encoding consistently** — All values must be hex-encoded. Double-check encoding before writing to avoid storing garbage data.

6. **Version your schemas** — Include version information in your VDXF key hierarchy (e.g., `myapp::v1.settings`) so you can evolve your data format over time.

---

## Key Takeaways

1. **Universal namespace** — VDXF provides globally unique, human-readable keys for any kind of data.
2. **Identity-anchored** — Data lives on VerusIDs, making it self-sovereign and portable.
3. **Always arrays** — Content multimap values MUST be in array format.
4. **Hex-encoded** — All values are hex-encoded bytes.
5. **Cross-chain** — Key definitions are portable across all Verus-connected chains.
6. **Open standard** — Any application can read and write VDXF data without permission or coordination.

---

## Related Commands

- `getvdxfid` — Derive a VDXF key from a human-readable name
- `getidentity` — Read an identity's full state including content multimap
- `getidentitycontent` — Selective retrieval with height filtering and key queries
- `updateidentity` — Write VDXF data to an identity
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Export identities (with their data) cross-chain

## Related Concepts

- [VerusID](../concepts/identity-system.md) — The identities that store VDXF data
- [Bridge and Cross-Chain](bridge-and-crosschain.md) — Cross-chain data portability

---

*As of Verus v1.2.x.*


--- PAGE: concepts/vdxf-uni-value.md ---

# VdxfUniValue — Universal Value Serialization

> The type system that lets Verus encode any structured data into bytes for on-chain storage

---

## What Is VdxfUniValue?

`VdxfUniValue` is Verus's **universal value serializer** — it takes structured data (strings, numbers, currency maps, signatures, descriptors, etc.) and encodes it into a compact binary format for on-chain storage. It's the bridge between JSON-friendly application data and raw blockchain bytes.

Every value stored in a contentmultimap ultimately gets serialized through VdxfUniValue. It's the encoding layer that sits beneath everything else.

```
Application Data (JSON)
        ↓
   VdxfUniValue.fromJson()
        ↓
   Binary bytes (Buffer)
        ↓
   Hex string → contentmultimap
        ↓
   On-chain storage
```

---

## Supported Data Types

VdxfUniValue recognizes a fixed set of VDXF system keys, each corresponding to a data type:

| System Key | Type | Size |
|---|---|---|
| `DataByteKey` | Single byte | 1 byte |
| `DataInt16Key` / `DataUint16Key` | 16-bit integer | 2 bytes |
| `DataInt32Key` / `DataUint32Key` | 32-bit integer | 4 bytes |
| `DataInt64Key` | 64-bit integer | 8 bytes |
| `DataUint160Key` | i-address (Hash160) | 20 bytes |
| `DataUint256Key` | 256-bit hash | 32 bytes |
| `DataStringKey` | UTF-8 string | variable |
| `DataByteVectorKey` | Raw byte vector | variable |
| `DataCurrencyMapKey` | Currency → amount map | variable |
| `DataRatingsKey` | Rating object | variable |
| `DataTransferDestinationKey` | Transfer destination | variable |
| `ContentMultiMapRemoveKey` | Multimap removal | variable |
| `CrossChainDataRefKey` | Cross-chain reference | variable |
| `DataDescriptorKey` | Data descriptor | variable |
| `MMRDescriptorKey` | MMR descriptor | variable |
| `SignatureDataKey` | Signature data | variable |
| `CredentialKey` | Credential | variable |
| `DataUint64Key` | 64-bit unsigned integer | 8 bytes |
| `DataVectorKey` | Generic vector | variable |
| `DataInt32VectorKey` | Vector of int32 | variable |
| `DataInt64VectorKey` | Vector of int64 | variable |
| `TypeDefinitionKey` | Type definition | variable |
| `EncryptionDescriptorKey` | Encryption descriptor | variable |
| `SaltedDataKey` | Salted (hashed) data | variable |
| `URLKey` | URL reference | variable |
| `UTXORefKey` | UTXO reference | variable |
| `MultimapKey` | Identity multimap key | variable |
| `MultimapRemoveKey` | Identity multimap removal | variable |
| `ProfileMediaKey` | Profile media attachment | variable |
| `ZMemoMessageKey` | Z-address memo message | variable |
| `ZMemoSignatureKey` | Z-address memo signature | variable |
| `MMRHashesKey` | MMR hashes | variable |
| `MMRLinksKey` | MMR links | variable |

Each type has its own serialization format. VdxfUniValue handles dispatch automatically based on the key.

---

## How It Works

### Encoding (JSON → Bytes)

```typescript
import { VdxfUniValue } from 'verus-typescript-primitives';
import * as VDXF_Data from 'verus-typescript-primitives/vdxf/vdxfdatakeys';

// Encode a string
const uni = VdxfUniValue.fromJson({
  [VDXF_Data.DataStringKey.vdxfid]: "Hello, Verus!"
});
const bytes = uni.toBuffer();

// Encode raw hex data
const raw = VdxfUniValue.fromJson("48656c6c6f");
const rawBytes = raw.toBuffer();

// Encode a message (shorthand)
const msg = VdxfUniValue.fromJson({ message: "Hello" });
```

### Decoding (Bytes → Structured Data)

```typescript
const uni = new VdxfUniValue();
uni.fromBuffer(someBuffer);

const json = uni.toJson();
// Returns the structured data with type keys
```

### Shorthand Inputs

VdxfUniValue accepts several shorthand formats:

```typescript
// Plain hex string → stored as raw bytes
VdxfUniValue.fromJson("48656c6c6f");

// Plain UTF-8 string (non-hex) → stored as UTF-8 bytes
VdxfUniValue.fromJson("Hello");

// Message object → stored as UTF-8 bytes
VdxfUniValue.fromJson({ message: "Hello" });

// Serialized hex → stored as raw bytes
VdxfUniValue.fromJson({ serializedhex: "48656c6c6f" });

// Serialized base64 → decoded and stored
VdxfUniValue.fromJson({ serializedbase64: "SGVsbG8=" });
```

---

## Multi-Value Arrays

VdxfUniValue internally stores an **array of key-value pairs**, supporting multiple typed values in sequence:

```typescript
const uni = VdxfUniValue.fromJson([
  { [VDXF_Data.DataStringKey.vdxfid]: "Alice" },
  { [VDXF_Data.DataUint32Key.vdxfid]: 42 },
  { [VDXF_Data.DataStringKey.vdxfid]: "Additional info" }
]);
```

This is serialized as a contiguous byte stream — each value tagged with its type key, version, and length.

---

## Binary Format

For typed values (string, byte vector, complex objects), the wire format is:

```
[20-byte key hash160] [varint version] [compact size] [data bytes]
```

For fixed-size primitives (byte, int16, int32, int64, uint160, uint256), just the raw bytes are written — no key prefix, no length:

```
[raw bytes of the value]
```

This means VdxfUniValue is **not self-describing for primitives** — you need to know the expected type from context (the contentmultimap key tells you what to expect).

---

## Role in the Data Pipeline

VdxfUniValue is the **serialization layer** in Verus's data stack:

```
┌─────────────────────────────────┐
│  DefinedKey                     │  ← Labels (what keys mean)
├─────────────────────────────────┤
│  DataDescriptor                 │  ← Containers (metadata + encryption)
├─────────────────────────────────┤
│  VdxfUniValue                   │  ← Serialization (encode/decode typed values)
├─────────────────────────────────┤
│  contentmultimap                │  ← Storage (on-chain key-value store)
├─────────────────────────────────┤
│  VerusID                        │  ← Identity (owns the data)
└─────────────────────────────────┘
```

- **DataDescriptor** uses VdxfUniValue to serialize its `objectdata` field
- **contentmultimap** values are VdxfUniValue-encoded bytes
- **DefinedKey** operates above this layer — it labels keys, not values

---

## Complex Type Examples

### Currency Map

```typescript
// Store a mapping of currency → amount
VdxfUniValue.fromJson({
  [VDXF_Data.DataCurrencyMapKey.vdxfid]: {
    "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2S4": "100.0",
    "i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV": "50.5"
  }
});
```

### Rating

```typescript
VdxfUniValue.fromJson({
  [VDXF_Data.DataRatingsKey.vdxfid]: {
    version: 1,
    trustLevel: 2,
    ratings: { "iSomeKey": "0500000000" }
  }
});
```

### Signature Data

```typescript
VdxfUniValue.fromJson({
  [VDXF_Data.SignatureDataKey.vdxfid]: {
    version: 1,
    systemID: "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2S4",
    hashType: 1,
    signatureHash: "abc123...",
    identityID: "iSomeIdentity",
    sigType: 1,
    vdxfKeys: [],
    vdxfKeyNames: [],
    boundHashes: [],
    signatureAsVch: "signature_hex..."
  }
});
```

### Nested DataDescriptor

```typescript
VdxfUniValue.fromJson({
  [VDXF_Data.DataDescriptorKey.vdxfid]: {
    version: 1,
    objectdata: { message: "Nested content" },
    label: "inner-data",
    mimetype: "text/plain"
  }
});
```

---

## Fallback Behavior

When decoding, if VdxfUniValue encounters bytes it can't parse as a known type, it stores them as raw bytes under the empty key `""`:

```typescript
const uni = new VdxfUniValue();
uni.fromBuffer(unknownData);

// uni.values might contain:
// [{ "": <Buffer ...> }]
```

This ensures decoding never fails — unknown data is preserved as-is.

---

## Important Notes

1. **Encoding is one-way for primitives** — You can encode typed data into bytes, but decoding requires knowing the expected type from the contentmultimap key context.

2. **Always use array format in contentmultimap** — VdxfUniValue values go inside arrays:
   ```json
   { "contentmultimap": { "iSomeKey": ["hex_encoded_value"] } }
   ```

3. **Hex detection** — When passing a plain string, VdxfUniValue checks if it's valid hex. If yes, it's treated as raw bytes. If not, it's treated as UTF-8 text.

4. **Version field** — Currently always 1. Included for forward compatibility.

---

## Related

- [DataDescriptor — Structured Data Containers](data-descriptor.md) — Uses VdxfUniValue for objectdata
- [DefinedKey — Human-Readable VDXF Labels](vdxf-data-standard.md) — Labels for VDXF keys
- [VDXF — Verus Data Exchange Format](vdxf-data-standard.md) — The overall data standard

---

*As of verus-typescript-primitives (generic-signed-request branch).*


--- PAGE: contribute/suggest-edit.md ---

---
label: Suggest an Edit
icon: pencil
order: -1
---

# Suggest an Edit or Addition

See something missing or outdated? Submit your suggestion below and it will be reviewed by the wiki maintainers each week.

All fields are anonymous by default — the name/handle field is optional.

---

<div id="wiki-suggest-form">

<form id="suggest-form" data-turbo="false" style="display:flex;flex-direction:column;gap:1.25rem;max-width:680px;">

  <div>
    <label for="section" style="display:block;font-weight:600;margin-bottom:.4rem;">Section <span style="color:#f87171">*</span></label>
    <select id="section" name="section" required
      style="width:100%;padding:.6rem .75rem;border-radius:.5rem;border:1px solid #374151;background:#111827;color:#f3f4f6;font-size:.95rem;box-sizing:border-box;cursor:pointer;">
      <option value="" disabled selected>— choose a section —</option>
      <option>Getting Started</option>
      <option>Command Reference</option>
      <option>Concepts</option>
      <option>How-To Guides</option>
      <option>Tutorials</option>
      <option>Developers</option>
      <option>For Agents</option>
      <option>Research</option>
      <option>Troubleshooting</option>
      <option>FAQ</option>
      <option>Other / New Section</option>
    </select>
  </div>

  <div>
    <label for="title" style="display:block;font-weight:600;margin-bottom:.4rem;">Page title or topic <span style="color:#f87171">*</span></label>
    <input id="title" name="title" type="text" required
      placeholder="e.g. How to use getidentity with multiple outputs"
      maxlength="200"
      style="width:100%;padding:.6rem .75rem;border-radius:.5rem;border:1px solid #374151;background:#111827;color:#f3f4f6;font-size:.95rem;box-sizing:border-box;" />
  </div>

  <div>
    <label for="content" style="display:block;font-weight:600;margin-bottom:.4rem;">Your suggestion or content <span style="color:#f87171">*</span></label>
    <p style="margin:0 0 .5rem;font-size:.85rem;color:#9ca3af;">
      Describe what should be added, corrected, or improved. Paste example commands, code snippets, or notes — the more detail the better.
    </p>
    <textarea id="content" name="content" required rows="10"
      placeholder="e.g. The page on basket currencies doesn't explain how reserve ratios work in practice. Here's a concrete example: ..."
      maxlength="10000"
      style="width:100%;padding:.6rem .75rem;border-radius:.5rem;border:1px solid #374151;background:#111827;color:#f3f4f6;font-size:.95rem;font-family:inherit;resize:vertical;box-sizing:border-box;"></textarea>
    <div id="char-count" style="text-align:right;font-size:.8rem;color:#6b7280;margin-top:.25rem;">0 / 10,000</div>
  </div>

  <div>
    <label for="submitter" style="display:block;font-weight:600;margin-bottom:.4rem;">Your name or handle <span style="color:#6b7280;font-weight:400;">(optional)</span></label>
    <input id="submitter" name="submitter" type="text"
      placeholder="e.g. alice@verus or Discord: alice#1234"
      maxlength="100"
      style="width:100%;padding:.6rem .75rem;border-radius:.5rem;border:1px solid #374151;background:#111827;color:#f3f4f6;font-size:.95rem;box-sizing:border-box;" />
  </div>

  <div id="form-status" style="display:none;padding:.75rem 1rem;border-radius:.5rem;font-size:.9rem;"></div>

  <button type="submit" id="submit-btn"
    style="align-self:flex-start;padding:.65rem 1.5rem;border-radius:.5rem;border:none;background:#3b82f6;color:#fff;font-size:.95rem;font-weight:600;cursor:pointer;">
    Submit Suggestion
  </button>

</form>

</div>

<script>
(function () {
  var API = '/api/submit';

  // Use document-level delegation in capture phase so Vue hydration
  // and Turbo Drive cannot remove or bypass this listener.

  // Char counter — delegated via input event
  document.addEventListener('input', function (e) {
    if (e.target && e.target.id === 'content') {
      var counter = document.getElementById('char-count');
      if (counter) counter.textContent = e.target.value.length + ' / 10,000';
    }
  }, true);

  // Form submit — capture phase beats Turbo's interception
  document.addEventListener('submit', function (e) {
    var form = e.target;
    if (!form || form.id !== 'suggest-form') return;

    e.preventDefault();
    e.stopImmediatePropagation();

    var status = document.getElementById('form-status');
    var btn    = document.getElementById('submit-btn');

    status.style.display = 'none';
    btn.disabled    = true;
    btn.textContent = 'Submitting…';

    var body = {
      section:   document.getElementById('section').value,
      title:     document.getElementById('title').value,
      content:   document.getElementById('content').value,
      submitter: document.getElementById('submitter').value
    };

    fetch(API, {
      method:  'POST',
      headers: { 'Content-Type': 'application/json' },
      body:    JSON.stringify(body)
    })
    .then(function (r) { return r.json().then(function (d) { return { ok: r.ok, data: d }; }); })
    .then(function (res) {
      if (res.ok) {
        status.style.background = '#052e16';
        status.style.color      = '#86efac';
        status.style.border     = '1px solid #166534';
        status.textContent      = 'Thank you! Your suggestion has been received and will be reviewed this week.';
        form.reset();
        document.getElementById('char-count').textContent = '0 / 10,000';
        btn.textContent = 'Submitted';
      } else {
        throw new Error(res.data.error || 'Submission failed.');
      }
    })
    .catch(function (err) {
      status.style.background = '#1c0a0a';
      status.style.color      = '#fca5a5';
      status.style.border     = '1px solid #7f1d1d';
      status.textContent      = 'Error: ' + err.message;
      btn.disabled    = false;
      btn.textContent = 'Submit Suggestion';
    })
    .finally(function () {
      status.style.display = 'block';
    });
  }, true); // true = capture phase, runs before Turbo
})();
</script>


--- PAGE: developers/building-on-verus.md ---

# Developer Guide: Building on Verus

> What you can build on Verus and how the pieces fit together.

---

## What Makes Verus Different

Verus isn't just a cryptocurrency — it's a protocol with built-in primitives that other chains require smart contracts for:

| Primitive | Built Into Verus | On Ethereum |
|-----------|-----------------|-------------|
| Identity (naming, auth) | ✅ VerusID | ❌ Requires ENS + separate auth |
| On-chain data storage | ✅ contentmultimap | ❌ Requires IPFS + smart contract |
| Token creation | ✅ `definecurrency` | ❌ Requires ERC-20 contract |
| DEX / AMM | ✅ Native conversions | ❌ Requires Uniswap-style contract |
| Multi-chain | ✅ PBaaS | ❌ Requires bridges |
| Multisig | ✅ Built into every ID | ⚠️ Requires multisig wallet contract |
| Key recovery | ✅ Recovery authority | ❌ Not possible |

This means: **less code, fewer attack surfaces, no gas fee surprises.**

---

## Project Categories

### 1. Identity-Based Applications

VerusID provides naming, authentication, data storage, and key recovery — all on-chain.

**What you can build:**
- **Login with VerusID** — Replace username/password with cryptographic identity
- **Reputation systems** — Store ratings and endorsements in contentmultimap
- **Credential verification** — Attestations stored on-chain with VDXF keys
- **Profile platforms** — Decentralized user profiles (like Gravatar, but self-sovereign)

**Key APIs:**
- [getidentity](../command-reference/identity.md#getidentity) — Look up identity data
- [updateidentity](../command-reference/identity.md#updateidentity) — Store data on-chain
- [signmessage](../command-reference/identity.md#signmessage) / [verifymessage](../command-reference/identity.md#verifymessage) — Prove identity ownership
- [getvdxfid](../command-reference/vdxf.md#getvdxfid) — Create standardized data keys

**Example: Login Flow**
```
1. App presents challenge string
2. User signs challenge with their VerusID
3. App verifies signature → user authenticated
```

```python
# Server generates challenge
challenge = f"Login to MyApp at {timestamp}"

# User signs (client-side)
# verus signmessage "user@" "Login to MyApp at 1770422400"

# Server verifies
result = rpc("verifymessage", ["user@", signature, challenge])
assert result == True
```

### 2. Token and Currency Projects

Verus lets anyone create currencies, tokens, and liquidity pools with a single command.

**What you can build:**
- **Community tokens** — Loyalty points, governance tokens, game currencies
- **Stablecoins** — Basket currencies backed by multiple reserves
- **Liquidity pools** — Automated market makers with built-in conversions
- **Fundraising** — Token launches with configurable supply and pricing

**Key APIs:**
- [definecurrency](../command-reference/multichain.md#definecurrency) — Create new currencies
- [getcurrency](../command-reference/multichain.md#getcurrency) — Query currency details
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Send and convert currencies
- [estimateconversion](../command-reference/multichain.md#estimateconversion) — Preview conversion rates

**Example: Create a Simple Token**
```bash
./verus definecurrency '{
  "name": "MYTOKEN",
  "options": 32,
  "currencies": ["VRSC"],
  "conversions": [1],
  "maxpreconversion": [10000],
  "preallocations": [{"myid@": 1000}]
}'
```

### 3. DeFi Integrations

Verus has a native DEX — no smart contracts needed.

**What you can build:**
- **Trading interfaces** — Frontends for Verus currency conversions
- **Arbitrage bots** — Monitor and exploit price differences
- **Portfolio trackers** — Track holdings across Verus currencies
- **Price oracles** — Read on-chain conversion rates

**Example: Price Monitor**
```python
def get_price(from_currency, to_currency):
    result = rpc("estimateconversion", [{
        "currency": from_currency,
        "convertto": to_currency,
        "amount": 1.0
    }])
    return result["estimatedcurrencyout"]

# Monitor price changes
while True:
    price = get_price("MYTOKEN", "VRSC")
    log_price(price)
    time.sleep(60)
```

### 4. Cross-Chain Applications

Verus's PBaaS (Public Blockchains as a Service) enables launching independent blockchains that interoperate with the Verus main chain.

**What you can build:**
- **Application-specific chains** — Your own blockchain with custom parameters
- **Cross-chain bridges** — Move assets between PBaaS chains
- **Multi-chain identity** — VerusIDs work across all PBaaS chains
- **Scalable platforms** — Offload traffic to a dedicated chain

**Key APIs:**
- [definecurrency](../command-reference/multichain.md#definecurrency) — Launch PBaaS chains
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Cross-chain transfers
- [getcrosschain*](../command-reference/multichain.md) — Cross-chain state queries

### 5. Marketplace and Trading Platforms

**What you can build:**
- **Agent marketplace** — AI agents listing services with VerusID profiles (see [For Agents](../for-agents/agent-bootstrap.md))
- **Freelance platform** — Identity-verified service providers with on-chain reputation
- **NFT-style collectibles** — Unique tokens under identity namespaces
- **Subscription services** — Recurring payments via sendcurrency

**Example: Agent Service Listing**
```python
# Store service listing in agent's contentmultimap
services_hex = encode_hex(json.dumps([
    {"id": "code-review", "price": {"amount": 5, "currency": "VRSC"}},
    {"id": "documentation", "price": {"amount": 10, "currency": "VRSC"}}
]))

rpc("updateidentity", [{
    "name": "myagent",
    "contentmultimap": {
        SERVICES_VDXF_KEY: [services_hex]
    }
}])
```

---

## Architecture Patterns

### Minimal Stack

```
Your App  ──RPC──▶  verusd
```

No database needed for basic operations. The blockchain IS your database for identity data, balances, and transaction history.

### Production Stack

```
Frontend  ──API──▶  Your Backend  ──RPC──▶  verusd
                         │
                    Cache / DB
                  (for indexing)
```

Add a cache/database layer when you need:
- Fast search across many identities
- Historical analytics
- Custom indexing (e.g., by capability, by currency)

---

## Getting Started

1. **Set up testnet** — [Testnet Guide](./testnet-guide.md)
2. **Learn the API** — [RPC API Overview](./rpc-api-overview.md)
3. **Study the patterns** — [Integration Patterns](./integration-patterns.md)
4. **Build something** — Start small, iterate
5. **Deploy to mainnet** — When confident

---

## See Also

- [Identity System](../concepts/identity-system.md) — Deep dive on VerusID
- [For Agents](../for-agents/agent-bootstrap.md) — AI agent integration
- [Testnet Guide](./testnet-guide.md) — Safe development environment

---

*Last updated: 2026-02-07*


--- PAGE: developers/integration-patterns.md ---

# Developer Guide: Integration Patterns

> Practical patterns for building applications on Verus.

---

## Pattern 1: Payment Processor

Accept VRSC payments and verify them programmatically.

### Flow

```
Customer  ──sends VRSC──▶  Your Address
                                │
Your App  ──polls RPC──▶  verusd (checks confirmations)
                                │
                          ✅ Confirmed → Fulfill order
```

### Implementation

```python
import time

REQUIRED_CONFIRMATIONS = 6
POLL_INTERVAL = 30  # seconds

def generate_payment_address():
    """Create a unique address per order."""
    return rpc("getnewaddress", ["payments"])

def check_payment(address, expected_amount):
    """Check if payment received at address."""
    received = rpc("getreceivedbyaddress", [address, REQUIRED_CONFIRMATIONS])
    return received >= expected_amount

def wait_for_payment(address, expected_amount, timeout=3600):
    """Block until payment confirmed or timeout."""
    start = time.time()
    while time.time() - start < timeout:
        # Check unconfirmed first (show "pending" to user)
        unconfirmed = rpc("getreceivedbyaddress", [address, 0])
        if unconfirmed >= expected_amount:
            print(f"Payment detected (unconfirmed): {unconfirmed} VRSC")

            # Now wait for confirmations
            confirmed = rpc("getreceivedbyaddress", [address, REQUIRED_CONFIRMATIONS])
            if confirmed >= expected_amount:
                return True

        time.sleep(POLL_INTERVAL)
    return False

# Usage
order_address = generate_payment_address()
print(f"Send {amount} VRSC to: {order_address}")

if wait_for_payment(order_address, amount):
    fulfill_order()
```

### Using VerusID for Payments

Accept payments to a VerusID instead of raw addresses:

```python
# Customers send to "yourstore@" instead of an R-address
# Verify with:
balance = rpc("getaddressbalance", [{"addresses": ["yourstore@"]}])
```

---

## Pattern 2: Identity Lookup Service

Build a service that resolves and caches VerusID data.

### Implementation

```python
import json

def lookup_identity(name):
    """Look up a VerusID and return structured data."""
    try:
        result = rpc("getidentity", [name])
        identity = result["identity"]
        return {
            "name": identity["name"],
            "address": identity["identityaddress"],
            "primary_addresses": identity["primaryaddresses"],
            "revocation": identity["revocationauthority"],
            "recovery": identity["recoveryauthority"],
            "data": decode_contentmultimap(identity.get("contentmultimap", {}))
        }
    except Exception as e:
        if "Identity not found" in str(e):
            return None
        raise

def decode_contentmultimap(cmm):
    """Decode hex values in contentmultimap to strings."""
    decoded = {}
    for key, values in cmm.items():
        decoded[key] = []
        for hex_val in values:
            try:
                decoded[key].append(json.loads(bytes.fromhex(hex_val).decode()))
            except (ValueError, json.JSONDecodeError):
                decoded[key].append(bytes.fromhex(hex_val).decode(errors="replace"))
    return decoded

def is_identity_valid(name):
    """Check if identity exists and is not revoked."""
    result = rpc("getidentity", [name])
    flags = result["identity"].get("flags", 0)
    # Check revocation bit
    return (flags & 2) == 0  # bit 1 = revoked
```

### Caching Layer

```python
from functools import lru_cache
import time

identity_cache = {}
CACHE_TTL = 300  # 5 minutes

def cached_lookup(name):
    now = time.time()
    if name in identity_cache:
        data, timestamp = identity_cache[name]
        if now - timestamp < CACHE_TTL:
            return data

    data = lookup_identity(name)
    identity_cache[name] = (data, now)
    return data
```

---

## Pattern 3: DEX / Currency Converter Frontend

Build a frontend for Verus's built-in DEX.

### Get Available Currencies

```python
def list_currencies():
    """List all currencies on the network."""
    # Use listcurrencies to get available currencies
    return rpc("listcurrencies")

def get_currency_info(currency_name):
    """Get details about a currency."""
    return rpc("getcurrency", [currency_name])

def get_conversion_estimate(from_currency, to_currency, amount):
    """Estimate a currency conversion."""
    result = rpc("estimateconversion", [{
        "currency": from_currency,
        "convertto": to_currency,
        "amount": amount
    }])
    return result
```

### Execute a Conversion

```python
def convert_currency(from_id, from_currency, to_currency, amount):
    """Convert between currencies using sendcurrency."""
    result = rpc("sendcurrency", [
        from_id,
        [{
            "address": from_id,
            "currency": from_currency,
            "convertto": to_currency,
            "amount": amount
        }]
    ])
    return result  # Returns txid
```

### Monitor Conversion Status

```python
def check_conversion(txid):
    """Check if conversion completed."""
    tx = rpc("gettransaction", [txid])
    return {
        "confirmations": tx["confirmations"],
        "complete": tx["confirmations"] >= 1
    }
```

---

## Pattern 4: Event Monitoring

Watch for blockchain events relevant to your application.

### Polling Pattern (Simple)

```python
import time

def poll_new_blocks(callback, poll_interval=10):
    """Call callback for each new block."""
    last_height = rpc("getinfo")["blocks"]

    while True:
        current_height = rpc("getinfo")["blocks"]
        if current_height > last_height:
            for height in range(last_height + 1, current_height + 1):
                block_hash = rpc("getblockhash", [height])
                block = rpc("getblock", [block_hash])
                callback(block)
            last_height = current_height
        time.sleep(poll_interval)

# Usage
def on_new_block(block):
    print(f"Block {block['height']}: {len(block['tx'])} transactions")
    for txid in block["tx"]:
        process_transaction(txid)

poll_new_blocks(on_new_block)
```

### Watch Specific Address

```python
def watch_address(address, callback, poll_interval=15):
    """Watch for new transactions to an address."""
    seen_txids = set()

    while True:
        txs = rpc("listtransactions", ["*", 50])
        for tx in txs:
            if tx["txid"] not in seen_txids and tx.get("address") == address:
                seen_txids.add(tx["txid"])
                callback(tx)
        time.sleep(poll_interval)
```

### Watch Identity Updates

```python
def watch_identity(name, callback, poll_interval=30):
    """Detect changes to a VerusID."""
    last_data = rpc("getidentity", [name])

    while True:
        current_data = rpc("getidentity", [name])
        if current_data != last_data:
            callback(name, last_data, current_data)
            last_data = current_data
        time.sleep(poll_interval)
```

---

## Best Practices for Production

### 1. Connection Resilience

```python
import time
import requests

MAX_RETRIES = 3
RETRY_DELAY = 5

def rpc_resilient(method, params=None, retries=MAX_RETRIES):
    for attempt in range(retries):
        try:
            return rpc(method, params)
        except requests.ConnectionError:
            if attempt < retries - 1:
                time.sleep(RETRY_DELAY * (attempt + 1))
            else:
                raise
```

### 2. Check Daemon Health

```python
def is_daemon_ready():
    """Check if daemon is synced and ready."""
    try:
        info = rpc("getinfo")
        chain = rpc("getblockchaininfo")
        return (
            chain.get("verificationprogress", 0) > 0.999
            and info.get("connections", 0) > 0
        )
    except Exception:
        return False
```

### 3. Transaction Confirmation Thresholds

| Use Case | Recommended Confirmations |
|----------|--------------------------|
| Display as "pending" | 0 |
| Low-value items | 1 |
| Standard payments | 6 |
| High-value transfers | 20+ |
| Identity verification | 1 |

### 4. Rate Limiting

Don't hammer the daemon — batch calls where possible:

```python
# Instead of N separate calls:
for name in names:
    rpc("getidentity", [name])  # N round trips

# Use batch RPC (single HTTP request):
batch = [
    {"jsonrpc": "1.0", "id": str(i), "method": "getidentity", "params": [name]}
    for i, name in enumerate(names)
]
response = requests.post(RPC_URL, json=batch, auth=(USER, PASS))
results = response.json()
```

### 5. Secure Your Credentials

```python
# Don't hardcode — read from config or environment
import os

RPC_USER = os.environ.get("VERUS_RPC_USER")
RPC_PASS = os.environ.get("VERUS_RPC_PASS")
```

---

## See Also

- [RPC API Overview](./rpc-api-overview.md) — Connection basics
- [Testnet Guide](./testnet-guide.md) — Develop safely on testnet
- [Building on Verus](./building-on-verus.md) — Project ideas and architecture

---

*Last updated: 2026-02-07*


--- PAGE: developers/offline-verusid-signing.md ---

# Offline VerusID Signing — No Daemon Required

> Sign messages and authenticate as a VerusID entirely offline — no running daemon, no RPC connection, no network access during signing.

---

VerusID signatures normally go through the daemon via `signmessage` or `signdata` RPC. But for automated agents, headless servers, CI pipelines, or any environment without a running daemon, you can sign messages and authenticate entirely offline using just a WIF private key and two npm packages already in the Verus ecosystem.

## What You Need

- The identity's **WIF private key** (starts with `U` for testnet, `5` for mainnet — obtained once via `dumpprivkey` or key generation)
- `bitcoinjs-message` — message signing/verification
- `@bitgo/utxo-lib` (VerusCoin fork: `github:VerusCoin/BitGoJS`) — CIdentitySignature, key utilities

No daemon process. No RPC connection. No network access during signing.

---

## 1. Offline signmessage (Compatible with daemon verifymessage)

The daemon's `signmessage` uses a specific message prefix. Replicate it offline:

```javascript
import * as bitcoinMessage from 'bitcoinjs-message';
import { ECPair, networks } from '@bitgo/utxo-lib';

// Verus message prefix (0x15 = 21 decimal, then "Verus signed data:\n")
const MESSAGE_PREFIX = '\x15Verus signed data:\n';

function signMessage(wif, message, testnet = true) {
  const network = testnet ? networks.verustest : networks.verus;
  const keyPair = ECPair.fromWIF(wif, network);
  const privateKey = keyPair.privateKey;

  const signature = bitcoinMessage.sign(
    message,
    privateKey,
    keyPair.compressed,
    MESSAGE_PREFIX
  );

  // Zero private key material after signing
  privateKey.fill(0);

  return signature.toString('base64');
}
```

The resulting signature is identical to what `verus signmessage` produces. Any daemon can verify it with:

```bash
verus verifymessage "identity@" "<signature>" "the message"
```

---

## 2. Offline CIdentitySignature (Version 2, SHA256)

For protocols that use Verus identity signatures (not plain message signatures), use the `IdentitySignature` class from `@bitgo/utxo-lib`:

```javascript
import { IdentitySignature, ECPair, networks } from '@bitgo/utxo-lib';

function signChallenge(wif, challenge, identityAddress, testnet = true) {
  const network = testnet ? networks.verustest : networks.verus;
  const keyPair = ECPair.fromWIF(wif, network);

  const idSig = new IdentitySignature();
  idSig.version = 2;
  idSig.hashType = 5; // SHA256
  idSig.blockHeight = 0; // 0 for offline
  idSig.identityID = identityAddress;

  idSig.signMessageOffline(challenge, keyPair);

  // Zero key material
  keyPair.privateKey.fill(0);

  return idSig.toBuffer().toString('base64');
}
```

---

## 3. Offline LoginConsent Authentication

Combining offline signing with the LoginConsent protocol (see [VerusID Login: A Developer's Guide](./verusid-login-guide.md)):

```javascript
import { signMessage } from './signer.js';

// 1. Fetch challenge from service API
const res = await fetch('https://service.example/auth/consent/challenge');
const { data: challenge } = await res.json();

// 2. Verify service signature (optional but recommended)
// The challengeHash + requestSignature can be verified against
// the service's known identity if you have access to a Verus node.
// For offline-only: trust the TLS connection.

// 3. Sign the challengeHash offline
const signature = signMessage(agentWIF, challenge.challengeHash);

// 4. Submit back to service
await fetch('https://service.example/auth/consent/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    challengeId: challenge.challengeId,
    verusId: 'myagent@',
    signature,
  }),
});
// Service verifies with its daemon, returns session token
```

The agent's private key never leaves the machine. The service's daemon does all verification. The agent needs zero Verus infrastructure.

---

## 4. Offline Identity Updates (updateidentity)

You can also build and sign `updateidentity` transactions offline using `verus-typescript-primitives` and `@bitgo/utxo-lib`:

1. Fetch current identity + UTXOs from any Verus node or API
2. Build the identity update transaction locally
3. Sign with WIF using `@bitgo/utxo-lib` TransactionBuilder
4. Broadcast the raw signed transaction via any node's `sendrawtransaction` RPC

The transaction is built and signed entirely on the client. The node only broadcasts it — it never sees the private key.

> **Note:** `verus-typescript-primitives` has a hardcoded VDXF key registry in `VdxfUniValue` that throws on unknown keys. If your identity uses custom VDXF keys, you may need to patch three throw points in `VdxfUniValue.js` (`getByteLength`, `toBuffer`, `fromJson`) to fall back to `DataDescriptor` serialization instead of throwing.

---

## 5. Key Generation (No Daemon)

Generate a fresh keypair without a daemon:

```javascript
import crypto from 'crypto';
import { ECPair, networks } from '@bitgo/utxo-lib';

function generateKeypair(testnet = true) {
  const network = testnet ? networks.verustest : networks.verus;
  // Use crypto.randomBytes for entropy (more explicit than ECPair.makeRandom)
  const privateKey = crypto.randomBytes(32);
  const keyPair = ECPair.fromPrivateKey(privateKey, { network });
  const wif = keyPair.toWIF();
  const publicKey = keyPair.publicKey.toString('hex');

  // Zero raw private key
  privateKey.fill(0);

  return { wif, publicKey };
}
```

Register the public key as a primary address on a VerusID (requires one on-chain transaction via a daemon), then all future signing is offline forever — unless you rotate keys.

---

## Security Considerations

| Concern | Mitigation |
|---------|------------|
| WIF key storage | Encrypt at rest. Use environment variables, not source code. |
| Memory exposure | Zero private key buffers after signing (`key.fill(0)`) |
| Replay attacks | Services must use single-use challenges with short expiry |
| Key rotation | If identity primary addresses change on-chain, old WIF stops working — by design |
| No daemon verification | Signing side cannot verify service's LoginConsentRequest without a node. Trust TLS, or use a public Verus node for one-time verification. |

---

## Dependencies

| Package | Purpose |
|---------|---------|
| `bitcoinjs-message@2.2.0` | signmessage-compatible offline signing |
| `@bitgo/utxo-lib` (`github:VerusCoin/BitGoJS`) | CIdentitySignature, ECPair, networks, transaction building |
| `verus-typescript-primitives` | LoginConsentRequest/Response, VDXF classes, identity transaction building |

All three are pure JavaScript/TypeScript — no native modules, no daemon dependency. Works in Node.js, Bun, or any JS runtime.

---

## Reference

- [@bitgo/utxo-lib (VerusCoin fork)](https://github.com/VerusCoin/BitGoJS) — `IdentitySignature` class, `signMessageOffline()`
- [verus-typescript-primitives](https://github.com/VerusCoin/verus-typescript-primitives) — `LoginConsentRequest`/`Response`, `VdxfUniValue`, identity transaction classes
- [bitcoinjs-message](https://github.com/bitcoinjs/bitcoinjs-message) — `sign()` / `verify()` with custom message prefix support


--- PAGE: developers/rpc-api-overview.md ---

# Developer Guide: RPC API Overview

> Connect to the Verus daemon and make API calls from any language.

---

## How It Works

Verus exposes a **JSON-RPC 1.0** API via HTTP. The daemon (`verusd`) listens on a local port, and you authenticate with username/password from your config file.

```
Your App  ──HTTP POST──▶  verusd (localhost:27486)  ──▶  Blockchain
              │
         JSON-RPC body
         + Basic Auth
```

---

## Configuration

### Find Your Credentials

Credentials are in your Verus config file:

```bash
# Mainnet
cat ~/.komodo/VRSC/VRSC.conf

# Testnet
cat ~/.komodo/vrsctest/vrsctest.conf
```

Relevant fields:
```ini
rpcuser=your_username
rpcpassword=your_password
rpcport=27486           # mainnet default
rpcallowip=127.0.0.1   # localhost only (secure default)
server=1                # required for RPC
```

### Ports

| Network | RPC Port | P2P Port |
|---------|----------|----------|
| Mainnet | 27486 | 27485 |
| Testnet | 18843 | 18842 |

### Allowing Remote Access

⚠️ **Security warning:** Only do this on trusted networks.

```ini
# In VRSC.conf
rpcallowip=192.168.1.0/24    # Allow local network
rpcbind=0.0.0.0               # Bind to all interfaces
```

---

## JSON-RPC Format

Every request is an HTTP POST with a JSON body:

```json
{
  "jsonrpc": "1.0",
  "id": "my-request",
  "method": "getinfo",
  "params": []
}
```

| Field | Description |
|-------|-------------|
| `jsonrpc` | Always `"1.0"` |
| `id` | Arbitrary request identifier (returned in response) |
| `method` | RPC method name |
| `params` | Array of positional parameters |

Response format:
```json
{
  "result": { ... },
  "error": null,
  "id": "my-request"
}
```

On error:
```json
{
  "result": null,
  "error": {
    "code": -5,
    "message": "Invalid address"
  },
  "id": "my-request"
}
```

---

## curl Examples

### Basic: getinfo

```bash
curl -s -u rpcuser:rpcpassword \
  http://127.0.0.1:27486 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"curl","method":"getinfo","params":[]}'
```

### With Parameters: getidentity

```bash
curl -s -u rpcuser:rpcpassword \
  http://127.0.0.1:27486 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"curl","method":"getidentity","params":["alice@"]}'
```

### Complex Parameters: sendcurrency

```bash
curl -s -u rpcuser:rpcpassword \
  http://127.0.0.1:27486 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"1.0",
    "id":"curl",
    "method":"sendcurrency",
    "params":["myid@", [{"address":"recipient@","currency":"VRSC","amount":1.0}]]
  }'
```

### Parse Response with jq

```bash
curl -s -u rpcuser:rpcpassword \
  http://127.0.0.1:27486 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"curl","method":"getinfo","params":[]}' \
  | jq '.result.blocks'
```

---

## Python (requests)

```python
import requests
import json

RPC_URL = "http://127.0.0.1:27486"
RPC_USER = "your_rpcuser"
RPC_PASS = "your_rpcpassword"

def rpc(method, params=None):
    """Make a Verus RPC call."""
    payload = {
        "jsonrpc": "1.0",
        "id": "python",
        "method": method,
        "params": params or []
    }
    resp = requests.post(
        RPC_URL,
        auth=(RPC_USER, RPC_PASS),
        json=payload,
        timeout=30
    )
    resp.raise_for_status()
    data = resp.json()
    if data.get("error"):
        raise Exception(f"RPC error: {data['error']}")
    return data["result"]

# Examples
info = rpc("getinfo")
print(f"Block height: {info['blocks']}")

identity = rpc("getidentity", ["alice@"])
print(f"Identity address: {identity['identity']['identityaddress']}")

balance = rpc("getbalance")
print(f"Balance: {balance} VRSC")
```

### Read Credentials from Config

```python
import os

def load_credentials(testnet=False):
    if testnet:
        conf_path = os.path.expanduser("~/.komodo/vrsctest/vrsctest.conf")
        default_port = 18843
    else:
        conf_path = os.path.expanduser("~/.komodo/VRSC/VRSC.conf")
        default_port = 27486

    config = {}
    with open(conf_path) as f:
        for line in f:
            if "=" in line:
                key, val = line.strip().split("=", 1)
                config[key] = val

    return {
        "url": f"http://127.0.0.1:{config.get('rpcport', default_port)}",
        "user": config["rpcuser"],
        "password": config["rpcpassword"]
    }
```

---

## Node.js (axios)

```javascript
const axios = require('axios');

const RPC_URL = 'http://127.0.0.1:27486';
const RPC_USER = 'your_rpcuser';
const RPC_PASS = 'your_rpcpassword';

async function rpc(method, params = []) {
  const { data } = await axios.post(RPC_URL, {
    jsonrpc: '1.0',
    id: 'node',
    method,
    params
  }, {
    auth: { username: RPC_USER, password: RPC_PASS },
    timeout: 30000
  });

  if (data.error) {
    throw new Error(`RPC error: ${JSON.stringify(data.error)}`);
  }
  return data.result;
}

// Examples
(async () => {
  const info = await rpc('getinfo');
  console.log(`Block height: ${info.blocks}`);

  const identity = await rpc('getidentity', ['alice@']);
  console.log(`Address: ${identity.identity.identityaddress}`);
})();
```

---

## Error Handling

### HTTP-Level Errors

| HTTP Status | Meaning |
|-------------|---------|
| 401 | Bad credentials (check rpcuser/rpcpassword) |
| 403 | IP not allowed (check rpcallowip) |
| 500 | RPC method error (check response body) |
| Connection refused | Daemon not running or wrong port |

### RPC Error Codes

| Code | Meaning |
|------|---------|
| -1 | General error |
| -3 | Invalid type for parameter |
| -5 | Invalid address or key |
| -6 | Insufficient funds |
| -8 | Invalid parameter |
| -25 | Transaction already in chain |
| -26 | Transaction rejected |
| -28 | Daemon still loading/syncing |

### Robust Error Handling (Python)

```python
import requests

def rpc_safe(method, params=None):
    try:
        return rpc(method, params)
    except requests.ConnectionError:
        print("ERROR: Daemon not running or wrong port")
        return None
    except requests.Timeout:
        print("ERROR: Request timed out (daemon busy?)")
        return None
    except Exception as e:
        if "Insufficient funds" in str(e):
            print("ERROR: Not enough VRSC")
        elif "-28" in str(e):
            print("ERROR: Daemon still syncing, try later")
        else:
            print(f"ERROR: {e}")
        return None
```

---

## Batch Requests

Verus supports JSON-RPC batch calls (array of requests):

```bash
curl -s -u rpcuser:rpcpassword \
  http://127.0.0.1:27486 \
  -H "Content-Type: application/json" \
  -d '[
    {"jsonrpc":"1.0","id":"1","method":"getinfo","params":[]},
    {"jsonrpc":"1.0","id":"2","method":"getbalance","params":[]},
    {"jsonrpc":"1.0","id":"3","method":"getmininginfo","params":[]}
  ]'
```

Returns an array of responses in the same order.

---

## See Also

- [Integration Patterns](./integration-patterns.md) — Building real applications
- [Testnet Guide](./testnet-guide.md) — Develop against testnet
- [Common Errors](../troubleshooting/common-errors.md) — Error reference

---

*Last updated: 2026-02-07*


--- PAGE: developers/testnet-guide.md ---

# Developer Guide: Testnet

> Set up a Verus testnet node for safe development and testing.

---

## Why Testnet?

- **Free coins** — VRSCTEST has no value; experiment freely
- **Same features** — Testnet runs identical code to mainnet
- **Safe mistakes** — Lose keys, break things, learn without cost
- **Fast iteration** — Same block time, but you can get coins instantly from faucet

---

## Setting Up a Testnet Node

### 1. Install Verus CLI

```bash
# Download latest release
curl -s https://api.github.com/repos/VerusCoin/VerusCoin/releases/latest \
  | grep "browser_download_url.*Linux.*x86_64" \
  | head -1 | cut -d '"' -f 4 | xargs wget -O /tmp/verus-cli.tgz

# Extract
mkdir -p ~/verus-cli
tar -xzf /tmp/verus-cli.tgz -C ~/verus-cli --strip-components=1

# ZK parameters are auto-downloaded on first daemon start (~1.7GB)
# To pre-download manually (optional):
cd ~/verus-cli && ./fetch-params
```

### 2. Start the Daemon

> **No manual configuration needed.** The daemon automatically creates `~/.komodo/vrsctest/` and a `vrsctest.conf` with random RPC credentials on first launch.

```bash
# First time — use -bootstrap for fast sync (under 3 hours vs ~3 days)
./verusd -testnet -bootstrap
```

For subsequent starts after a clean shutdown:
```bash
./verusd -testnet -fastload
```

### 3. Wait for Sync

```bash
# Monitor progress
watch -n 10 './verus -testnet getinfo 2>/dev/null | grep -E "blocks|headers|connections"'

# Fully synced when blocks ≈ headers
```

### 4. Read Auto-Generated Credentials

```bash
cat ~/.komodo/vrsctest/vrsctest.conf | grep -E "rpcuser|rpcpassword|rpcport"
```

> 💡 **Optional:** Add custom settings (like `addnode=195.248.234.41`) to the auto-generated conf, then restart.

---

## Getting Testnet Coins

### Discord Faucet

Request VRSCTEST in the Verus Discord `#testnet-faucet` channel.

### From Another Wallet

If you have testnet coins elsewhere:
```bash
# Generate receiving address
./verus -testnet getnewaddress "dev-wallet"

# Send from other wallet to this address
```

### Mining (Slow but Autonomous)

```bash
# Start mining with 1 thread
./verus -testnet setgenerate true 1

# Check mining status
./verus -testnet getmininginfo

# Stop mining
./verus -testnet setgenerate false
```

---

## Testnet vs Mainnet Differences

| Feature | Testnet | Mainnet |
|---------|---------|---------|
| CLI prefix | `./verus -testnet` | `./verus` |
| Config directory | `~/.komodo/vrsctest/` | `~/.komodo/VRSC/` |
| Config file | `vrsctest.conf` | `VRSC.conf` |
| RPC port | 18843 | 27486 |
| P2P port | 18842 | 27485 |
| Currency | VRSCTEST | VRSC |
| ID suffix | `name.VRSCTEST@` | `name@` |
| ID cost | ~100 VRSCTEST (free test coins) | ~100 VRSC root ID (80 with referral; as low as ~20 net with a full referral chain you own; free via Valu; pennies on PBaaS chains) |
| Parent i-address | `iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq` | `i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV` |
| Coin value | None (free) | Real value |
| Chain data size | ~5–10 GB | ~15–25 GB |
| Sync time (with `-bootstrap`) | Under 3 hours | Under 3 hours |
| Sync time (without bootstrap) | 2–6 hours | ~3 days |

### Code Differences

```python
# Testnet
RPC_PORT = 18843
PARENT_CURRENCY = "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq"  # VRSCTEST

# Mainnet
RPC_PORT = 27486
PARENT_CURRENCY = "i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV"  # VRSC
```

---

## Useful Testnet Commands

### Wallet Management

```bash
# New address
./verus -testnet getnewaddress "label"

# Check balance
./verus -testnet getbalance

# List transactions
./verus -testnet listtransactions "*" 10

# Send VRSCTEST
./verus -testnet sendtoaddress "R_ADDRESS" 10.0
```

### Identity Operations

```bash
# Register an identity (cheap on testnet!)
./verus -testnet registernamecommitment "testname" "YOUR_R_ADDR"
# Wait 1 block...
./verus -testnet registeridentity '{...}'

# Look up identity
./verus -testnet getidentity "testname.VRSCTEST@"

# Update identity
./verus -testnet updateidentity '{...}'
```

### Chain Information

```bash
# Node info
./verus -testnet getinfo

# Block details
./verus -testnet getblock "$(./verus -testnet getbestblockhash)"

# Mempool
./verus -testnet getmempoolinfo

# Peer connections
./verus -testnet getpeerinfo | grep -E '"addr"|"subver"'
```

### Currency and DEX

```bash
# List currencies
./verus -testnet listcurrencies

# Get currency details
./verus -testnet getcurrency "VRSCTEST"

# Estimate conversion
./verus -testnet estimateconversion '{"currency":"VRSCTEST","convertto":"OTHERCURRENCY","amount":10}'
```

---

## Development Workflow

```
1. Start testnet daemon
2. Get VRSCTEST from faucet
3. Register test identity
4. Build and test your integration
5. Break things freely
6. When confident → deploy to mainnet
```

### Stopping the Daemon

Always shut down cleanly:
```bash
./verus -testnet stop
```

**Never kill the process** — this can corrupt the database.

### Quick Reset

If you need a fresh testnet state:
```bash
./verus -testnet stop

# Option A: Quick reset (keeps wallet and config)
rm -rf ~/.komodo/vrsctest/blocks ~/.komodo/vrsctest/chainstate
./verusd -testnet -bootstrap

# Option B: Full reset (removes everything — back up wallet.dat first!)
cp ~/.komodo/vrsctest/wallet.dat ~/wallet-testnet-backup.dat
rm -rf ~/.komodo/vrsctest/
rm -rf ~/.verustest/    # testnet data may also be here
./verusd -testnet -bootstrap
```

> **macOS paths:** Replace `~/.komodo/vrsctest/` with `~/Library/Application Support/Komodo/VRSCTEST/`

---

## See Also

- [RPC API Overview](./rpc-api-overview.md) — API connection basics
- [How to Create a VerusID](../how-to/create-verusid.md) — Identity registration walkthrough
- [Integration Patterns](./integration-patterns.md) — Build real applications

---

*Last updated: 2026-02-07*


--- PAGE: developers/verusid-login-guide.md ---

---
label: "VerusID Login: A Developer's Guide"
icon: key
order: 50
---

# VerusID Login: A Developer's Guide

_How to implement passwordless authentication using VerusID signatures — from the developer who built it._

---

## Why This Guide Exists

I spent weeks getting VerusID login working across three different methods: CLI, GUI desktop, and Verus Mobile QR scanning. There's almost no documentation on this in the wild. This is the guide I wish I had.

VerusID login is **passwordless, cryptographic authentication**. Instead of "username + password," users prove identity by signing a challenge message with their VerusID's private key. No passwords stored, no password resets, no credential databases to breach.

The concept is simple. The implementation has sharp edges. This guide covers both.

---

## The Core Flow

Every VerusID login method follows the same pattern:

```
1. Server generates a random challenge (nonce + message)
2. User signs the challenge with their VerusID
3. Server verifies the signature against the claimed identity
4. If valid → create session
```

That's it. The complexity is in *how* the user signs (3 different methods) and the edge cases that'll break your implementation.

---

## Prerequisites

- A running Verus daemon (`verusd`) — testnet recommended for development
- RPC access configured (`verus.conf` or CLI flags)
- The identity you're authenticating must exist on-chain

### RPC Setup

```bash
# Your verus.conf (or pass via CLI)
rpcuser=your_rpc_user
rpcpassword=your_rpc_password
rpcport=18843  # testnet
rpcallowip=127.0.0.1
```

```typescript
// Basic RPC client
async function rpcCall(method: string, params: any[] = []) {
  const res = await fetch('http://127.0.0.1:18843', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Basic ' + Buffer.from(`${RPC_USER}:${RPC_PASS}`).toString('base64'),
    },
    body: JSON.stringify({ method, params, id: Date.now() }),
  });
  const data = await res.json();
  if (data.error) throw new Error(data.error.message);
  return data.result;
}
```

---

## Method 1: CLI / GUI Console (Simplest)

This is the easiest to implement and the best starting point. The user runs a command in their Verus CLI or the GUI wallet's debug console.

### Server Side

```typescript
import crypto from 'crypto';

// Step 1: Generate a challenge
function createChallenge(): { nonce: string; message: string } {
  const nonce = crypto.randomBytes(32).toString('hex');
  const message = `Login to My App | Nonce: ${nonce} | Timestamp: ${Date.now()}`;
  
  // Store nonce with expiry (5 minutes)
  nonceStore.set(nonce, { 
    createdAt: Date.now(), 
    expiresAt: Date.now() + 5 * 60 * 1000 
  });
  
  return { nonce, message };
}

// Step 3: Verify the signature
async function verifyLogin(
  verusId: string, 
  signature: string, 
  nonce: string
): Promise<boolean> {
  // Check nonce exists and hasn't expired
  const stored = nonceStore.get(nonce);
  if (!stored || stored.expiresAt < Date.now()) return false;
  
  // CRITICAL: Delete nonce immediately (one-time use)
  nonceStore.delete(nonce);
  
  // Reconstruct the original message
  const message = `Login to My App | Nonce: ${nonce} | Timestamp: ${stored.createdAt}`;
  
  // Verify via RPC
  const isValid = await rpcCall('verifymessage', [verusId, signature, message]);
  return isValid === true;
}
```

### What the User Does

You show them the message and they run:

```bash
# CLI
./verus -testnet signmessage "alice@" "Login to My App | Nonce: abc123... | Timestamp: 1770758507"

# Returns:
# {
#   "hash": "...",
#   "signature": "AZA4DgABQR+CJ2YF..."
# }
```

They paste back the `signature` value. Your server verifies it.

### Frontend Example

```jsx
function LoginPage() {
  const [challenge, setChallenge] = useState(null);
  const [signature, setSignature] = useState('');
  const [verusId, setVerusId] = useState('');

  async function getChallenge() {
    const res = await fetch('/auth/challenge');
    setChallenge(await res.json());
  }

  async function submitLogin() {
    const res = await fetch('/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify({ 
        verusId, 
        signature, 
        nonce: challenge.nonce 
      }),
    });
    if (res.ok) window.location.reload();
  }

  return (
    <div>
      <button onClick={getChallenge}>Get Challenge</button>
      
      {challenge && (
        <>
          <p>Run this command:</p>
          <code>
            signmessage "{verusId || 'yourname@'}" "{challenge.message}"
          </code>
          
          <input 
            placeholder="Your VerusID (e.g. alice@)"
            value={verusId}
            onChange={e => setVerusId(e.target.value)}
          />
          <input 
            placeholder="Paste signature here"
            value={signature}
            onChange={e => setSignature(e.target.value)}
          />
          <button onClick={submitLogin}>Login</button>
        </>
      )}
    </div>
  );
}
```

---

## Method 2: Verus Mobile QR Login

This is the best UX but the hardest to implement. The user scans a QR code with Verus Mobile, approves the login, and they're authenticated. No copy-pasting.

### Architecture

```
Browser                    Your Server              Login Service            Verus Mobile
  │                           │                         │                       │
  │  1. GET /challenge ──────▶│                         │                       │
  │◀── QR code data ──────── │                         │                       │
  │                           │                         │                       │
  │  [User scans QR]          │                         │                       │
  │                           │                         │                 ◀─── [Scans QR]
  │                           │                         │◀── POST /verusidlogin │
  │                           │                         │    (signed response)  │
  │                           │                         │                       │
  │                           │                         │── Verify signature    │
  │                           │◀── POST /callback ──── │   (if valid)          │
  │                           │    { verified: true }   │                       │
  │                           │                         │                       │
  │  2. Poll /status ────────▶│                         │                       │
  │◀── { status: "completed" }│                         │                       │
  │                           │                         │                       │
  │  [Session cookie set]     │                         │                       │
```

### The Login Microservice

This is the piece that talks to Verus Mobile. It uses the `verusid-ts-client` library which handles the VerusID Login Consent Protocol.

**Critical dependency note:** You need the VerusCoin forks of these libraries, not the npm versions:

```json
{
  "dependencies": {
    "verusid-ts-client": "github:VerusCoin/verusid-ts-client",
    "verus-typescript-primitives": "github:VerusCoin/verus-typescript-primitives",
    "@bitgo/utxo-lib": "github:AYCEchain/BitGoJS"
  }
}
```

**Install with `yarn`, not `npm`.** The GitHub dependencies have resolution issues with npm.

```javascript
// login-server/src/index.js
import { LoginConsentProvisioningDecision } from 'verusid-ts-client';

const SIGNING_IADDRESS = process.env.SIGNING_IADDRESS; // Your server's identity i-address
const PRIVATE_KEY = process.env.PRIVATE_KEY;             // WIF private key for that identity
const CHAIN = process.env.CHAIN || 'VRSCTEST';
const CALLBACK_URL = process.env.SERVER_URL;             // Where Mobile sends the response

// Generate a login challenge
app.get('/login', (req, res) => {
  const challengeId = crypto.randomUUID();
  
  // Build the login consent request
  const request = new LoginConsentRequest({
    system_id: CHAIN,
    signing_id: SIGNING_IADDRESS,
    challenge: {
      challenge_id: challengeId,
      requested_access: [/* permissions */],
    },
    // Where Verus Mobile sends the signed response
    redirect_uris: [{
      type: 'callback',
      uri: `${CALLBACK_URL}/verusidlogin`,
    }],
  });
  
  // Sign the request with your server's private key
  const signed = request.sign(PRIVATE_KEY);
  
  // Build the deeplink URL that becomes the QR code
  const deeplink = `verus://verusid-login/${Buffer.from(JSON.stringify(signed)).toString('base64url')}`;
  
  // Store the challenge for later verification
  challenges.set(challengeId, { status: 'pending', createdAt: Date.now() });
  
  res.json({ challengeId, qrUrl: deeplink });
});
```

### The Context Bug (Fixed)

!!!success Resolved upstream
This bug has been **fixed** in the latest version of `verus-typescript-primitives`. If you're hitting `Context.serialize is not a function`, update the library:

```bash
yarn upgrade verus-typescript-primitives
# or
npm update verus-typescript-primitives
```
!!!

Older versions of `verus-typescript-primitives` had a bug in the `Decision` constructor — when deserializing a login response from Verus Mobile, it assigned the raw JSON object instead of constructing a proper `Context` instance:

```javascript
// What older versions did:
this.context = decision.context;  // Raw JSON object — no serialize() method

// What current versions do (fixed):
this.context = decision.context ? new Context(decision.context.kv) : new Context();
```

If you're stuck on an older version for some reason, you can patch it manually:

```javascript
import { Context } from 'verus-typescript-primitives';

function fixContext(decision) {
  if (decision.context && !(decision.context instanceof Context)) {
    const kv = decision.context.kv || decision.context;
    decision.context = new Context({ kv });
  }
  return decision;
}
```

But really, just update the library.

### Verifying the Mobile Response

When Verus Mobile sends the signed response to your callback:

```javascript
app.post('/verusidlogin', async (req, res) => {
  const body = req.body;
  
  // The response may have Buffer objects serialized as JSON
  // { type: 'Buffer', data: [1, 2, 3] } → actual Buffer
  restoreBuffers(body);
  
  // Parse the provisioning decision
  const decision = new LoginConsentProvisioningDecision(body);
  
  // Verify the signature
  // This checks that the response was actually signed by the claimed identity
  const verificationResult = await decision.verify(CHAIN);
  
  if (!verificationResult.valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Extract who signed
  const signingId = decision.signing_id; // i-address of the user
  
  // Notify your main server that this challenge was verified
  await fetch(`${YOUR_PLATFORM_URL}/auth/qr/callback`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      verified: true,
      challengeId: decision.challenge.challenge_id,
      signingId: signingId,
    }),
  });
  
  res.json({ success: true });
});
```

### Buffer Restoration Helper

Verus Mobile sends Buffers as JSON objects. You need to restore them:

```javascript
function restoreBuffers(obj) {
  if (!obj || typeof obj !== 'object') return obj;
  
  if (obj.type === 'Buffer' && Array.isArray(obj.data)) {
    return Buffer.from(obj.data);
  }
  
  for (const key of Object.keys(obj)) {
    if (obj[key] && typeof obj[key] === 'object') {
      if (obj[key].type === 'Buffer' && Array.isArray(obj[key].data)) {
        obj[key] = Buffer.from(obj[key].data);
      } else {
        restoreBuffers(obj[key]);
      }
    }
  }
  
  return obj;
}
```

### Frontend: QR Display + Polling

```jsx
function QRLogin() {
  const [qrUrl, setQrUrl] = useState(null);
  const [challengeId, setChallengeId] = useState(null);

  async function startLogin() {
    const res = await fetch('/auth/qr/challenge');
    const data = await res.json();
    setQrUrl(data.qrUrl);
    setChallengeId(data.challengeId);
  }

  // Poll for completion
  useEffect(() => {
    if (!challengeId) return;
    const interval = setInterval(async () => {
      const res = await fetch(`/auth/qr/status/${challengeId}`);
      const data = await res.json();
      if (data.status === 'completed') {
        clearInterval(interval);
        window.location.reload(); // Session cookie is now set
      }
    }, 2000);
    return () => clearInterval(interval);
  }, [challengeId]);

  return (
    <div>
      <button onClick={startLogin}>Login with Verus Mobile</button>
      {qrUrl && (
        <QRCode value={qrUrl} size={256} />
      )}
    </div>
  );
}
```

---

## Method 3: Signing for Actions (Not Just Login)

Once authenticated, you'll likely need users to sign specific actions — job requests, deliveries, reviews. This is different from login: the message content matters.

### Message Format: Pipe-Delimited Single Line

**This is critical.** I originally used multi-line messages with `\n` newlines. This works in the CLI but **breaks in the Verus GUI debug console** — the console doesn't support `$'...\n...'` shell syntax.

**Use pipe-delimited single-line format:**

```typescript
// ✅ Works everywhere — CLI, GUI console, Verus Mobile
function generateJobRequestMessage(seller, description, amount, currency, deadline, timestamp) {
  return `VAP-JOB|To:${seller}|Desc:${description}|Amt:${amount} ${currency}|Deadline:${deadline || 'None'}|Ts:${timestamp}|I request this job and agree to pay upon completion.`;
}
```

The user runs:
```bash
signmessage "alice@" "VAP-JOB|To:bob@|Desc:Code review|Amt:50 VRSC|Deadline:2026-02-15|Ts:1770758507|I request this job and agree to pay upon completion."
```

Simple double quotes. Works in CLI, GUI console, and can be constructed programmatically by Verus Mobile or agent SDKs.

### Verification: Reconstruct, Don't Trust

**Never verify the raw message the user claims they signed.** Always reconstruct the expected message from the submitted parameters and verify against that:

```typescript
// User submits: { seller, description, amount, timestamp, signature }

// WRONG — trusting user's claimed message
const isValid = await rpcCall('verifymessage', [userId, signature, userProvidedMessage]);

// RIGHT — reconstruct the expected message from submitted params
const expectedMessage = generateJobRequestMessage(seller, description, amount, currency, deadline, timestamp);
const isValid = await rpcCall('verifymessage', [userId, signature, expectedMessage]);
```

This prevents an attacker from signing a different message (e.g., different amount) and submitting it with modified parameters.

---

## Identity Resolution: Names vs i-Addresses

VerusIDs have two forms:
- **Friendly name**: `alice@`, `alice.yourapp@`
- **i-address**: `i...` (34-character base58 address)

### What Works Where

| Operation | Friendly Name | i-Address |
|-----------|:---:|:---:|
| `signmessage` | ✅ | ❌ (won't find private key) |
| `verifymessage` | ✅ | ✅ |
| `getidentity` | ✅ | ✅ |

**Key insight:** `signmessage` needs the friendly name because it looks up the private key in the local wallet. `verifymessage` accepts both because it only needs the public key (which it resolves from the blockchain).

### Use `fullyqualifiedname`

When you resolve an identity via RPC, use `fullyqualifiedname` (not `identity.name`):

```typescript
const identity = await rpcCall('getidentity', ['alice@']);

// identity.fullyqualifiedname = "alice.VRSCTEST@"  ← Use this
// identity.identity.name = "alice"                   ← Don't use this (ambiguous)
// identity.identity.identityaddress = "iAddR..."     ← Store this as DB key

// Strip the chain suffix for display
const displayName = identity.fullyqualifiedname
  .replace(/\.VRSCTEST@$/, '')
  .replace(/\.VRSC@$/, '');
// "alice" or "alice.yourapp"
```

### SubID Gotcha

If your identity is a subID (like `alice.yourapp@`), you **cannot** use the parent path for signing:

```bash
# ✅ Works — the actual registered identity
signmessage "alice@" "hello"

# ❌ FAILS — "Invalid identity"  
signmessage "alice.yourapp@" "hello"
# (unless alice.yourapp is a separately registered identity with its own keys)
```

SubIDs under a namespace share the namespace's identity structure but signing requires the identity that actually holds the private key in your wallet.

---

## Security Checklist

Things I learned the hard way:

- [x] **Nonces must be one-time use** — Delete immediately after verification, not after expiry
- [x] **Nonces must expire** — 5 minutes is reasonable. 24 hours is way too long.
- [x] **Use `INSERT OR IGNORE`** for nonce claiming — prevents race conditions where two requests verify the same nonce
- [x] **Timestamp in the challenge message** — Prevents a signed challenge from being replayed after the nonce is regenerated
- [x] **Verify the reconstructed message** — Never trust a user-provided message string
- [x] **Store i-addresses in your DB** — They're immutable. Friendly names can be transferred.
- [x] **Authenticate your callback endpoint** — If you have a separate login microservice forwarding verified results, authenticate that channel (HMAC secret or localhost-only). Otherwise anyone can POST `{ verified: true }` and hijack sessions.
- [x] **HttpOnly + Secure + SameSite=Strict** on session cookies
- [x] **Session lifetime: 1 hour** with sliding window (extend on activity)

---

## Common Errors and Fixes

### "Invalid identity" on signmessage
The identity doesn't exist in your wallet or you're using the wrong name format. Try `listidentities` to see what's available.

### Signature verification returns false but signature looks valid
The message you're verifying against doesn't exactly match what was signed. Even a single character difference (trailing space, different newline) causes failure. Log both the signed message and the verification message and diff them.

### Verus Mobile shows "Invalid Request" on QR scan
Your login consent request is malformed. Common causes:
- Wrong `system_id` (must match the chain: `VRSCTEST` or `VRSC`)
- Invalid `signing_id` (must be a valid i-address)
- Callback URL not reachable from the phone's network

### Login works locally but not in production
Your callback URL must be reachable from Verus Mobile (which runs on the user's phone). If your server is behind a firewall, you need a tunnel (Cloudflare Tunnel, ngrok, etc.) or a public-facing callback endpoint.

### `Context.serialize is not a function`
You're on an older version of `verus-typescript-primitives`. Update the library — the bug has been fixed upstream. See "The Context Bug (Fixed)" section above.

---

## Full Working Example

A minimal but complete VerusID login server:

```typescript
// server.ts — Minimal VerusID CLI/GUI login
import Fastify from 'fastify';
import cookie from '@fastify/cookie';
import crypto from 'crypto';

const app = Fastify();
app.register(cookie);

const RPC_URL = 'http://127.0.0.1:18843';
const RPC_AUTH = Buffer.from('user:pass').toString('base64');
const nonces = new Map<string, { message: string; expiresAt: number }>();

// Cleanup expired nonces every minute
setInterval(() => {
  const now = Date.now();
  for (const [k, v] of nonces) {
    if (v.expiresAt < now) nonces.delete(k);
  }
}, 60000);

async function verusRpc(method: string, params: any[]) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Basic ${RPC_AUTH}` },
    body: JSON.stringify({ method, params, id: 1 }),
  });
  const data = await res.json();
  if (data.error) throw new Error(data.error.message);
  return data.result;
}

// GET /challenge — Generate a login challenge
app.get('/challenge', async () => {
  const nonce = crypto.randomBytes(32).toString('hex');
  const message = `Sign to login | ${nonce} | ${Date.now()}`;
  nonces.set(nonce, { message, expiresAt: Date.now() + 300000 });
  return { nonce, message };
});

// POST /login — Verify signature and create session
app.post('/login', async (req, reply) => {
  const { verusId, signature, nonce } = req.body as any;
  
  const stored = nonces.get(nonce);
  if (!stored || stored.expiresAt < Date.now()) {
    return reply.code(401).send({ error: 'Invalid or expired challenge' });
  }
  nonces.delete(nonce); // One-time use
  
  const isValid = await verusRpc('verifymessage', [verusId, signature, stored.message]);
  if (!isValid) {
    return reply.code(401).send({ error: 'Invalid signature' });
  }
  
  // Resolve identity
  const identity = await verusRpc('getidentity', [verusId]);
  const iAddress = identity.identity.identityaddress;
  
  // Create session
  const sessionId = crypto.randomBytes(32).toString('hex');
  // Store session in your DB...
  
  reply.setCookie('session', sessionId, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 3600,
    path: '/',
  });
  
  return { success: true, identity: iAddress };
});

app.listen({ port: 3000 });
```

---

## Resources

- [Verus RPC Documentation](https://wiki.verus.io/#!faq-cli/clifaq-02_verus_commands.md) — `signmessage`, `verifymessage`, `getidentity`
- [VerusCoin/verusid-ts-client](https://github.com/VerusCoin/verusid-ts-client) — TypeScript library for VerusID Login Consent Protocol
- [VerusCoin/verus-typescript-primitives](https://github.com/VerusCoin/verus-typescript-primitives) — Core Verus types
- [Verus Mobile](https://verus.io/wallet/verus-mobile) — Mobile wallet with QR login support



--- PAGE: developers/verusid-loginconsent-api-flow.md ---

---
label: "VerusID LoginConsent: API-Based Flow"
icon: shield-check
order: 45
---

# VerusID LoginConsent Authentication — API-Based Flow

The VerusID LoginConsent protocol provides mutual authentication between services and users. Both sides verify each other — no passwords, no centralized auth providers.

Verus Mobile handles LoginConsent via deep links and QR codes. But Desktop GUI and CLI users don't need deep links at all. This guide shows how to implement the full LoginConsent protocol using a synchronous API-based flow that works with any wallet that has `signmessage` and `verifysignature`.

## Overview

```
Service (has daemon)              User (Desktop GUI / CLI / SDK)
       |                                    |
  1. Create LoginConsentRequest             |
     Sign with signdata RPC       -------->  |
     Serve via REST API                     |
       |                                    |
       |                          2. Verify service signature
       |                             verifysignature (proves
       |                             challenge is from service)
       |                                    |
       |                          3. Sign the challengeHash
       |                             signmessage (proves user
       |                  <--------  owns the identity)
       |                                    |
  4. Verify user signature                  |
     verifymessage RPC                      |
     Create session               -------->  |
```

No deep links. No URL scheme handlers. No push notifications. The user pulls the challenge, verifies it, signs it, and sends it back. Works with Verus Desktop, Verus CLI, or any SDK that can sign messages offline.

## Step 1: Service Creates LoginConsentRequest

The service builds a LoginConsentRequest using verus-typescript-primitives and signs it with the daemon's `signdata` RPC.

```javascript
import primitives from 'verus-typescript-primitives/dist/vdxf/classes/index.js';
import * as keys from 'verus-typescript-primitives/dist/vdxf/keys.js';
import * as scopes from 'verus-typescript-primitives/dist/vdxf/scopes.js';
import * as vdxf from 'verus-typescript-primitives/dist/vdxf/index.js';
import { toBase58Check } from 'verus-typescript-primitives/dist/utils/address.js';
import { I_ADDR_VERSION } from 'verus-typescript-primitives/dist/constants/vdxf.js';
import { randomBytes } from 'crypto';

const SERVICE_ID = 'yourservice@';
const SYSTEM_ID = 'iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq'; // VRSCTEST

// Generate unique challenge ID (base58check i-address format)
const challengeId = toBase58Check(randomBytes(20), I_ADDR_VERSION);

// Build the challenge
// redirect_uris can include a webhook for mobile QR compatibility,
// or be left empty for pure API-based flows.
const challenge = new primitives.LoginConsentChallenge({
  challenge_id: challengeId,
  created_at: Math.floor(Date.now() / 1000),
  requested_access: [
    new primitives.RequestedPermission(scopes.IDENTITY_VIEW.vdxfid),
  ],
  redirect_uris: [
    // Optional: include webhook for Verus Mobile QR compatibility
    new primitives.RedirectUri(
      'https://yourservice.example/auth/callback',
      keys.LOGIN_CONSENT_WEBHOOK_VDXF_KEY.vdxfid,
    ),
  ],
});

const loginRequest = new primitives.LoginConsentRequest({
  system_id: SYSTEM_ID,
  signing_id: serviceIAddress, // resolved via getidentity
  challenge,
});

// Sign with daemon's signdata RPC
// IMPORTANT: Pass challenge.toSha256(), NOT getChallengeHash().
// The daemon internally adds system_id + block height + signing_id
// to the hash before ECDSA signing.
const challengeSha256 = challenge.toSha256();
const signResult = await rpc('signdata', [{
  address: SERVICE_ID,
  datahash: challengeSha256.toString('hex'),
}]);
// signResult = { signature: string, signatureheight: number }

loginRequest.signature = new vdxf.VerusIDSignature(
  { signature: signResult.signature },
  keys.IDENTITY_AUTH_SIG_VDXF_KEY,
);

const challengeHash = challengeSha256.toString('hex');
```

Serve via your API:
```json
{
  "challengeId": "iBase58CheckNonce",
  "challengeHash": "abc123...64hex",
  "requestSignature": "AgVm...(base64 signdata output)",
  "blockHeight": 990566,
  "signingId": "iXYZ...(service i-address)",
  "expiresAt": "2026-03-24T12:05:00Z"
}
```

## Step 2: User Verifies the Service's Identity

Before signing anything, the user confirms the challenge came from the claimed service. This is the mutual authentication step.

**Desktop GUI (debug console):**
```
run verifysignature '{"address":"yourservice@","datahash":"<challengeHash>","signature":"<requestSignature>"}'
```

**CLI:**
```
./verus -testnet verifysignature '{"address":"yourservice@","datahash":"<challengeHash>","signature":"<requestSignature>"}'
```

If valid, the challenge is genuine. If not — do not sign.

## Step 3: User Signs the ChallengeHash

**Desktop GUI:**
```
run signmessage "myidentity@" "<challengeHash>"
```

**CLI:**
```
./verus -testnet signmessage "myidentity@" "<challengeHash>"
```

Produces a base64 signature proving the user controls the identity.

## Step 4: Service Verifies the User's Signature

```javascript
const isValid = await rpc('verifymessage', [
  'myidentity@', challengeHash, signature, true
]);

const identity = await rpc('getidentity', ['myidentity@']);
const iAddress = identity.identity.identityaddress;
const friendlyName = identity.fullyqualifiedname;
// Create session, issue token, etc.
```

## SDK / Offline Signing (No Daemon on Client Side)

For programmatic use, the client needs no daemon. bitcoinjs-message with the Verus prefix handles offline signing:

```javascript
import bitcoinMessage from 'bitcoinjs-message';
const messagePrefix = '\x15Verus signed data:\n';
const signature = bitcoinMessage.sign(
  challengeHash, privateKeyBuffer, compressed, messagePrefix
);
```

The service's daemon verifies with `verifymessage` as normal. The user's private key never leaves their machine.

## Security Properties

| Property | How |
|----------|-----|
| Service authenticity | LoginConsentRequest signed via signdata — user verifies with verifysignature |
| User authenticity | signmessage verified by daemon against on-chain keys |
| Replay prevention | Random challenge_id, short expiry, single-use |
| Block height binding | signdata includes block height — daemon checks keys were valid at that height |
| Offline capable | Client needs only a WIF key + bitcoinjs-message |

## Compared to Raw signmessage

Raw `signmessage` (sign a random text challenge) provides no mutual authentication — the user cannot verify who created the challenge. An attacker could serve a fake challenge and collect signatures.

The LoginConsent flow fixes this: the service signs the challenge with its on-chain identity, and the user verifies that signature before responding.

## Dependencies

- `verus-typescript-primitives` — LoginConsentRequest/Response classes, serialization, VDXF keys
- `bitcoinjs-message` — Offline message signing (Verus-compatible)
- A Verus daemon on the SERVICE side (for signdata + verifymessage)
- Any wallet with signmessage + verifysignature on the USER side

## Reference

- [verus-typescript-primitives](https://github.com/VerusCoin/verus-typescript-primitives)
- [verusid-ts-client](https://github.com/VerusCoin/verusid-ts-client)
- [Verus Mobile LoginConsent](https://github.com/VerusCoin/Verus-Mobile) (src/containers/DeepLink/)


--- PAGE: faq/defi.md ---

---
label: DeFi
icon: sync
order: 80
description: "Frequently asked questions about Verus DeFi — basket currencies, protocol-level AMM, MEV resistance, and the Ethereum bridge."
---

# DeFi FAQ

Common questions about decentralized finance on Verus — how it works without smart contracts.

---

## How does Verus DeFi work without smart contracts?

**Verus DeFi is built directly into the protocol's consensus rules. The AMM, currency conversions, and token launches are validated by every node — like how Bitcoin validates "you can't spend coins you don't have."**

On Ethereum, DeFi runs in smart contracts — separate programs deployed on the blockchain that can have bugs, exploits, and admin keys. On Verus, the equivalent functionality is part of the node software itself:

| Ethereum DeFi | Verus DeFi |
|---------------|-----------|
| Smart contract (Solidity code) | Protocol consensus rules |
| Can have bugs/exploits | Same code secures every basket |
| Contract owner can change rules | Rules are fixed at launch |
| High gas costs | 0.0001 VRSC per transaction |
| Requires audit | No separate contract to audit |

This doesn't mean Verus is "better" for all use cases — you can't write arbitrary DeFi logic. But for the features it provides (AMM, token launch, conversions), the protocol-level approach eliminates entire categories of risk.

Learn more: [Basket Currencies and DeFi](/concepts/basket-currencies-defi/) | [Currencies and Tokens](/concepts/currencies-and-tokens/)

---

## What is a basket currency?

**A basket currency is a token backed by reserves of one or more other currencies, with automatic on-chain conversion via a protocol-level AMM. Think of it like a decentralized ETF.**

When someone buys a basket currency with one of its reserves, that reserve flows into the basket and new tokens are minted. When someone sells, tokens are burned and reserves flow out. The price adjusts automatically based on reserve ratios.

Example:
```
MYBASKET (basket currency)
├── Reserve: VRSC  (weight: 50%)
└── Reserve: USDC  (weight: 50%)

Buy MYBASKET with VRSC → VRSC enters reserves, MYBASKET minted
Sell MYBASKET for VRSC → MYBASKET burned, VRSC exits reserves
```

Basket currencies are created with a single CLI command (`definecurrency`) — no code required.

Learn more: [Basket Currencies and DeFi](/concepts/basket-currencies-defi/) | [How to Convert Currencies](/how-to/convert-currencies/)

---

## Does Verus have MEV?

**Verus is MEV-resistant by design. All currency conversions within a single block execute simultaneously at the same price, making front-running impossible.**

On Ethereum, miners/validators can reorder transactions to extract value (MEV). Bots watch the mempool and insert transactions before yours to profit from price changes. This is a major problem:

- **Sandwich attacks**: Bot buys before you, sells after you
- **Front-running**: Bot copies your trade at a better price
- **Back-running**: Bot trades immediately after a large order

On Verus, all conversions in a block are batched and executed at one price. There's no ordering advantage — a transaction submitted first gets the same price as one submitted last (within the same block). This eliminates the entire MEV category.

Learn more: [Basket Currencies and DeFi — MEV Resistance](/concepts/basket-currencies-defi/#mev-resistance-fair-pricing)

---

## How do I swap currencies on Verus?

**Use the `sendcurrency` command with a `convertto` parameter. The protocol handles the conversion through the basket currency's reserves.**

```bash
# Convert 100 VRSC to Bridge.vETH (via the basket currency)
verus sendcurrency '*' '[{"currency":"VRSC","convertto":"Bridge.vETH","amount":100,"address":"your_address@"}]'
```

You can estimate the conversion first:
```bash
verus estimateconversion '{"currency":"VRSC","convertto":"Bridge.vETH","amount":100}'
```

The conversion fee is typically 0.025% (set at currency launch). There's no slippage in the traditional sense — the price is determined by reserve ratios after all conversions in the block are applied.

Learn more: [How to Convert Currencies](/how-to/convert-currencies/)

---

## How do I launch a token on Verus?

**Use the `definecurrency` CLI command. No programming, no Solidity, no deployment scripts — just specify the parameters and the protocol creates it.**

Simple token:
```bash
verus -chain=vrsctest definecurrency '{"name":"MyToken","options":32,"preallocations":[{"my_address@":1000000}]}'
```

Basket currency (with reserves):
```bash
verus definecurrency '{"name":"MyBasket","currencies":["VRSC","Bridge.vETH"],"initialcontributions":[1000,5],"conversions":[1,1]}'
```

The token exists as a first-class protocol object — it can be sent, received, converted, and traded on the marketplace immediately.

Learn more: [How to Launch a Token](/how-to/launch-token/) | [Tutorial: Launch Your First Token](/tutorials/launch-your-first-token/)

---

## What is the Ethereum bridge?

**A trustless, decentralized bridge that connects Verus and Ethereum, allowing transfers of ETH, ERC-20 tokens, VRSC, and Verus currencies between the two networks.**

The bridge uses a notarization system — Verus notaries monitor both chains and confirm cross-chain transactions. No single entity controls the bridge; it's secured by the same consensus mechanism as the rest of the protocol.

What you can do:
- Send ETH and ERC-20 tokens from Ethereum to Verus
- Send VRSC and Verus currencies from Verus to Ethereum
- Use ETH and ERC-20 tokens in Verus DeFi (basket currencies)

Learn more: [How to Bridge from Ethereum](/how-to/bridge-from-ethereum/) | [Bridge and Cross-Chain](/concepts/bridge-and-crosschain/)


--- PAGE: faq/general.md ---

---
label: General
icon: question
order: 100
description: "Frequently asked questions about the Verus blockchain — what it is, how it differs from Ethereum, and its origins."
---

# General FAQ

Common questions about the Verus protocol, answered directly.

---

## What is Verus?

**Verus is a blockchain protocol with self-sovereign identity, protocol-level DeFi, CPU mining, and zero-knowledge privacy — all built into layer 1 with no smart contracts.**

Verus (VRSC) launched in May 2018 as a fair launch with no ICO, no premine, and no developer tax. It provides features that most blockchains implement through smart contracts — identity, decentralized exchange, multi-chain interoperability, and privacy — directly at the protocol level, validated by every node in the network.

Key capabilities:
- **VerusID**: Human-readable, revocable, recoverable on-chain identity
- **Basket currencies**: Protocol-level AMM with MEV resistance
- **50/50 hybrid mining/staking**: CPU-mineable with VerusHash 2.2
- **Sapling privacy**: Full zero-knowledge shielded transactions
- **PBaaS**: Launch independent, interoperable blockchains
- **Ethereum bridge**: Trustless, decentralized bridge to Ethereum

Learn more: [Key Concepts](/getting-started/key-concepts/) | [The Hidden Power of Verus](/introduction/the-hidden-power-of-verus/)

---

## How is Verus different from Ethereum?

**Verus builds DeFi and identity into the protocol itself, while Ethereum relies on smart contracts. This eliminates contract exploits, MEV, and high gas fees.**

| Aspect | Verus | Ethereum |
|--------|-------|----------|
| DeFi | Protocol-level AMM | Smart contracts (Uniswap, etc.) |
| Identity | VerusID (protocol-native) | ENS (smart contract) |
| MEV | Resistant (simultaneous execution) | Rampant |
| Privacy | Sapling zk-SNARKs | No native privacy |
| Fees | ~0.0001 VRSC | Variable gas fees |
| Smart contracts | No (not needed) | Yes (EVM/Solidity) |
| Mining | CPU (VerusHash 2.2) | N/A (Proof of Stake) |
| Token launch | CLI command, no code | Requires Solidity contract |

The trade-off: Ethereum has a much larger ecosystem and supports arbitrary programmable logic. Verus's features are powerful but fixed — you can't write custom smart contract logic, because the protocol provides the most-needed features natively.

Learn more: [Verus Facts — Comparison Table](/verus-facts/#verus-vs-other-blockchains)

---

## Is Verus a fork of Zcash?

**Yes, originally. Verus forked from Komodo (which forked from Zcash), but has been so heavily modified that the codebase is now fundamentally different.**

The Zcash heritage gives Verus its Sapling zero-knowledge proof system for private transactions. However, Verus has added:

- An entirely new identity system (VerusID)
- Protocol-level DeFi (basket currencies and AMM)
- PBaaS multi-chain architecture
- VerusHash 2.2 mining algorithm
- A native marketplace with atomic swaps
- VDXF structured data standard
- On-chain file storage
- A trustless Ethereum bridge
- 201 CLI commands (vs ~80 in base Zcash)

The relationship is similar to how Android started from Linux — the foundation is there, but the end product is a different system entirely.

---

## Who created Verus?

**Verus was created by Michael Toutonghi, former VP and Technical Fellow at Microsoft, where he co-invented the .NET platform.**

The project launched in 2018 with a fair launch model: no ICO, no premine, no investor allocation, and no developer tax. Development is funded by the community. The protocol is open-source under the MIT license.

- **GitHub**: [github.com/VerusCoin](https://github.com/VerusCoin)
- **Website**: [verus.io](https://verus.io)

---

## Is Verus decentralized?

**Yes. Verus has no central authority, no admin keys, no governance token voting, and no way for developers to freeze or modify the protocol without a network-wide upgrade.**

Key decentralization properties:
- **Fair launch**: No premine or insider allocation
- **CPU mining**: VerusHash 2.2 keeps mining accessible to regular hardware
- **No smart contract admin**: Protocol features have no "owner" who can change rules
- **No dev tax**: Community-funded development
- **Hybrid consensus**: Both miners and stakers secure the network

---

## What is VRSC used for?

**VRSC is the native currency of Verus, used for transaction fees, VerusID registration, staking, mining rewards, and as reserve backing for basket currencies.**

Specific uses:
- **Transaction fees**: 0.0001 VRSC per transaction
- **VerusID registration**: ~100 VRSC for a root identity (~80 with referral)
- **SubID registration**: As low as 0.01 VRSC (set by namespace owner)
- **Staking**: Lock VRSC to earn block rewards
- **Mining rewards**: Earned by mining blocks with CPU
- **Currency reserves**: Used as reserve backing in basket currencies
- **Marketplace**: Buy and sell currencies, tokens, and identities

---

## How do I get started with Verus?

**Download the software, sync the blockchain, and create a wallet address. The whole process takes about 30 minutes (mostly waiting for sync).**

1. [Install Verus](/getting-started/installation/) — Download Verus Desktop (GUI) or CLI
2. [First Steps](/getting-started/first-steps/) — Start the daemon and sync
3. [Wallet Setup](/getting-started/wallet-setup/) — Create addresses and receive VRSC
4. [Key Concepts](/getting-started/key-concepts/) — Understand VerusID, currencies, mining, staking, privacy

For AI agents: [Agent Bootstrap Guide](/for-agents/agent-bootstrap/)


--- PAGE: faq/identity.md ---

---
label: Identity
icon: person
order: 90
description: "Frequently asked questions about VerusID — cost, features, recovery, multisig, and use cases."
---

# Identity FAQ

Common questions about VerusID, the self-sovereign identity system built into the Verus protocol.

---

## What is a VerusID?

**A VerusID is a human-readable, on-chain identity (like `alice@`) that can hold funds, prove ownership, store data, and be recovered if keys are lost — all without any centralized authority.**

A VerusID combines:
- **A human-readable name**: People send to `alice@` instead of a random address
- **A crypto wallet**: Holds VRSC and other currencies
- **A digital passport**: Cryptographically signs messages and transactions
- **A data vault**: Stores arbitrary data on-chain (public or encrypted)
- **A recoverable identity**: Keys can be rotated without losing the identity

Unlike accounts on platforms like Google or Twitter, no company controls your VerusID. It exists on the blockchain permanently.

Learn more: [VerusID In Depth](/concepts/identity-system/) | [Register a VerusID](/how-to/create-verusid/)

---

## How much does a VerusID cost?

**A root VerusID costs ~100 VRSC (~80 VRSC with a referral). SubIDs can cost as little as 0.01 VRSC.**

| ID Type | Cost | Example |
|---------|------|---------|
| Root VerusID | ~100 VRSC (80 with referral) | `alice@` |
| SubID | Set by namespace owner (as low as 0.01 VRSC) | `bob.MyCurrency@` |
| PBaaS chain ID | Varies by chain | `alice.MyChain@` |

The cost of a root VerusID is a protocol-level fee that goes partially to the referrer (if any) and partially to miners/stakers. SubID pricing is controlled by the namespace (currency) owner.

Learn more: [Register a VerusID](/how-to/create-verusid/) | [Manage SubIDs](/how-to/manage-subids/)

---

## Can I recover a lost VerusID?

**Yes. VerusID has a built-in revocation and recovery system — you can freeze a compromised identity and reassign new keys without losing the identity itself.**

How it works:
1. Each VerusID has a **revocation authority** and a **recovery authority** (these can be other VerusIDs or the same ID)
2. If your keys are compromised, the revocation authority **revokes** (freezes) the identity
3. The recovery authority **recovers** the identity with entirely new keys
4. The identity keeps its name, history, and address — only the controlling keys change

This is one of Verus's most important features. On most blockchains, lost keys mean lost funds forever. On Verus, identity recovery is a protocol-level operation.

Learn more: [How to Revoke and Recover](/how-to/revoke-recover-identity/)

---

## What is a SubID?

**A SubID is a child identity created under a parent namespace. If you own a currency called `MyCurrency`, you can create identities like `user.MyCurrency@` at prices you set.**

SubIDs are useful for:
- **Organizations**: `employee.CompanyName@`
- **Applications**: `user123.MyApp@`
- **Agent registries**: `agent.AgentHub@`
- **Communities**: `member.CommunityName@`

The namespace owner controls:
- SubID pricing (can be as low as 0.01 VRSC)
- Whether anyone can register or only the owner can issue them
- Referral discounts

SubIDs have all the same capabilities as root IDs: they can hold funds, store data, be revoked and recovered, and use multisig.

Learn more: [Manage SubIDs](/how-to/manage-subids/)

---

## Does VerusID support multisig?

**Yes. VerusID has native M-of-N multisig — you set multiple primary addresses and a minimum signature threshold directly on the identity.**

Example: A 2-of-3 multisig identity has three keyholders, and any two must agree to sign a transaction:

```
primaryaddresses: ["R_addr_1", "R_addr_2", "R_addr_3"]
minimumsignatures: 2
```

No special scripts or smart contracts are needed. Multisig is a built-in property of every VerusID.

Learn more: [Setup Multisig](/how-to/setup-multisig/)

---

## Can I store data on a VerusID?

**Yes. Every VerusID has a `contentmultimap` field that stores arbitrary key-value data on-chain using the VDXF (Verus Data Exchange Format) standard.**

You can store:
- Public text, JSON, or binary data
- Encrypted data (encrypted to a Sapling z-address)
- Files (automatically split across transactions if large)
- Structured data with schema definitions

Data is stored permanently on-chain. There's no external storage dependency like IPFS.

Learn more: [VDXF Data Standard](/concepts/vdxf-data-standard/) | [On-Chain File Storage](/concepts/on-chain-file-storage/)

---

## Can VerusID be used for login/authentication?

**Yes. VerusID supports cryptographic signature-based authentication — a user proves they control an identity by signing a challenge, with no password needed.**

The flow:
1. Application presents a challenge string
2. User signs it with their VerusID (`signmessage`)
3. Application verifies the signature (`verifymessage`)

This enables passwordless login for any application that integrates with the Verus RPC API.

Learn more: [VerusID Login Guide](/developers/verusid-login-guide/)


--- PAGE: faq/mining-staking.md ---

---
label: Mining & Staking
icon: cpu
order: 70
description: "Frequently asked questions about Verus mining and staking — VerusHash 2.2, CPU mining, staking requirements, and rewards."
---

# Mining and Staking FAQ

Common questions about mining and staking on Verus.

---

## How do I mine Verus?

**Run `verus setgenerate true <threads>` on your Verus node. Verus uses VerusHash 2.2, a CPU-optimized algorithm — no GPU or ASIC needed.**

Quick start:
```bash
# Start mining with 4 CPU threads
verus setgenerate true 4

# Check mining status
verus getmininginfo

# Stop mining
verus setgenerate false
```

You can also use external mining software (like ccminer) to mine in a pool. Solo mining with the built-in miner works for testing but pool mining is more practical for consistent rewards.

Learn more: [How to Mine VRSC](/how-to/mine-vrsc/) | [Mining and Staking Concepts](/concepts/mining-and-staking/)

---

## What is VerusHash?

**VerusHash 2.2 is Verus's custom mining algorithm, designed to keep CPU mining competitive against specialized hardware (FPGAs and GPUs).**

Key properties:
- Uses AES and AVX instructions that map well to modern CPUs
- FPGAs can mine but are equalized to ~2x CPU cost-performance
- No ASICs exist for VerusHash
- GPUs can mine (via ccminer) but are generally less efficient than CPUs
- A modern desktop CPU can meaningfully participate in mining

This matters because CPU accessibility supports decentralization — anyone with a computer can mine, not just those who can afford specialized hardware.

---

## Can I stake VRSC?

**Yes. Any amount of VRSC can be staked. Just run the daemon and enable staking — no minimum, no lockup, no special hardware.**

```bash
# Enable staking (0 threads = staking only, no mining)
verus setgenerate true 0

# Or mine and stake simultaneously
verus setgenerate true 4
```

Requirements:
- VRSC in your wallet (any amount)
- UTXOs must be mature (150 confirmations, ~2.5 hours)
- Daemon running and synced
- Wallet unlocked (if encrypted)

The probability of finding a staking block is proportional to the size of your UTXOs. Larger UTXOs stake more frequently.

Learn more: [How to Stake VRSC](/how-to/stake-vrsc/)

---

## What are the mining/staking rewards?

**The block reward is 3 VRSC per block on mainnet (era 9, starting at block 3,381,840), plus the transaction fee pool. On testnet (VRSCTEST), the block reward is 6 VRSCTEST. Rewards halve approximately every 2 years (~1,051,920 blocks). Half of blocks go to miners, half to stakers.**

| Fact | Value |
|------|-------|
| Current block reward | 3 VRSC (mainnet) / 6 VRSCTEST (testnet) |
| Fee pool | Yes — transaction fees included in block reward |
| Block time | ~60 seconds |
| PoW/PoS split | ~50/50 |
| Halving schedule | Approximately every 2 years (~1,051,920 blocks) |
| Next halving | ~August 2026 |
| Max supply | 83,540,184 VRSC |

Miners earn the full block reward plus transaction fees for PoW blocks they find. Stakers earn the full block reward plus transaction fees for PoS blocks they validate. There is no developer tax or foundation cut.

---

## Do I need special hardware to mine?

**No. A modern desktop or laptop CPU is the primary mining hardware for Verus. Server CPUs with more cores will mine faster, but any CPU works.**

Hardware comparison:
- **CPUs**: Primary mining hardware (best cost-performance)
- **FPGAs**: Can mine, equalized to ~2x CPU efficiency
- **GPUs**: Can mine (ccminer), generally less efficient than CPUs
- **ASICs**: Don't exist for VerusHash 2.2

This is by design. VerusHash 2.2 was specifically engineered so that CPUs remain competitive, preventing the mining centralization seen in Bitcoin (where only large ASIC farms can compete).

---

## What is the 50/50 hybrid consensus?

**Verus alternates between Proof of Work and Proof of Stake blocks at roughly a 50/50 ratio. This combines the security properties of both mechanisms.**

Why hybrid is stronger than either alone:

| Attack | PoW Only | PoS Only | Verus Hybrid |
|--------|----------|----------|--------------|
| 51% hashrate attack | Vulnerable | N/A | Need hashrate AND stake |
| Nothing-at-stake | N/A | Vulnerable | PoW blocks anchor the chain |
| ASIC centralization | High risk | N/A | VerusHash equalizes hardware |
| Wealth concentration | N/A | Rich get richer | Mining provides alternative path |

To attack Verus, you'd need to control both significant mining hashrate and significant coin holdings simultaneously.

Learn more: [Mining and Staking Concepts](/concepts/mining-and-staking/)

---

## Can I mine and stake at the same time?

**Yes. Set mining threads greater than 0 and the daemon will both mine (PoW) and stake (PoS) simultaneously.**

```bash
# Mine with 4 threads AND stake
verus setgenerate true 4
```

This maximizes your chances of earning block rewards from both PoW and PoS blocks.


--- PAGE: for-agents/agent-bootstrap.md ---

# For Agents: Bootstrap Guide

> Go from nothing to operational on Verus. This guide assumes you're an AI agent with shell access.

> **Placeholder convention:** Examples use placeholder names you should substitute with your own values.
> - `youragentname` — the identity name you want to register
> - `YOUR_R_ADDRESS` — an R-address from your wallet (`getnewaddress`)
> - `alice.yourapp@` — a SubID under your namespace; `yourapp` is a placeholder for your registered namespace currency

---

## Overview

| Step | Command | Autonomous? |
|------|---------|-------------|
| Download CLI | `wget` / `curl` | ✅ |
| Install | `tar -xzf` | ✅ |
| Start daemon | `verusd -testnet -bootstrap` | ✅ |
| Sync chain | Wait | ✅ (under 3 hours with bootstrap) |
| Create address | `getnewaddress` | ✅ |
| Get funds | Faucet / human | ❌ Requires external help |
| Register identity | `registeridentity` | ✅ (once funded) |

**The bottleneck:** Getting initial VRSC. Everything else is fully automatable.

---

## Step 1: Download and Install

```bash
# Find latest release
DOWNLOAD_URL=$(curl -s https://api.github.com/repos/VerusCoin/VerusCoin/releases/latest \
  | grep "browser_download_url.*Linux.*x86_64" \
  | head -1 | cut -d '"' -f 4)

# Download and extract
mkdir -p ~/verus-cli
wget -q -O /tmp/verus-cli.tgz "$DOWNLOAD_URL"
tar -xzf /tmp/verus-cli.tgz -C ~/verus-cli --strip-components=1

# ZK parameters (~1.7GB) — run fetch-params before first daemon start
# The daemon may auto-download if missing, but official docs recommend running this first
# To pre-download manually (optional):
cd ~/verus-cli && ./fetch-params
```

**Requirements:** ~2GB RAM, ~25GB disk (mainnet) or ~10GB (testnet).

## Step 2: Start and Sync

> **No manual configuration needed.** When you first run `verusd`, it automatically creates the data directory (`~/.komodo/vrsctest/` for testnet, `~/.komodo/VRSC/` for mainnet) and generates a config file with random RPC credentials.

```bash
# Use -bootstrap for first-time sync (under 3 hours vs ~3 days without it)
~/verus-cli/verusd -testnet -bootstrap

# Poll sync status
while true; do
  BLOCKS=$(~/verus-cli/verus -testnet getinfo 2>/dev/null | grep '"blocks"' | tr -dc '0-9')
  HEADERS=$(~/verus-cli/verus -testnet getinfo 2>/dev/null | grep '"headers"' | tr -dc '0-9')
  echo "Sync: $BLOCKS / $HEADERS"
  [ "$BLOCKS" = "$HEADERS" ] && [ -n "$BLOCKS" ] && echo "SYNCED" && break
  sleep 60
done
```

**Time with `-bootstrap`:** Under 3 hours (testnet or mainnet). Without bootstrap: testnet 2–6 hours, mainnet ~3 days.

### Reading Auto-Generated Credentials

After first launch, read the auto-generated RPC credentials:

```bash
# Testnet
cat ~/.komodo/vrsctest/vrsctest.conf | grep -E "rpcuser|rpcpassword|rpcport"

# Save for programmatic access
RPC_USER=$(grep rpcuser ~/.komodo/vrsctest/vrsctest.conf | cut -d= -f2)
RPC_PASS=$(grep rpcpassword ~/.komodo/vrsctest/vrsctest.conf | cut -d= -f2)
RPC_PORT=$(grep rpcport ~/.komodo/vrsctest/vrsctest.conf | cut -d= -f2)

cat > ~/.verus-rpc-credentials << EOF
RPC_URL=http://127.0.0.1:${RPC_PORT:-18843}
RPC_USER=$RPC_USER
RPC_PASS=$RPC_PASS
EOF
```

> 💡 **Optional:** You can add custom settings (like `addnode=`) to the auto-generated conf file. Just edit it and restart the daemon.

## Step 3: Create Address

```bash
~/verus-cli/verus -testnet getnewaddress "agent-wallet"
# Returns: R-address (save this)
```

## Step 4: Get Funded

This is the step that requires external help:

| Method | How |
|--------|-----|
| **Testnet faucet** | Ask in Verus Discord #testnet-faucet |
| **Human sponsor** | Have someone send VRSCTEST to your R-address |
| **Mining** | `./verus -testnet setgenerate true 1` (slow) |

You need ~100 VRSCTEST for identity registration + fees (free test currency from faucet). On mainnet, a root ID costs ~100 VRSC (80 with referral). The 20 VRSC discount goes to the referral chain, not back to the registrant — you always pay 80 minimum. Free IDs are available via Valu, and subIDs/PBaaS chain IDs can cost pennies.

## Step 5: Register Identity

```bash
# Commitment (prevents front-running)
~/verus-cli/verus -testnet registernamecommitment "youragentname" "YOUR_R_ADDRESS"
# SAVE THE ENTIRE OUTPUT — you need txid and salt

# Wait for 1 confirmation (~1 minute)
sleep 90

# Register
~/verus-cli/verus -testnet registeridentity '{
  "txid": "COMMITMENT_TXID",
  "namereservation": {
    "version": 1,
    "name": "youragentname",
    "salt": "SALT_FROM_COMMITMENT",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "referral": "",
    "nameid": "NAMEID_FROM_COMMITMENT"
  },
  "identity": {
    "name": "youragentname",
    "primaryaddresses": ["YOUR_R_ADDRESS"],
    "minimumsignatures": 1,
    "revocationauthority": "youragentname.VRSCTEST@",
    "recoveryauthority": "youragentname.VRSCTEST@"
  }
}'

# Verify (after 1 confirmation)
sleep 90
~/verus-cli/verus -testnet getidentity "youragentname.VRSCTEST@"
```

## Step 6: You're Operational

With a VerusID, you can now:
- Store data on-chain → [Agent Identity](./agent-identity.md)
- Send/receive payments → [Agent Economy](./agent-economy.md)
- Encrypt communications → [Agent Messaging](./agent-messaging.md)
- Sign and verify messages → [CLI Reference](./agent-cli-reference.md)

---

## RPC Access Pattern

For all subsequent operations, use JSON-RPC:

```bash
# Generic RPC call pattern
curl -s -u "$RPC_USER:$RPC_PASS" http://127.0.0.1:18843 \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"1.0\",\"id\":\"agent\",\"method\":\"METHOD\",\"params\":[PARAMS]}"
```

See [RPC API Overview](../developers/rpc-api-overview.md) for language-specific examples.

---

## Keeping the Daemon Running

```bash
# Option 1: systemd (if you have root)
sudo tee /etc/systemd/system/verusd.service << EOF
[Unit]
Description=Verus Daemon
After=network.target

[Service]
User=$USER
ExecStart=$HOME/verus-cli/verusd -testnet -fastload
ExecStop=$HOME/verus-cli/verus -testnet stop
Restart=always

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now verusd

# Option 2: tmux
tmux new -d -s verusd "~/verus-cli/verusd -testnet"

# Option 3: nohup
nohup ~/verus-cli/verusd -testnet &
```

---

## Complete Bootstrap Script

```bash
#!/bin/bash
set -e

NETWORK="${1:-testnet}"
INSTALL_DIR="$HOME/verus-cli"

echo "=== Verus Agent Bootstrap ($NETWORK) ==="

# Download
URL=$(curl -s https://api.github.com/repos/VerusCoin/VerusCoin/releases/latest \
  | grep "browser_download_url.*Linux.*x86_64" | head -1 | cut -d '"' -f 4)
mkdir -p "$INSTALL_DIR"
wget -q -O /tmp/verus-cli.tgz "$URL"
tar -xzf /tmp/verus-cli.tgz -C "$INSTALL_DIR" --strip-components=1

# ZK params
[ ! -f "$HOME/.zcash-params/sprout-proving.key" ] && cd "$INSTALL_DIR" && ./fetch-params

# Set network args
if [ "$NETWORK" = "testnet" ]; then
  DARGS="-testnet"; CONF_DIR="$HOME/.komodo/vrsctest"; CONF="vrsctest.conf"; PORT=18843
else
  DARGS=""; CONF_DIR="$HOME/.komodo/VRSC"; CONF="VRSC.conf"; PORT=27486
fi

# Start with bootstrap (auto-creates dirs and conf with random RPC credentials)
"$INSTALL_DIR/verusd" $DARGS -bootstrap -daemon
sleep 10

# Read auto-generated credentials
RPC_USER=$(grep rpcuser "$CONF_DIR/$CONF" | cut -d= -f2)
RPC_PASS=$(grep rpcpassword "$CONF_DIR/$CONF" | cut -d= -f2)

# Create address
ADDR=$("$INSTALL_DIR/verus" $DARGS getnewaddress "agent-wallet")
echo "Address: $ADDR"
echo "RPC: http://127.0.0.1:$PORT (user: $RPC_USER)"
echo "⚠️  Send VRSC to $ADDR, then register your identity."
```

---

## Error Handling Tips

RPC errors return a non-zero exit code and a JSON error object. Common ones:

| Error Code | Message | Likely Cause |
|------------|---------|--------------|
| -5 | `Identity not found` | Name doesn't exist or wrong qualification (`alice@` vs `alice.yourapp@`) |
| -8 | `Invalid identity or identity not in wallet` | Trying to sign/send from an ID you don't control |
| -6 | `Insufficient funds` | Not enough balance for amount + fees |
| -1 | Various | Invalid parameters — check `verus help <command>` |

**Best practices:**
- Always check exit codes in scripts: `verus -testnet getidentity "name@" || echo "FAILED"`
- Parse stderr for error details
- Use fully qualified names for SubIDs (e.g., `alice.yourapp@`, not `alice@`)
- After registration, wait for 1 confirmation before querying the new identity

---

*Last updated: 2026-02-07*


--- PAGE: for-agents/agent-cli-reference.md ---

# For Agents: CLI Quick Reference

> The essential Verus commands for AI agents, organized by task. All examples use JSON-RPC via curl. Replace credentials and addresses with your own.

> **Placeholder convention:** Examples use placeholder names you should substitute with your own values.
> - `myid@` — your top-level VerusID
> - `alice.yourapp@` — a SubID under your namespace
> - `yourapp` — your registered namespace currency (placeholder, not a real testnet currency)
> - `myid::agent.v1.*` — VDXF keys under your namespace; keep `agent.v1.*` for interoperability, replace `myid` with your identity name
> - `i...` — placeholder for an i-address; derive real values with `getvdxfid`

---

## Getting Help

```bash
verus help              # List all available commands
verus help <command>    # Detailed usage for a specific command
verus -testnet help sendcurrency   # Works with -testnet too
```

---

## Name Qualification

Understanding name formats is critical — using the wrong form will give "Identity not found":

| Format | Meaning | Example |
|--------|---------|---------|
| `name@` | Top-level identity on the current chain | `myid@` (looks for top-level "myid") |
| `name.PARENT@` | SubID under a parent namespace | `alice.yourapp@` (SubID under yourapp) |
| `name.VRSCTEST@` | Fully qualified on testnet | `myid.VRSCTEST@` (same as `myid@` on testnet) |

**Common mistake:** `alice@` looks for a *top-level* identity called "alice". If alice is a SubID under yourapp, you must use `alice.yourapp@`. Using the wrong form returns "Identity not found".

```bash
# ✅ Correct — alice is a SubID under yourapp
getidentity "alice.yourapp@"

# ❌ Wrong — no top-level identity called "alice" exists
getidentity "alice@"
# → error code: -5, "Identity not found"
```

---

## Common Testnet Currencies

| Currency | Description |
|----------|-------------|
| `VRSCTEST` | Native testnet coin (equivalent of VRSC on mainnet) |
| `Bridge.vETH` | Bridge currency for Ethereum testnet |
| `VRSC-USD` | USD-pegged test currency |
| `yourapp` | Placeholder — replace with your own registered namespace currency |

---

## RPC Call Pattern

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:$RPC_PORT \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"1","method":"METHOD","params":[PARAMS]}'
```

**Ports:** Testnet=18843, Mainnet=27486

---

## Identity

### Look Up Identity
```bash
# method: getidentity
# params: ["name@"]
{"method":"getidentity","params":["alice@"]}
```

### Register Identity (2-step)
```bash
# Step 1: Commit
{"method":"registernamecommitment","params":["name","R_ADDRESS"]}

# Step 2: Register (after 1 confirmation)
{"method":"registeridentity","params":[{
  "txid":"COMMITMENT_TXID",
  "namereservation":{"name":"name","salt":"SALT","parent":"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq","referral":""},
  "identity":{"name":"name","primaryaddresses":["R_ADDR"],"minimumsignatures":1}
}]}
```

### Update Identity
```bash
{"method":"updateidentity","params":[{
  "name":"name",
  "parent":"iPARENT_CURRENCY_IADDR",
  "primaryaddresses":["R_ADDR"],
  "minimumsignatures":1,
  "contentmultimap":{"iVDXF_KEY":["hex_data"]}
}]}
```

### List My Identities
```bash
{"method":"listidentities","params":[true, true, false]}
```

---

## Data (VDXF / contentmultimap)

### Get VDXF Key
```bash
{"method":"getvdxfid","params":["myid::agent.v1.name"]}
# Returns: {"vdxfid": "i...", ...}
```

### Encode Data to Hex
```bash
echo -n '"value"' | xxd -p | tr -d '\n'
```

### Decode Hex to Data
```bash
echo "HEX" | xxd -r -p
```

### Store Data On-Chain
Use `updateidentity` with `contentmultimap` (see above).

⚠️ Include ALL existing contentmultimap entries — update replaces everything.

---

## Payments

### Check Balance
```bash
{"method":"getbalance","params":[]}
{"method":"z_gettotalbalance","params":[]}
```

### Generate Address
```bash
{"method":"getnewaddress","params":["label"]}
```

### Send VRSCTEST
```bash
{"method":"sendcurrency","params":["fromid@",[{"address":"toid@","currency":"VRSCTEST","amount":5}]]}
# Returns: operation-id (opid), NOT a txid
```

### Track Send Operation
```bash
# sendcurrency returns an opid — use z_getoperationstatus to track it
{"method":"z_getoperationstatus","params":[["opid-from-sendcurrency"]]}
# When status is "success", the txid is in result.txid

# Or use z_getoperationresult to get result and remove from queue
{"method":"z_getoperationresult","params":[["opid-from-sendcurrency"]]}
```

### Send with Memo
```bash
{"method":"sendcurrency","params":["fromid@",[{"address":"toid@","currency":"VRSCTEST","amount":5,"memo":"job_001"}]]}
# Note: memos only work when sending to z-addresses
```

### Check Transaction
```bash
{"method":"gettransaction","params":["TXID"]}
```

### Check Received at Address
```bash
{"method":"getreceivedbyaddress","params":["R_ADDRESS", 1]}
# Second param = minimum confirmations
```

### List Recent Transactions
```bash
{"method":"listtransactions","params":["*", 20]}
```

---

## Signing & Verification

### Sign a Message
```bash
{"method":"signmessage","params":["yourid@","message text"]}
# Returns: {"hash":"hexhash", "signature":"base64sig"}
```

### Verify a Signature
```bash
{"method":"verifymessage","params":["signerid@","SIGNATURE","message text"]}
# Returns: true/false
```

### Sign Data with Encryption
```bash
{"method":"signdata","params":[{
  "address":"yourid@",
  "message":"plaintext message",
  "encrypttoaddress":"zs1RECIPIENT_ZADDR"
}]}
```

### Verify Signed Data
```bash
{"method":"verifysignature","params":[{
  "address":"signerid@",
  "datahash":"HASH",
  "signature":"SIGNATURE",
  "hashtype":"sha256"
}]}
# Returns: {"hash":"...", "signature":"..."} on success, RPC error on failure
```

---

## Encryption

### Create z-Address
```bash
{"method":"z_getnewaddress","params":[]}
```

### Get Viewing Keys
```bash
{"method":"z_getencryptionaddress","params":[{"address":"zs1..."}]}
# Returns: extendedviewingkey, incomingviewingkey, address
```

### Decrypt Data
```bash
{"method":"decryptdata","params":[{
  "datadescriptor":{"version":1,"flags":5,"objectdata":"HEX","epk":"HEX"},
  "ivk":"VIEWING_KEY"
}]}
# Returns: hex-encoded plaintext
```

---

## Chain Status

### Node Info
```bash
{"method":"getinfo","params":[]}
```

### Block Height
```bash
{"method":"getblockcount","params":[]}
```

### Blockchain Info
```bash
{"method":"getblockchaininfo","params":[]}
```

### Mempool
```bash
{"method":"getmempoolinfo","params":[]}
```

---

## Currency

### Get Currency Info
```bash
{"method":"getcurrency","params":["VRSC"]}
```

### List Currencies
```bash
{"method":"listcurrencies","params":[]}
```

### Estimate Conversion
```bash
{"method":"estimateconversion","params":[{"currency":"VRSCTEST","convertto":"OTHER","amount":10}]}
```

### Convert Currency
```bash
{"method":"sendcurrency","params":["yourid@",[{"address":"yourid@","currency":"VRSCTEST","convertto":"OTHER","amount":10}]]}
```

---

## Agent VDXF Key Reference

> **Note:** i-addresses below are derived from the VDXF key string. Replace `myid` with your own identity name — e.g., if your identity is `devplatform`, run `getvdxfid "devplatform::agent.v1.name"` to get your i-address. The `agent.v1.*` schema names are kept for interoperability — only the namespace prefix changes per deployer.

| Field | i-address |
|-------|-----------|
| `myid::agent.v1.version` | `i...` |
| `myid::agent.v1.type` | `i...` |
| `myid::agent.v1.name` | `i...` |
| `myid::agent.v1.description` | `i...` |
| `myid::agent.v1.capabilities` | `i...` |
| `myid::agent.v1.endpoints` | `i...` |
| `myid::agent.v1.protocols` | `i...` |
| `myid::agent.v1.owner` | `i...` |
| `myid::agent.v1.status` | `i...` |
| `myid::agent.v1.services` | `i...` |

---

## signmessage vs signdata

| | `signmessage` | `signdata` |
|---|---|---|
| **Use case** | Simple text signing | Advanced: encryption, v2 sigs, MMR proofs |
| **Input** | `["identity@", "message"]` | `[{"address":"id@", "message":"text", ...}]` |
| **Output** | Base64 signature | Hash + signature + optional encrypted data |
| **Verify with** | `verifymessage` | `verifysignature` (pass `datahash`) |
| **When to use** | Proving authorship, simple auth | Encrypted messages, cross-chain proofs |

**Rule of thumb:** Use `signmessage` for 90% of cases. Use `signdata` when you need encryption or MMR-based verification.

---

## Error Handling

Common RPC errors you'll encounter:

### Identity not found (error code: -5)
```
error code: -5
error message:
Identity not found
```
**Cause:** The name doesn't exist, is misspelled, or you used the wrong qualification (e.g., `alice@` instead of `alice.yourapp@`).

### Invalid identity or not in wallet (error code: -8)
```
error code: -8
error message:
Invalid identity or identity not in wallet
```
**Cause:** Trying to send from or sign with an identity your wallet doesn't control.

### Insufficient funds
```
error code: -6
error message:
Insufficient funds
```
**Cause:** Not enough balance to cover amount + fees.

**Tip:** Always check the exit code. Non-zero means an error occurred. Parse `error code` and `error message` from stderr.

---

## Decode All contentmultimap Fields

One-liner to decode every hex value in an identity's contentmultimap:

```bash
verus -testnet getidentity "name@" | jq -r \
  '.identity.contentmultimap | to_entries[] | .key as $k | .value[] | "\($k): \(. | @sh)"' \
  | while IFS=': ' read -r key hex; do
    echo "$key: $(echo "$hex" | tr -d "'" | xxd -r -p)"
  done
```

---

## See Also

- [Agent Bootstrap](./agent-bootstrap.md) — Setup from scratch
- [Agent Identity](./agent-identity.md) — Identity management
- [Agent Economy](./agent-economy.md) — Payments
- [Agent Messaging](./agent-messaging.md) — Encrypted comms
- [RPC API Overview](../developers/rpc-api-overview.md) — Full API guide

---

*Last updated: 2026-02-07*


--- PAGE: for-agents/agent-economy.md ---

# For Agents: Participating in the Verus Economy

> How to send, receive, and earn VRSC as an AI agent.

> **Placeholder convention:** Examples use placeholder names you should substitute with your own values.
> - `youragent@` — your agent's VerusID
> - `recipient@` — the destination identity for a payment
> - `myid::agent.v1.*` — VDXF keys under your namespace; keep `agent.v1.*` for interoperability, replace `myid` with your identity name
> - `i...` — placeholder for an i-address; derive real values with `getvdxfid`

---

## Receiving Payments

### To Your VerusID

Anyone can send VRSC to your identity name:

```bash
# Sender runs:
verus sendcurrency "*" '[{"address":"youragent@","currency":"VRSCTEST","amount":5}]'
```

### To a Specific Address

```bash
# Generate a fresh address per transaction (better for tracking)
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"getnewaddress","params":["payments"]}'
```

### Check Balance

```bash
# Total wallet balance
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"getbalance","params":[]}'

# Balance by address
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"z_gettotalbalance","params":[]}'
```

---

## Sending Payments

### Send VRSC

```bash
# Send to a VerusID
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"sendcurrency",
    "params":["youragent@", [{"address":"recipient@","currency":"VRSCTEST","amount":5}]]
  }'
# Returns: operation-id (opid) — use z_getoperationstatus to track, then get txid from result
```

### Send with Memo (for Job Tracking)

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"sendcurrency",
    "params":["youragent@", [{
      "address":"recipient@",
      "currency":"VRSCTEST",
      "amount":5,
      "memo":"job_20260207_001"
    }]]
  }'
```

### Verify a Payment Was Received

```bash
# Check transaction
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"gettransaction","params":["TXID"]}'
# Check: confirmations > 0 means it's mined
```

---

## Listing Services and Pricing

Store your service offerings in your identity's contentmultimap:

```bash
# Service listing format
SERVICES='[{"id":"code-review","name":"Code Review","price":{"amount":5,"currency":"VRSCTEST","unit":"per-review"}},{"id":"research","name":"Research","price":{"amount":10,"currency":"VRSCTEST","unit":"per-report"}}]'

# Encode to hex
SERVICES_HEX=$(echo -n "$SERVICES" | xxd -p | tr -d '\n')

# Resolve the VDXF key for your services field
# Replace "myid" with your own identity name
SERVICES_KEY=$(verus -testnet getvdxfid "myid::agent.v1.services" | jq -r '.vdxfid')

# Store on-chain
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d "{
    \"jsonrpc\":\"1.0\",\"id\":\"1\",\"method\":\"updateidentity\",
    \"params\":[{
      \"name\": \"youragent\",
      \"parent\": \"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq\",
      \"contentmultimap\": {
        \"$SERVICES_KEY\": [\"$SERVICES_HEX\"]
      }
    }]
  }"
```

---

## Job Flow (Agent-to-Agent Commerce)

### As a Seller

```
1. List services in contentmultimap
2. Receive job request (signed by buyer)
3. Verify buyer's signature
4. Accept job (sign acceptance)
5. Do the work
6. Deliver results (signed)
7. Receive payment
```

### As a Buyer

```
1. Look up agent's services via getidentity
2. Create and sign job request
3. Wait for acceptance
4. Pay (prepay or postpay per terms)
5. Receive delivery
6. Verify and acknowledge completion
```

### Sign a Job Message

```bash
# Create job request
JOB='{"type":"job_request","jobId":"jr_001","buyer":"you@","seller":"them@","service":"research","price":{"amount":10,"currency":"VRSCTEST"}}'

# Sign it
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d "{\"jsonrpc\":\"1.0\",\"id\":\"1\",\"method\":\"signmessage\",\"params\":[\"youragent@\",\"$JOB\"]}"

# Recipient verifies with verifymessage
```

---

## Currency Conversions

Verus has a built-in DEX. Convert between currencies:

```bash
# Estimate conversion
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"estimateconversion","params":[{"currency":"VRSCTEST","convertto":"OTHERCURRENCY","amount":10}]}'

# Execute conversion
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"sendcurrency",
    "params":["youragent@",[{"address":"youragent@","currency":"VRSCTEST","convertto":"OTHERCURRENCY","amount":10}]]
  }'
```

---

## Transaction Monitoring

### Watch for Incoming Payments

```python
import time

def monitor_payments(callback, poll_interval=15):
    seen = set()
    while True:
        txs = rpc("listtransactions", ["*", 50])
        for tx in txs:
            if tx["txid"] not in seen and tx["category"] == "receive":
                seen.add(tx["txid"])
                callback(tx)
        time.sleep(poll_interval)

def on_payment(tx):
    print(f"Received {tx['amount']} VRSC (confirmations: {tx['confirmations']})")
    if tx["confirmations"] >= 1:
        process_payment(tx)
```

### Confirm Specific Payment

```python
def is_payment_confirmed(txid, min_confirmations=1):
    tx = rpc("gettransaction", [txid])
    return tx["confirmations"] >= min_confirmations
```

---

## On-Chain Reputation

Store job completion records in your contentmultimap:

```bash
# After completing a job, update your on-chain stats
# Encode: {"completed": 5, "rating": 4.8}
STATS_HEX=$(echo -n '{"completed":5,"rating":4.8}' | xxd -p | tr -d '\n')

# Store under a reputation VDXF key
```

Other agents can verify:
1. Your job count and ratings (contentmultimap)
2. Payment transactions matching job IDs (on-chain)
3. Signed completion messages from buyers (verifiable)
4. Your identity age (block height of creation)

---

## Marketplace / Offers

Verus has a built-in decentralized marketplace for trading currencies, identities, and other on-chain assets:

### List Open Offers
```bash
# Get all open offers for a currency
{"method":"getoffers","params":["VRSC",true]}

# List open offers (params: unexpired, expired — both bools)
{"method":"listopenoffers","params":[true, false]}

# Get offers for a specific currency
{"method":"getoffers","params":["VRSCTEST"]}
```

### Make an Offer
```bash
# Offer to trade — e.g., sell 10 VRSCTEST for 50 OtherCurrency
# First param is fromaddress, second is the offer JSON object
{"method":"makeoffer","params":["youragent@", {
  "changeaddress":"youragent@",
  "offer":{"currency":"VRSCTEST","amount":10},
  "for":{"currency":"OtherCurrency","amount":50}
}]}
```

### Take an Offer
```bash
# Accept an existing offer — first param is fromaddress, txid goes INSIDE the JSON
{"method":"takeoffer","params":["youragent@", {
  "txid":"OFFER_TXID",
  "changeaddress":"youragent@",
  "deliver":{"currency":"VRSCTEST","amount":10},
  "accept":{"currency":"OtherCurrency","amount":50}
}]}
```

### Close an Offer
```bash
{"method":"closeoffers","params":[["OFFER_TXID"]]}
```

**Agent use case:** List your services as offers (e.g., offering "research hours" tokens for VRSC), or find other agents' service offers programmatically.

---

## See Also

- [Agent Bootstrap](./agent-bootstrap.md) — Initial setup
- [Agent Identity](./agent-identity.md) — Profile and data management
- [Agent Messaging](./agent-messaging.md) — Encrypted communication
- [CLI Reference](./agent-cli-reference.md) — Command quick reference

---

*Last updated: 2026-02-07*


--- PAGE: for-agents/agent-identity.md ---

# For Agents: Identity Management

> Create, update, and use your VerusID programmatically.

---

## Name Qualification — Getting It Right

VerusID names must be properly qualified. The `@` suffix is always required, and the parent namespace matters:

- **`myid@`** — Top-level identity on the current chain
- **`alice.yourapp@`** — SubID: "alice" under the "yourapp" namespace  
- **`myid.VRSCTEST@`** — Fully qualified with chain suffix (equivalent to `myid@` on testnet)

⚠️ **`alice@` ≠ `alice.yourapp@`** — The first looks for a top-level identity "alice" (which may not exist). The second correctly references the SubID. Always use the fully qualified name when working with SubIDs.

---

## Your Identity Is Your Foundation

A VerusID gives you:
- **A name** — `youragent@` instead of a hex address
- **On-chain storage** — contentmultimap for profiles, keys, service listings
- **Cryptographic signing** — Prove you authored messages or data
- **Payment address** — Receive VRSC to your name
- **Key rotation** — Update keys without losing your identity

---

## Registration

See [Agent Bootstrap](./agent-bootstrap.md) for initial registration. Summary:

```bash
# 1. Commit
verus -testnet registernamecommitment "agentname" "R_ADDRESS"
# 2. Wait 1 block
# 3. Register
verus -testnet registeridentity '{ "txid":"...", "namereservation":{...}, "identity":{...} }'
```

---

## Reading Your Identity

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"1","method":"getidentity","params":["agentname.VRSCTEST@"]}'
```

Key fields in response:

| Field | Use |
|-------|-----|
| `identityaddress` | Your permanent i-address (never changes) |
| `primaryaddresses` | Current control addresses (can be rotated) |
| `contentmultimap` | Your on-chain data store |
| `revocationauthority` | Who can revoke this ID |
| `recoveryauthority` | Who can recover this ID |
| `flags` | Status bits (check for revocation) |

---

## Storing Data (contentmultimap)

### VDXF Keys

Create deterministic keys from human-readable names:

```bash
# Get the i-address for a namespace key
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"getvdxfid","params":["vrsc::system.agent.profile"]}'
# Returns: {"vdxfid": "iXXXXXXXX...", ...}
```

### Encode Data

All contentmultimap values are hex-encoded:

```bash
# String to hex
echo -n '"My Agent Description"' | xxd -p | tr -d '\n'
# → 224d7920416765...22

# JSON to hex
echo -n '{"version":"1","capabilities":["research"]}' | xxd -p | tr -d '\n'
```

### Write Data

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"updateidentity",
    "params":[{
      "name": "agentname",
      "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "contentmultimap": {
        "iVDXF_KEY_1": ["hex_data_1"],
        "iVDXF_KEY_2": ["hex_data_2"]
      }
    }]
  }'
```

⚠️ **Critical:** `updateidentity` replaces the ENTIRE contentmultimap. Always include all existing entries plus your new ones.

### Read Data

```bash
# Get identity → extract contentmultimap → decode hex
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"getidentity","params":["agentname.VRSCTEST@"]}' \
  | jq -r '.result.identity.contentmultimap'
```

Decode a hex value:
```bash
echo "HEX_VALUE" | xxd -r -p
# → "decoded value"
```

---

## Agent Profile Schema

Use the `myid::agent.v1.*` VDXF namespace for interoperability. The `agent.v1.*` field names are a convention — you can use any namespace prefix (e.g., `yourapp::agent.v1.*`). Run `getvdxfid` with your chosen key string to get the corresponding i-address.

> **Placeholder note:** i-addresses below are examples only. Run `getvdxfid "yourprefix::agent.v1.fieldname"` to obtain your actual i-addresses.

| Field | VDXF Key | i-address |
|-------|----------|-----------|
| version | `myid::agent.v1.version` | `i...` |
| type | `myid::agent.v1.type` | `i...` |
| name | `myid::agent.v1.name` | `i...` |
| description | `myid::agent.v1.description` | `i...` |
| capabilities | `myid::agent.v1.capabilities` | `i...` |
| protocols | `myid::agent.v1.protocols` | `i...` |
| status | `myid::agent.v1.status` | `i...` |
| services | `myid::agent.v1.services` | `i...` |

### Register as an Agent

```bash
# First, resolve your VDXF keys
VERSION_KEY=$(verus -testnet getvdxfid "myid::agent.v1.version" | jq -r '.vdxfid')
TYPE_KEY=$(verus -testnet getvdxfid "myid::agent.v1.type" | jq -r '.vdxfid')
NAME_KEY=$(verus -testnet getvdxfid "myid::agent.v1.name" | jq -r '.vdxfid')
STATUS_KEY=$(verus -testnet getvdxfid "myid::agent.v1.status" | jq -r '.vdxfid')

# Encode each field
VERSION_HEX=$(echo -n '"1"' | xxd -p | tr -d '\n')
TYPE_HEX=$(echo -n '"autonomous"' | xxd -p | tr -d '\n')
NAME_HEX=$(echo -n '"MyAgent"' | xxd -p | tr -d '\n')
STATUS_HEX=$(echo -n '"active"' | xxd -p | tr -d '\n')

# Update identity with agent profile
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d "{
    \"jsonrpc\":\"1.0\",\"id\":\"1\",\"method\":\"updateidentity\",
    \"params\":[{
      \"name\": \"agentname\",
      \"parent\": \"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq\",
      \"contentmultimap\": {
        \"$VERSION_KEY\": [\"$VERSION_HEX\"],
        \"$TYPE_KEY\": [\"$TYPE_HEX\"],
        \"$NAME_KEY\": [\"$NAME_HEX\"],
        \"$STATUS_KEY\": [\"$STATUS_HEX\"]
      }
    }]
  }"
```

---

## Signing and Verification

### Sign a Message

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"signmessage","params":["agentname@","message to sign"]}'
# Returns: {"hash":"hexhash", "signature":"base64sig"}
```

### Verify a Signature

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"verifymessage","params":["agentname@","SIGNATURE","message to sign"]}'
# Returns: true/false
```

### Use Cases
- **Prove authorship** of data or messages
- **Authenticate** to other agents or services
- **Non-repudiation** — signature is tied to your identity and block height

---

## Key Rotation

If keys are compromised, rotate without losing your identity:

```bash
# Generate new address
NEW_ADDR=$(curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"getnewaddress","params":[]}' | jq -r '.result')

# Update primary address
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d "{
    \"jsonrpc\":\"1.0\",\"id\":\"1\",\"method\":\"updateidentity\",
    \"params\":[{
      \"name\": \"agentname\",
      \"parent\": \"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq\",
      \"primaryaddresses\": [\"$NEW_ADDR\"],
      \"minimumsignatures\": 1
    }]
  }"
```

Your i-address stays the same. Your name stays the same. Only the controlling keys change.

---

## See Also

- [Agent Bootstrap](./agent-bootstrap.md) — Initial setup
- [Agent Economy](./agent-economy.md) — Payments and services
- [Agent Messaging](./agent-messaging.md) — Encrypted communication
- [CLI Reference](./agent-cli-reference.md) — Command quick reference
- [Identity System](../concepts/identity-system.md) — Deep dive on VerusID

---

*Last updated: 2026-02-07*


--- PAGE: for-agents/agent-messaging.md ---

# For Agents: Encrypted Messaging

> Send and receive encrypted, signed messages using Verus cryptographic primitives.

---

## Overview

Verus provides end-to-end encrypted messaging using:
- **VerusID** for sender authentication (signing)
- **z-addresses** for encryption (recipient's shielded address)
- **VDXF keys** for on-chain message storage (optional)

```
Sender (VerusID)  ──sign + encrypt──▶  Encrypted blob  ──deliver──▶  Recipient (z-addr)
                                                                          │
                                                                    decrypt with ivk
                                                                          │
                                                                    verify signature
```

---

## Setup: Create a z-Address

Each agent needs a z-address for receiving encrypted messages:

```bash
# Create shielded address
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"z_getnewaddress","params":[]}'
# Returns: "zs1..."

# Get your viewing keys (needed for decryption)
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{"jsonrpc":"1.0","id":"1","method":"z_getencryptionaddress","params":[{"address":"zs1YOUR_ADDRESS"}]}'
# Returns: { "extendedviewingkey": "...", "incomingviewingkey": "...", "address": "zs1..." }
```

**Store your z-address** in your identity's contentmultimap so other agents can find it. Publish the z-address (it's safe — only you have the viewing key).

---

## Sending an Encrypted Message

### Step 1: Create Message Envelope

```json
{
  "version": "1.0",
  "type": "message",
  "from": "sender.VRSCTEST@",
  "to": "recipient.VRSCTEST@",
  "timestamp": 1770336000,
  "body": "Hello from Agent"
}
```

### Step 2: Sign and Encrypt

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"signdata",
    "params":[{
      "address": "sender.VRSCTEST@",
      "message": "{\"version\":\"1.0\",\"type\":\"message\",\"from\":\"sender.VRSCTEST@\",\"to\":\"recipient.VRSCTEST@\",\"body\":\"Hello from Agent\"}",
      "encrypttoaddress": "zs1RECIPIENT_Z_ADDRESS"
    }]
  }'
```

**Response contains:**

| Field | Use |
|-------|-----|
| `mmrdescriptor_encrypted.datadescriptors[0]` | Encrypted blob (send to recipient) |
| `signature` | Proof of sender identity |
| `hash` | Content fingerprint |
| `signaturedata_ssk` | Shared secret key (for selective disclosure) |

### Step 3: Deliver

**Option A: Off-chain** — Send the encrypted blob via any channel (HTTP, WebSocket, file transfer). Recipient decrypts locally.

**Option B: On-chain** — Store in recipient's contentmultimap (requires cooperation or shared namespace):

```bash
# Encode the encrypted datadescriptor to hex
ENCRYPTED_HEX=$(echo -n '{"version":1,"flags":5,"objectdata":"...","epk":"..."}' | xxd -p | tr -d '\n')

# Store under a messaging VDXF key
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d "{
    \"jsonrpc\":\"1.0\",\"id\":\"1\",\"method\":\"updateidentity\",
    \"params\":[{
      \"name\": \"recipient\",
      \"parent\": \"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq\",
      \"contentmultimap\": {
        \"MESSAGE_VDXF_KEY\": [\"$ENCRYPTED_HEX\"]
      }
    }]
  }"
```

---

## Receiving and Decrypting

### Step 1: Get Encrypted Blob

From on-chain (contentmultimap) or off-chain delivery.

### Step 2: Decrypt

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"decryptdata",
    "params":[{
      "datadescriptor": {
        "version": 1,
        "flags": 5,
        "objectdata": "encrypted_hex_blob...",
        "epk": "ephemeral_public_key..."
      },
      "ivk": "your_incoming_viewing_key"
    }]
  }'
```

**Returns:** Hex-encoded plaintext. Decode:
```bash
echo "HEX_OUTPUT" | xxd -r -p
# → {"version":"1.0","type":"message","from":"sender@","body":"Hello from Agent"}
```

### Step 3: Verify Sender

```bash
curl -s -u $RPC_USER:$RPC_PASS http://127.0.0.1:18843 \
  -d '{
    "jsonrpc":"1.0","id":"1","method":"verifysignature",
    "params":[{
      "address": "sender.VRSCTEST@",
      "datahash": "hash_from_signdata",
      "signature": "signature_from_signdata",
      "hashtype": "sha256"
    }]
  }'
# Returns: {"hash":"hexhash", "signature":"base64sig"}
# If verification fails, an RPC error is returned instead
```

---

## Message Types

### Standard Message

```json
{"version": "1.0", "type": "message", "from": "a@", "to": "b@", "body": "text", "timestamp": 0}
```

### Job Request

```json
{"version": "1.0", "type": "job_request", "jobId": "jr_001", "buyer": "a@", "seller": "b@", "service": "research", "price": {"amount": 10, "currency": "VRSC"}}
```

### System Message

```json
{"version": "1.0", "type": "system", "action": "key_rotation", "newZaddr": "zs1..."}
```

---

## Selective Disclosure (SSK)

The `signaturedata_ssk` from `signdata` is a per-message shared secret key. You can give this key to a third party to let them decrypt ONE specific message without giving them access to all your messages.

**Use case:** Arbitration — share SSK with a mediator so they can read the disputed message.

---

## Security Properties

| Property | How |
|----------|-----|
| **Confidentiality** | z-address encryption (only recipient can decrypt) |
| **Authenticity** | VerusID signature (proves sender) |
| **Integrity** | SHA256 hash in signature (tamper detection) |
| **Non-repudiation** | Signature tied to block height (timestamped) |
| **Selective disclosure** | SSK per-message keys |

---

## VDXF Keys for Messaging

```bash
# Useful namespace keys
getvdxfid "vrsctest::message.inbox"
getvdxfid "vrsctest::message.outbox"
getvdxfid "vrsctest::message.thread"
```

---

## See Also

- [Agent Identity](./agent-identity.md) — Managing your on-chain profile
- [Agent Economy](./agent-economy.md) — Payments and commerce
- [CLI Reference](./agent-cli-reference.md) — Command quick reference

---

*Last updated: 2026-02-07*


--- PAGE: getting-started/first-steps.md ---

# First Steps with Verus

You've installed Verus — now let's get it running. This guide covers starting the daemon, syncing the blockchain, and basic configuration.

## Starting the Daemon

The Verus daemon (`verusd`) is the core software that connects to the network and maintains your copy of the blockchain.

```bash
# From your verus-cli directory — FIRST TIME (uses bootstrap for fast sync)
./verusd -bootstrap
```

On first launch, `verusd` will automatically:
1. Create the data directory (`~/.komodo/VRSC/` on Linux, `~/Library/Application Support/Komodo/VRSC/` on macOS, `%AppData%\Komodo\VRSC\` on Windows)
2. Generate a default `VRSC.conf` with random RPC credentials
3. Download a bootstrap snapshot and sync the blockchain

> ⚠️ **You do NOT need to manually create the data directory or config file** — `verusd` creates them automatically on first run.

> 💡 **Why `-bootstrap`?** Without it, first-time sync can take **~3 days**. With `-bootstrap`, you'll be synced in **under 3 hours**.

For **testnet**, use:
```bash
./verusd -testnet -bootstrap
```

## Checking Sync Status

Your node needs to download the entire blockchain before it's fully operational. Check progress with:

```bash
./verus getinfo
```

Key fields to watch:

| Field | Meaning |
|-------|---------|
| `blocks` | Blocks your node has downloaded |
| `longestchain` | Total blocks in the network |
| `connections` | Number of peer connections |

> When `blocks` equals `longestchain`, your node is fully synchronized.

For more detailed info:

```bash
./verus getblockchaininfo
```

This shows chain name, difficulty, verification progress, and consensus parameters.

### How Long Does Sync Take?

| Method | Approximate Time |
|--------|-----------------|
| `./verusd -bootstrap` (recommended for first time) | **Under 3 hours** |
| `./verusd` (no bootstrap, syncing from peers) | **~3 days** |
| `./verusd -fastload` (after clean shutdown) | **Minutes** |

**Always use `-bootstrap` for your first sync.** For subsequent starts after a clean shutdown with `verus stop`, use `-fastload` instead (see below).

## VRSC.conf Basics

The configuration file controls how your node operates. It's located at:

- **Linux**: `~/.komodo/VRSC/VRSC.conf`
- **macOS**: `~/Library/Application Support/Komodo/VRSC/VRSC.conf`
- **Windows**: `%AppData%\Komodo\VRSC\VRSC.conf`

A default config is created on first launch. Key settings:

```ini
# RPC credentials (auto-generated, keep secret)
rpcuser=your_random_username
rpcpassword=your_random_password

# RPC port (default: 27486)
rpcport=27486

# P2P port (default: 27485)
port=27485

# Optional: add specific peers
addnode=seeds.verus.io

# Optional: enable mining or staking
# mint=1           # Enable staking
# gen=1            # Enable mining
# genproclimit=2   # Number of mining threads
```

> 🔒 **Security**: Your `rpcuser` and `rpcpassword` control access to your node. Never share them. The defaults are random strings, which is good — leave them as-is unless you have a reason to change them.

### Common Configuration Options

| Setting | Default | Description |
|---------|---------|-------------|
| `rpcuser` | (random) | Username for RPC authentication |
| `rpcpassword` | (random) | Password for RPC authentication |
| `rpcport` | 27486 | Port for RPC connections |
| `port` | 27485 | Port for P2P network connections |
| `rpcallowip` | 127.0.0.1 | IPs allowed to connect via RPC |
| `txindex` | 1 | Keep full transaction index (recommended) |
| `mint` | 0 | Enable staking (1 = on) |
| `gen` | 0 | Enable mining (1 = on) |

After editing `VRSC.conf`, restart the daemon for changes to take effect.

## Stopping the Daemon Safely

Always shut down gracefully:

```bash
# Mainnet
./verus stop

# Testnet
./verus -testnet stop
```

This tells the daemon to finish what it's doing, save state, and exit cleanly. **Do not kill the process** (`kill -9`, closing the terminal, etc.) — this can corrupt the blockchain database.

You can verify it stopped by checking:

```bash
./verus getinfo
# Should show: error: couldn't connect to server
```

### Restarting After Clean Shutdown

If you shut down properly with `verus stop`, you can restart much faster using `-fastload`:

```bash
# Mainnet
./verusd -fastload

# Testnet
./verusd -testnet -fastload
```

The `-fastload` flag skips full chain verification since the shutdown was clean. **Only use `-bootstrap` for first-time sync or if your data is corrupted.**

## Quick Reference

| Task | Command |
|------|---------|
| Start daemon (first time) | `./verusd -bootstrap` |
| Start daemon (after clean stop) | `./verusd -fastload` |
| Check sync status | `./verus getinfo` |
| Detailed chain info | `./verus getblockchaininfo` |
| Stop daemon | `./verus stop` |
| View help | `./verus help` |

## Next Steps

- [Wallet Setup](wallet-setup.md) — Create addresses and manage your VRSC
- [Key Concepts](../introduction/key-concepts.md) — Understand VerusID, staking, and more
- [Troubleshooting: Sync Issues](../troubleshooting/sync-issues.md) — If you're having trouble syncing



--- PAGE: getting-started/installation.md ---

# Installing Verus

This guide walks you through downloading and installing Verus on your computer. No prior experience needed.

## Choose Your Software

Verus offers two options:

| Option | Best For | Description |
|--------|----------|-------------|
| **Verus Desktop** | Most users | Graphical wallet with mining, staking, and VerusID management built in |
| **Verus CLI** | Advanced users, servers | Command-line tools (`verusd`, `verus`) for headless operation |

## System Requirements

- **OS**: Linux (Ubuntu 18.04+), macOS (10.14+), Windows (10+)
- **RAM**: 4 GB minimum, 8 GB recommended
- **Disk**: 15+ GB free (blockchain grows over time)
- **CPU**: Any modern x86_64 processor; ARM64 supported on Linux
- **Network**: Broadband internet for initial sync

## Download

### Official Sources

- **Website**: [https://verus.io/wallet](https://verus.io/wallet)
- **GitHub Releases**: [https://github.com/VerusCoin/VerusCoin/releases](https://github.com/VerusCoin/VerusCoin/releases)

> ⚠️ **Only download from official sources.** Never trust links from unofficial channels.

### Verus Desktop

Download from [verus.io/wallet](https://verus.io/wallet) — installers available for Linux, macOS, and Windows.

### Verus CLI

Download the appropriate archive from [GitHub Releases](https://github.com/VerusCoin/VerusCoin/releases):

| Platform | Filename Pattern |
|----------|-----------------|
| Linux x86_64 | `Verus-CLI-Linux-v*-amd64.tar.gz` |
| Linux ARM64 | `Verus-CLI-Linux-v*-arm64.tar.gz` |
| macOS | `Verus-CLI-macOS-v*.tar.gz` |
| Windows | `Verus-CLI-Windows-v*.zip` |

## Install — Linux

**Dependencies (if on a fresh system):**
```bash
sudo apt-get install libcurl3 g++-multilib    # Ubuntu/Debian
```

```bash
# Extract the archive
tar -xzf Verus-CLI-Linux-v*.tar.gz

# Move into the extracted directory
cd verus-cli

# Make binaries executable (usually already set)
chmod +x verusd verus fetch-params
```

### Zcash Parameters (Auto-Downloaded)

The daemon automatically downloads the required Zcash cryptographic parameters (~1.7 GB to `~/.zcash-params/`) on first run. The official docs recommend running `fetch-params` before first start, but the daemon will handle it if you skip this step:

```bash
./fetch-params   # Recommended before first start; daemon auto-downloads if missing
```

## Install — macOS

```bash
tar -xzf Verus-CLI-macOS-v*.tar.gz
cd verus-cli
```

If macOS blocks execution, go to **System Preferences → Security & Privacy** and click **Allow**.

## Install — Windows

1. Extract the `.zip` file to a folder (e.g., `C:\verus-cli`)
2. Open **Command Prompt** or **PowerShell**
3. Navigate to the folder: `cd C:\verus-cli`

> Zcash parameters are downloaded automatically on first daemon start. You can optionally run `fetch-params.bat` to pre-download them.

## Install — ARM (Linux)

ARM64 builds (Raspberry Pi 4, etc.) follow the same Linux steps — just download the `arm64` archive:

```bash
tar -xzf Verus-CLI-Linux-v*-arm64.tar.gz
cd verus-cli
```

> 💡 **Tip**: ARM devices with limited RAM may struggle during initial sync. Consider using a [bootstrap](first-steps.md) to speed things up.

## Verifying Signatures

Each release includes a signature file. To verify:

```bash
# Import the Verus signing key (if you haven't already)
gpg --import verus-signing-key.asc

# Verify the archive
gpg --verify Verus-CLI-Linux-v*-amd64.tar.gz.sig Verus-CLI-Linux-v*-amd64.tar.gz
```

You should see `Good signature from "Verus Coin"`. If verification fails, **do not use the download**.

SHA256 checksums are also published with each release for additional verification.

## What's Included (CLI)

The CLI package contains these key binaries:

| Binary | Purpose |
|--------|---------|
| `verusd` | The Verus daemon — runs the blockchain node |
| `verus` | CLI client — sends commands to `verusd` |
| `fetch-params` | Downloads required Zcash cryptographic parameters |
| `fetch-bootstrap` | Downloads blockchain bootstrap for fast initial sync |

## Next Steps

- [First Steps](first-steps.md) — Start the daemon and sync the blockchain
- [Wallet Setup](wallet-setup.md) — Create your first address and receive VRSC
- [Key Concepts](../introduction/key-concepts.md) — Understand what makes Verus unique


--- PAGE: getting-started/wallet-setup.md ---

# Wallet Setup

Your Verus node includes a built-in wallet. This guide covers creating addresses, receiving VRSC, checking balances, and keeping your funds safe.

> **Prerequisites**: Your daemon should be running and synced. See [First Steps](first-steps.md) if you haven't done that yet.

## Creating Your First Address

Generate a new transparent address:

```bash
./verus getnewaddress
```

This returns an address starting with **R** (e.g., `RKjh38dkj2...`). This is your transparent address — like a bank account number you can share with others.

### Address Types

| Prefix | Type | Privacy |
|--------|------|---------|
| `R...` | Transparent | Visible on the blockchain (like Bitcoin) |
| `zs...` | Shielded (Sapling) | Encrypted — amounts and memo hidden |
| `i...` | VerusID | Human-readable identity address |

For now, a transparent `R` address is all you need to get started. See [Privacy & Shielded Transactions](../concepts/privacy-shielded-tx.md) to learn about shielded addresses.

## Getting Your First VRSC

You can obtain VRSC by:

1. **Receiving from someone** — Share your `R...` address
2. **Mining** — See [How to Mine VRSC](../how-to/mine-vrsc.md)
3. **Staking** — See [How to Stake VRSC](../how-to/stake-vrsc.md)
4. **Exchanges** — Purchase on supported exchanges (see [verus.io](https://verus.io))
5. **Community** — The Verus Discord community sometimes runs giveaways

## Checking Your Balance

### Simple Balance

```bash
./verus getbalance
```

Returns your total confirmed transparent balance.

### Detailed Balance

```bash
./verus z_gettotalbalance
```

Shows transparent, shielded (private), and total balances:

```json
{
  "transparent": "100.00000000",
  "private": "50.00000000",
  "total": "150.00000000"
}
```

### List Transactions

```bash
./verus listtransactions
```

Shows your recent transaction history with amounts, confirmations, and addresses.

## Backing Up Your Wallet

Your wallet file contains your private keys. **If you lose it, you lose your funds.** Back it up!

### Wallet File Location

- **Linux**: `~/.komodo/VRSC/wallet.dat`
- **macOS**: `~/Library/Application Support/Komodo/VRSC/wallet.dat`
- **Windows**: `%AppData%\Komodo\VRSC\wallet.dat`

### How to Back Up

1. **Stop the daemon** for a clean backup:
   ```bash
   ./verus stop
   ```

2. **Copy `wallet.dat`** to a safe location (USB drive, encrypted cloud storage, etc.):
   ```bash
   cp ~/.komodo/VRSC/wallet.dat ~/verus-wallet-backup.dat
   ```

3. **Restart the daemon**:
   ```bash
   ./verusd -fastload
   ```

### Backup Best Practices

- ✅ Back up after creating new addresses
- ✅ Store copies in multiple physical locations
- ✅ Use encrypted storage
- ❌ Don't email wallet files
- ❌ Don't store backups on public cloud without encryption

### Export Private Keys (Alternative)

You can also export individual private keys:

```bash
# For a transparent address
./verus dumpprivkey "RYourAddressHere"

# For a shielded address
./verus z_exportkey "zsYourAddressHere"
```

> 🔒 **Private keys = full control of funds.** Anyone with your private key can spend your coins. Store them as securely as your wallet file.

## Encrypting Your Wallet

Add password protection to your wallet:

```bash
./verus encryptwallet "your-strong-passphrase"
```

After encryption:
- The daemon will shut down — restart it
- You must unlock the wallet to send funds: `./verus walletpassphrase "passphrase" timeout_seconds`
- Staking while encrypted requires: `./verus walletpassphrase "passphrase" 99999999 true`

## Understanding Transparent vs Shielded

| Feature | Transparent (`R...`) | Shielded (`zs...`) |
|---------|---------------------|-------------------|
| Balances | Visible on-chain | Hidden |
| Amounts | Visible | Hidden |
| Sender/Receiver | Visible | Hidden |
| Use case | General transactions | Privacy-sensitive transactions |
| Speed | Instant | Slightly slower |

Most users start with transparent addresses. When you need privacy, you can move funds to a shielded address. See [Send a Private Transaction](../how-to/send-private-transaction.md) for a step-by-step guide.

## Next Steps

- [Key Concepts](../introduction/key-concepts.md) — Understand the full Verus ecosystem
- [Send a Private Transaction](../how-to/send-private-transaction.md) — Use shielded addresses
- [Register a VerusID](../how-to/create-verusid.md) — Get a human-readable identity
- [Command Reference: Wallet](../command-reference/wallet.md) — All wallet-related commands


--- PAGE: how-to/backup-and-restore-wallet.md ---

# How To: Backup and Restore Your Wallet

> Protect your funds and identities with proper wallet backups

---

## Prerequisites

- Verus CLI installed with `verusd` running
- Access to the Verus data directory

---

## Method 1: backupwallet (Quick Backup)

Creates a copy of the `wallet.dat` file.

### Step 1: Run the Backup

```bash
verus backupwallet "mybackup20260207"
```

> ⚠️ **The filename must be alphanumeric only** — no spaces, dots, slashes, or special characters. `mybackup20260207` works. `my-backup.dat` does **not**.

### Step 2: Locate the Backup

The backup is saved to the directory configured via the `-exportdir` startup option. If `-exportdir` is not set, it defaults to the Verus data directory:
- **Linux:** `~/.komodo/VRSC/mybackup20260207`
- **macOS:** `~/Library/Application Support/Komodo/VRSC/mybackup20260207`
- **Windows:** `%APPDATA%\Komodo\VRSC\mybackup20260207`

For testnet, replace `VRSC` with `vrsctest`.

> 💡 **Tip:** Set `-exportdir=/path/to/backups` in your config or startup flags to control where backups are saved.

### Step 3: Move to Safe Storage

Copy the backup file to a secure location:

```bash
cp ~/.komodo/VRSC/mybackup20260207 /path/to/secure/storage/
```

---

## Method 2: dumpwallet (Full Export)

Exports all private keys and addresses to a human-readable text file. This is the most complete backup method.

### Step 1: Export

```bash
verus dumpwallet "fullexport20260207"
```

> ⚠️ Same naming rules — **alphanumeric only**.

### Step 2: Secure the Export

The exported file contains **all private keys in plain text**. Anyone with this file has full access to your funds.

```bash
# Move to secure location
cp ~/.komodo/VRSC/fullexport20260207 /path/to/secure/storage/

# Optionally encrypt
gpg -c /path/to/secure/storage/fullexport20260207
# Enter a strong passphrase when prompted

# Delete the unencrypted version
rm /path/to/secure/storage/fullexport20260207
```

### What's in the Export

The dump file contains:
- All private keys (WIF format)
- All addresses (transparent and shielded)
- Key metadata (creation time, labels)
- All private keys for transparent and shielded addresses

---

## Restoring from Backup

### Restore wallet.dat (from backupwallet)

1. **Stop the daemon:**
   ```bash
   verus stop
   ```

2. **Replace the wallet file:**
   ```bash
   # Backup the current wallet first!
   cp ~/.komodo/VRSC/wallet.dat ~/.komodo/VRSC/wallet.dat.old

   # Copy your backup in
   cp /path/to/secure/storage/mybackup20260207 ~/.komodo/VRSC/wallet.dat
   ```

3. **Restart the daemon:**
   ```bash
   verusd -fastload
   ```

4. **Rescan the blockchain** (to find all transactions):
   ```bash
   verus stop
   verusd -rescan
   ```

### Restore from dumpwallet (using importwallet)

1. **Copy the export file** to the Verus data directory:
   ```bash
   cp /path/to/secure/storage/fullexport20260207 ~/.komodo/VRSC/
   ```

2. **Import:**
   ```bash
   verus importwallet "fullexport20260207"
   ```

   > ⚠️ Same alphanumeric filename rules apply.

3. **Wait for rescan.** The import triggers a blockchain rescan to find all transactions associated with the imported keys. This can take a while depending on chain length.

---

## Backing Up Individual Keys

For specific addresses or identities:

### Export a Single Private Key

```bash
verus dumpprivkey "RYourAddress"
```

Save the output (WIF-format private key) securely.

### Import a Single Private Key

```bash
verus importprivkey "YourPrivateKeyWIF" "" true
```

The third parameter triggers a rescan.

---

## Best Practices

### Backup Frequency

| Event | Action |
|---|---|
| After creating a new identity | Backup immediately |
| After receiving funds to a new address | Backup soon |
| After any `getnewaddress` call | Backup (new key generated) |
| Weekly (routine) | Scheduled backup |
| Before any wallet upgrade | Backup beforehand |

### Storage

1. **Multiple copies** — Keep backups in at least 2 physically separate locations
2. **Encrypt** — Always encrypt backup files with a strong passphrase (GPG, VeraCrypt, etc.)
3. **Offline storage** — Store at least one copy on an air-gapped device or physical media (USB drive)
4. **Test restores** — Periodically verify your backups work by restoring to a test environment
5. **Label clearly** — Include the date and chain (mainnet vs testnet) in the filename

### Security

- **Never share** wallet files or private key exports
- **Never store unencrypted** backups on cloud storage (Dropbox, Google Drive, etc.)
- **Delete intermediate files** — If you decrypt a backup for restoration, delete the decrypted copy after
- **Secure the passphrase** — Store your encryption passphrase separately from the backup

---

## Common Errors

| Error | Cause | Solution |
|---|---|---|
| `Error: Filename must be alphanumeric` | Special characters in filename | Use only letters and numbers: `backup20260207` |
| `Error: wallet.dat not found` | Wrong data directory | Check your OS-specific path (see above) |
| `Error importing wallet` | File not in data directory | Copy the file to `~/.komodo/VRSC/` first |
| Missing transactions after restore | Rescan needed | Restart with `verusd -rescan` |
| Missing z-address funds | z-keys not in backup | Use `dumpwallet` (not `backupwallet`) for complete export including z-keys |

---

## Quick Reference

```bash
# Quick backup
verus backupwallet "backup20260207"

# Full export (all keys)
verus dumpwallet "export20260207"

# Import full export
verus importwallet "export20260207"

# Export single key
verus dumpprivkey "RAddress"

# Import single key
verus importprivkey "WIFkey" "" true

# Rescan blockchain after restore
verusd -rescan
```

---

## Related

- [VerusID Concepts](../concepts/identity-system.md) — Understanding identities you're backing up
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Moving funds after restoration

---

*As of Verus v1.2.x.*


--- PAGE: how-to/bridge-from-ethereum.md ---

# How To: Bridge from Ethereum

> Transfer ETH and ERC-20 tokens to Verus, and send VRSC back to Ethereum

---

## Prerequisites

- **Ethereum wallet** (MetaMask or similar) with ETH for gas + the amount to bridge
- **Verus wallet** — either Verus Desktop or Verus CLI (`verusd`) running and synced
- A **Verus destination address** (R-address) or **VerusID** to receive funds
- For CLI operations: Verus daemon running and synced with Bridge.vETH active

---

## Part 1: Ethereum → Verus (Web UI)

The simplest method. No coding required.

### Step 1: Open the Bridge Interface

Go to [eth.verusbridge.io](https://eth.verusbridge.io/)

### Step 2: Connect Your Ethereum Wallet

1. Click **Connect Wallet**
2. Select MetaMask (or your wallet)
3. Approve the connection

### Step 3: Select the Token to Bridge

Choose from:
- **ETH** — arrives as **vETH** on Verus
- **DAI** — arrives as **DAI.vETH** on Verus
- **MKR** — arrives as **MKR.vETH** on Verus

### Step 4: Enter Your Verus Destination

Enter your Verus R-address or VerusID (e.g., `myidentity@`).

> ⚠️ **Double-check the address.** Cross-chain transfers cannot be reversed.

### Step 5: Enter the Amount

Specify how much to bridge. The UI shows estimated fees and output.

### Step 6: Confirm the Transaction

1. Review the details
2. Click **Send**
3. Confirm the transaction in MetaMask
4. Pay the gas fee

### Step 7: Wait for Completion

| Stage | Time |
|---|---|
| Ethereum confirmation | ~15 minutes |
| Bridge notarization | ~10-20 minutes |
| Verus import | ~1-2 minutes |
| **Total** | **~30-60 minutes** |

### Step 8: Verify on Verus

```bash
# Check your balance
verus getbalance

# Check specific currency balance (vETH, DAI.vETH, etc.)
verus getcurrencybalance '*'
```

---

## Part 2: Verus → Ethereum (CLI)

Send VRSC or other Verus-side currencies back to Ethereum.

### Step 1: Verify Bridge Status

```bash
verus getcurrency "Bridge.vETH"
```

Confirm the bridge is active and has reserves.

### Step 2: Send to Ethereum

Use [sendcurrency](../command-reference/multichain.md#sendcurrency) with `exportto`:

```bash
# Send VRSC to your Ethereum address
verus sendcurrency '*' '[{
  "address": "0xYourEthereumAddress",
  "amount": 10,
  "currency": "VRSC",
  "exportto": "vETH",
  "feecurrency": "veth"
}]'
```

```bash
# Send vETH back to Ethereum as ETH
verus sendcurrency '*' '[{
  "address": "0xYourEthereumAddress",
  "amount": 0.5,
  "currency": "vETH",
  "exportto": "vETH",
  "feecurrency": "veth"
}]'
```

### Step 3: Wait for Completion

Same timing as ETH → Verus: approximately 30-60 minutes (~1 hour typical) for notarization and import on the Ethereum side.

### Step 4: Verify on Ethereum

Check your Ethereum wallet or use a block explorer (Etherscan) to confirm receipt.

---

## Part 3: Bridge + Convert in One Step

You can bridge **and** convert simultaneously. For example, convert vETH to VRSC through the Bridge.vETH basket:

```bash
# Convert vETH → VRSC through Bridge.vETH
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 0.5,
  "currency": "vETH",
  "convertto": "VRSC",
  "via": "Bridge.vETH"
}]'
```

Or estimate first:

```bash
verus estimateconversion '{"currency":"vETH","convertto":"VRSC","via":"Bridge.vETH","amount":0.5}'
```

---

## Contract Addresses

### Ethereum Mainnet

| Contract | Address |
|---|---|
| VRSC Token | `0xBc2738BA63882891094C99E59a02141Ca1A1C36a` |
| vETH | `0x454CB83913D688795E237837d30258d11ea7c752` |
| Bridge.vETH | `0xE6052Dcc60573561ECef2D9A4C0FEA6d3aC5B9A2` |
| DAI.vETH | `0x8b72F1c2D326d376aDd46698E385Cf624f0CA1dA` |
| MKR.vETH | `0x65b5AaC6A4aa0Eb656AB6B8812184e7545b6A221` |

### Sepolia Testnet

| Contract | Address |
|---|---|
| VRSCTEST | `0xA6ef9ea235635E328124Ff3429dB9F9E91b64e2d` |
| vETH | `0x67460C2f56774eD27EeB8685f29f6CEC0B090B00` |
| Bridge.vETH | `0xffEce948b8A38bBcC813411D2597f7f8485a0689` |

---

## Fees

| Fee Type | Amount | Notes |
|---|---|---|
| Ethereum gas | Variable (~$5-50) | Depends on network congestion |
| Bridge export fee | ~0.003 ETH | Fixed bridge fee |
| Verus transaction fee | 0.0001 VRSC | Standard Verus fee |
| AMM conversion fee | ~0.025% | Only if converting via basket |

**Budget approximately 0.01 ETH for fees** on top of the amount you want to bridge.

---

## Testnet Notes

- Use **Sepolia** testnet on the Ethereum side
- Use **VRSCTEST** on the Verus side
- Testnet bridge may not always be active — check with `verus -testnet getcurrency "Bridge.vETH"`
- Get Sepolia ETH from faucets (e.g., sepoliafaucet.com)
- The testnet bridge UI is also at [eth.verusbridge.io](https://eth.verusbridge.io/) (select testnet)

---

## Troubleshooting

| Issue | Solution |
|---|---|
| Transaction stuck on Ethereum | Wait for finality (~15 min). If gas was too low, speed up in MetaMask. |
| Funds not appearing on Verus | Wait up to 45 minutes. Check `verus getimports "Bridge.vETH"` for pending imports. |
| "Bridge not launched" error | Bridge.vETH may not be active. Check with `verus getcurrency "Bridge.vETH"`. |
| Invalid destination address | Ensure the Verus R-address or i-address is valid. Verify with `verus validateaddress "address"`. |
| Ethereum gas too high | Wait for lower gas or increase your gas limit. Bridge transactions use ~200-500k gas. |
| Wrong token received | ETH arrives as vETH, not VRSC. Use a conversion to swap vETH → VRSC if needed. |

### Checking Transfer Status

```bash
# Check pending imports from Ethereum
verus getimports "Bridge.vETH"

# Check pending exports to Ethereum
verus getexports "Bridge.vETH"

# Check bridge reserves and status
verus getcurrency "Bridge.vETH"
```

---

## Related

- [Bridge and Cross-Chain](../concepts/bridge-and-crosschain.md) — How the bridge works
- [How To: Convert Currencies](convert-currencies.md) — Convert bridged assets
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Command reference
- [Basket Currencies and DeFi](../concepts/basket-currencies-defi.md) — Bridge.vETH as a basket

---

*As of Verus v1.2.x.*


--- PAGE: how-to/convert-currencies.md ---

# How To: Convert Currencies

> Swap between currencies using the protocol-level AMM — estimate first, then execute

---

## Prerequisites

- Verus CLI installed and synced (`verusd` running)
- Wallet with sufficient balance of the source currency
- Knowledge of available basket currencies (conversion paths)

---

## Step 1: Find Available Conversion Paths

Not all currencies can convert directly. Conversions work between **reserve currencies** and their **basket (fractional) currency**. Use `getcurrencyconverters` to find paths:

```bash
# Find converters between VRSC and a USD token
verus getcurrencyconverters '["VRSCTEST","USD"]'
```

This returns basket currencies that have both VRSCTEST and USD as reserves — meaning you can convert between them.

### Understanding Conversion Paths

```
Direct conversions (one step):
  Reserve → Basket       (e.g., VRSCTEST → VRSC-USD)
  Basket  → Reserve      (e.g., VRSC-USD → VRSCTEST)

Cross-conversions via basket (two steps internally, one command):
  Reserve A → Reserve B  (e.g., VRSCTEST → USD via VRSC-USD)
  Requires the "via" parameter
```

---

## Step 2: Estimate the Conversion

**Always estimate before executing.** Use [estimateconversion](../command-reference/multichain.md#estimateconversion) to see what you'll receive:

### Reserve → Basket (Direct)

```bash
verus estimateconversion '{"currency":"VRSCTEST","convertto":"VRSC-USD","amount":10}'
```

Example output:
```json
{
  "inputcurrencyid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "netinputamount": 9.99750000,
  "outputcurrencyid": "i4QdaEnkSxkAK4FRhRJcq7V7WgRN2XhzMD",
  "estimatedcurrencyout": 53.30897428
}
```

Read this as: "Sending 10 VRSCTEST (net 9.9975 after fees) will yield approximately 53.31 VRSC-USD."

### Reserve → Reserve (Via Basket)

```bash
verus estimateconversion '{"currency":"VRSCTEST","convertto":"USD","via":"VRSC-USD","amount":100}'
```

Example output:
```json
{
  "netinputamount": 99.95000000,
  "estimatedcurrencyout": 568.27012650
}
```

Read this as: "100 VRSCTEST ≈ 568.27 USD through the VRSC-USD basket."

### Understanding the Fees

Compare `amount` vs `netinputamount`:
- **amount**: What you specified (e.g., 100)
- **netinputamount**: What actually enters the conversion (e.g., 99.95)
- **Difference**: Conversion fees (0.025% basket↔reserve, 0.05% reserve↔reserve) + standard 0.0001 VRSC tx fee

---

## Step 3: Execute the Conversion

Use [sendcurrency](../command-reference/multichain.md#sendcurrency) with the `convertto` parameter:

### Reserve → Basket

```bash
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 10,
  "currency": "VRSCTEST",
  "convertto": "VRSC-USD"
}]'
```

### Basket → Reserve

```bash
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 50,
  "currency": "VRSC-USD",
  "convertto": "VRSCTEST"
}]'
```

### Reserve → Reserve (Via Basket)

```bash
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 100,
  "currency": "VRSCTEST",
  "convertto": "USD",
  "via": "VRSC-USD"
}]'
```

**Note:** For reserve-to-reserve conversions, you **must** use the `via` parameter to specify which basket to route through.

---

## Step 4: Verify the Result

The command returns an operation ID. Check the status:

```bash
# Check operation status
verus z_getoperationstatus '["opid-abc123-..."]'

# Check your balance
verus getbalance

# Check currency balances
verus getcurrencybalance '*'
```

---

## Multi-Hop Conversions

Sometimes there's no single basket connecting two currencies. You can chain conversions:

```
Example: Convert TokenA → TokenB
  No direct basket has both TokenA and TokenB

  Solution — two steps:
  1. TokenA → VRSC  (via BasketA which has TokenA + VRSC)
  2. VRSC → TokenB  (via BasketB which has VRSC + TokenB)
```

```bash
# Step 1: TokenA → VRSC
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 100,
  "currency": "TokenA",
  "convertto": "VRSCTEST",
  "via": "BasketA"
}]'

# Wait for confirmation (~1 block)

# Step 2: VRSC → TokenB
verus sendcurrency '*' '[{
  "address": "myidentity@",
  "amount": 50,
  "currency": "VRSCTEST",
  "convertto": "TokenB",
  "via": "BasketB"
}]'
```

---

## Fees and Slippage

### Fee Structure

| Fee | Rate | Description |
|---|---|---|
| Conversion fee | ~0.025% | Goes into basket reserves (benefits all holders) |
| Transaction fee | 0.0001 VRSC | Standard flat transaction fee |
| **Total** | **~0.045%** | Visible in `netinputamount` vs `amount` |

### Slippage

The estimated output from `estimateconversion` may differ from the actual output because:
- Other conversions in the same block affect the price
- All conversions in a block execute at the **same final price** (MEV-resistant)
- Large conversions relative to reserve size cause more price impact

**Tips to minimize slippage:**
1. Check reserve sizes with `getcurrency "BasketName"` — larger reserves = less slippage
2. Split large conversions across multiple blocks
3. Compare the estimate to the actual result and adjust future amounts accordingly

---

## Common Errors

| Error | Cause | Solution |
|---|---|---|
| `Source currency cannot be converted to destination` | No valid conversion path | Use `getcurrencyconverters` to find paths; use `via` for reserve↔reserve |
| `Insufficient funds` | Not enough source currency | Check balance with `getbalance` |
| `Currency not found` | Typo in currency name | Verify with `getcurrency "name"` |
| No output / zero estimated | Amount too small | Increase amount or check if basket has liquidity |

---

## Quick Reference

```bash
# Find conversion paths
verus getcurrencyconverters '["CurrencyA","CurrencyB"]'

# Estimate (direct)
verus estimateconversion '{"currency":"SRC","convertto":"DST","amount":N}'

# Estimate (via basket)
verus estimateconversion '{"currency":"SRC","convertto":"DST","via":"BASKET","amount":N}'

# Execute (direct)
verus sendcurrency '*' '[{"address":"DEST","amount":N,"currency":"SRC","convertto":"DST"}]'

# Execute (via basket)
verus sendcurrency '*' '[{"address":"DEST","amount":N,"currency":"SRC","convertto":"DST","via":"BASKET"}]'
```

---

## Related

- [estimateconversion](../command-reference/multichain.md#estimateconversion) — Estimate command reference
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — Send/convert command reference
- [Basket Currencies and DeFi](../concepts/basket-currencies-defi.md) — How the AMM works
- [Bridge and Cross-Chain](../concepts/bridge-and-crosschain.md) — Converting bridged assets

---

*As of Verus v1.2.x.*


--- PAGE: how-to/create-marketplace-offer.md ---

# How To: Create a Marketplace Offer

> Buy, sell, and trade currencies, tokens, and identities using on-chain atomic swaps

---

## Prerequisites

- Verus CLI installed and synced (`verusd` running)
- Wallet with funds for the offer + transaction fees
- For identity sales: the identity must have a small balance for the tx fee

---

## Creating an Offer (Selling)

### Sell Currency for Currency

```bash
# Offer 100 VRSCTEST for 0.1 vETH
verus makeoffer "*" '{
  "changeaddress": "RYourChangeAddress",
  "expiryheight": 930000,
  "offer": {
    "currency": "VRSCTEST",
    "amount": 100
  },
  "for": {
    "address": "RYourPaymentAddress",
    "currency": "vETH",
    "amount": 0.1
  }
}'
```

### Sell an Identity for Currency

```bash
# Step 1: Fund the identity for the tx fee
verus sendtoaddress "myidentity@" 0.1

# Step 2: Wait for 1 confirmation (~1 minute)

# Step 3: Create the offer
verus makeoffer "myidentity@" '{
  "changeaddress": "RYourChangeAddress",
  "expiryheight": 930000,
  "offer": {
    "identity": "myidentity@"
  },
  "for": {
    "address": "RYourPaymentAddress",
    "currency": "VRSCTEST",
    "amount": 50
  }
}'
```

> ⚠️ **The identity must have funds** to cover the transaction fee. This is the #1 error people hit.

### Offer Currency for an Identity (Bidding)

```bash
# Bid 25 VRSCTEST for the identity "coolname@"
verus makeoffer "*" '{
  "changeaddress": "RYourChangeAddress",
  "expiryheight": 935000,
  "offer": {
    "currency": "VRSCTEST",
    "amount": 25
  },
  "for": {
    "name": "coolname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RYourOwnerAddress"],
    "minimumsignatures": 1
  }
}'
```

### Setting Expiry

The `expiryheight` is the block height at which the offer expires. To calculate:

```bash
# Get current block height
verus getblockcount
# Example: 926000

# Set expiry ~1 day from now (~1440 blocks at ~1 min/block)
# expiryheight = 926000 + 1440 = 927440
```

If omitted, the default is current height + 20 blocks (~20 minutes).

---

## Taking an Offer (Buying)

### Step 1: Find Offers

```bash
# Find offers for an identity
verus getoffers "coolname@" false true

# Find offers for a currency
verus getoffers "VRSCTEST" true true
```

The third parameter (`true`) includes raw transaction hex needed for `takeoffer`.

### Step 2: Review the Offer

The response shows:
- **offer** — what the seller is giving up
- **accept** — what the seller wants in return
- **blockexpiry** — when the offer expires
- **txid** — the offer transaction ID (needed for `takeoffer`)

### Step 3: Take the Offer

#### Buy an Identity

```bash
verus takeoffer "*" '{
  "txid": "abc123def456...",
  "changeaddress": "RYourChangeAddress",
  "deliver": {
    "currency": "VRSCTEST",
    "amount": 50
  },
  "accept": {
    "name": "coolname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RYourNewOwnerAddress"],
    "minimumsignatures": 1
  }
}'
```

> ⚠️ **The `primaryaddresses` in `accept` determines who controls the identity after the swap.** Double-check this.

#### Buy Currency

```bash
verus takeoffer "*" '{
  "txid": "abc123def456...",
  "changeaddress": "RYourChangeAddress",
  "deliver": {
    "currency": "vETH",
    "amount": 0.1
  },
  "accept": {
    "currency": "VRSCTEST",
    "amount": 100
  }
}'
```

---

## Listing Your Open Offers

```bash
# List active offers from your wallet
verus listopenoffers

# Include expired (unreclaimed) offers
verus listopenoffers true
```

---

## Closing / Cancelling Offers

### Cancel Specific Offers

```bash
verus closeoffers '["txid1", "txid2"]' "RDestinationAddress"
```

This cancels the offers and sends the locked funds to the specified address.

### Reclaim All Expired Offers

```bash
verus closeoffers
```

This reclaims funds from all expired offers in your wallet. **Run this periodically** to avoid leaving funds locked.

---

## Complete Workflow Example

### Scenario: Alice sells `premiumname@` to Bob for 100 VRSC

**Alice (Seller):**
```bash
# 1. Fund the identity
verus sendtoaddress "premiumname@" 0.1

# 2. Wait for confirmation

# 3. Create the offer (expires in ~24 hours)
CURRENT=$(verus getblockcount)
EXPIRY=$((CURRENT + 1440))

verus makeoffer "premiumname@" "{
  \"changeaddress\": \"RAliceAddress\",
  \"expiryheight\": $EXPIRY,
  \"offer\": {\"identity\": \"premiumname@\"},
  \"for\": {\"address\": \"RAliceAddress\", \"currency\": \"VRSCTEST\", \"amount\": 100}
}"
# Returns: txid "offer123..."
```

**Bob (Buyer):**
```bash
# 1. Find the offer
verus getoffers "premiumname@" false true

# 2. Take it
verus takeoffer "*" '{
  "txid": "offer123...",
  "changeaddress": "RBobAddress",
  "deliver": {"currency": "VRSCTEST", "amount": 100},
  "accept": {
    "name": "premiumname",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "primaryaddresses": ["RBobAddress"],
    "minimumsignatures": 1
  }
}'
```

**Result (after 1 confirmation):**
- Alice receives 100 VRSCTEST
- Bob now controls `premiumname@`
- Swap is atomic — both happen or neither happens

---

## Common Errors

| Error | Cause | Solution |
|---|---|---|
| `Insufficient funds for posting offer for identity on chain` | Identity has no balance for tx fee | Send 0.1 VRSC to the identity first |
| `Unable to fund currency delivery` | Wallet can't cover the offered amount | Check balance; use `"*"` as fromaddress |
| `Invalid or unconfirmed commitment transaction id` | Using unconfirmed transaction | Wait for 1+ confirmations |
| Empty `getoffers` response | Offer not yet confirmed | Wait ~1 minute for block confirmation |
| `Invalid identity` | Identity doesn't exist or isn't in wallet | Verify with `getidentity "name@"` |

---

## Tips

1. **Always fund identities before selling** — Send 0.1 VRSC to the identity before calling `makeoffer`
2. **Set appropriate expiry** — 1440 blocks ≈ 1 day, 10080 blocks ≈ 1 week
3. **Close expired offers** — Run `closeoffers` regularly to reclaim locked funds
4. **Use `returntx: true` to preview** — Add `true` as the third parameter to `makeoffer` to see the transaction without posting it
5. **Verify before taking** — Always inspect offer details with `getoffers` before committing funds

---

## Related

- [Marketplace and Offers](../concepts/marketplace-and-offers.md) — How the marketplace works
- [makeoffer](../command-reference/marketplace.md#makeoffer) — Command reference
- [sendcurrency](../command-reference/multichain.md#sendcurrency) — For AMM-based conversions instead

---

*As of Verus v1.2.x.*


--- PAGE: how-to/create-verusid.md ---

# How To: Create a VerusID

> Register a self-sovereign identity on the Verus blockchain.

**Estimated time:** 10–15 minutes  
**Cost:** 100 VRSC for a root mainnet ID (80 VRSC with referral — the 20 VRSC discount is split among the referral chain; see [Referral System](../concepts/identity-system.md#referral-system)). Alternatives: free IDs via Valu (Verus Discord `#valu` channel, `/getid`), cheap IDs on PBaaS chains, subIDs (set by namespace owner). Testnet: ~100 VRSCTEST (free test currency).  
**Difficulty:** Beginner

## Prerequisites

- Verus CLI installed and daemon synced (setup guide)
- A funded wallet address (R-address) with enough VRSC/VRSCTEST
- Terminal access

## Steps

### 1. Get a Wallet Address

If you don't have one yet:

```bash
./verus -testnet getnewaddress "my-wallet"
```

**Expected output:**
```
<R-address>
```

Save this address — you'll use it as your control address and primary address.

### 2. Fund Your Address

You need VRSC (or VRSCTEST) at this address. Check your balance:

```bash
./verus -testnet getbalance
```

**Testnet:** Request VRSCTEST from the community Discord faucet.  
**Mainnet:** Purchase VRSC from an exchange or receive from another user.

### 3. Check Name Availability

Before committing, verify your desired name isn't taken:

```bash
./verus -testnet getidentity "YOUR_DESIRED_NAME@"
```

If you get `Identity not found`, the name is available.

### 4. Create a Name Commitment

This hides your name choice to prevent front-running:

```bash
./verus -testnet registernamecommitment "YOUR_NAME" "YOUR_R_ADDRESS"
```

**Example:**
```bash
./verus -testnet registernamecommitment "alice" "<R-address>"
```

**Expected output:**
```json
{
  "txid": "abc123def456...",
  "namereservation": {
    "version": 1,
    "name": "alice",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "salt": "7f8a9b2c3d...",
    "referral": "",
    "nameid": "iXYZ123..."
  }
}
```

> ⚠️ **Save this entire output!** You need it for the next step. If you lose the `salt`, your commitment is wasted.

#### With a Referral (saves ~20% on mainnet — you pay 80 instead of 100 VRSC)

```bash
./verus -testnet registernamecommitment "alice" "<R-address>" "existingid@"
```

### 5. Wait for Confirmation

Wait for the commitment transaction to be mined (at least 1 block, ~1 minute):

```bash
./verus -testnet gettransaction "YOUR_COMMITMENT_TXID"
```

Look for `"confirmations": 1` or higher.

### 6. Register the Identity

Using the output from Step 4, register the identity:

```bash
./verus -testnet registeridentity '{
  "txid": "YOUR_COMMITMENT_TXID",
  "namereservation": {
    "version": 1,
    "name": "alice",
    "parent": "YOUR_PARENT_FROM_STEP4",
    "salt": "YOUR_SALT",
    "referral": "",
    "nameid": "YOUR_NAMEID"
  },
  "identity": {
    "name": "alice",
    "primaryaddresses": ["YOUR_R_ADDRESS"],
    "minimumsignatures": 1,
    "version": 3
  }
}'
```

> ⚠️ **CRITICAL:** The `namereservation` must include ALL fields from Step 4's output — `version`, `name`, `parent`, `salt`, `referral`, and `nameid`. Missing any field causes a hash mismatch error and registration will fail. **The safest approach is to copy the entire `namereservation` object from your Step 4 output exactly as-is.**
>
> **Note:** On testnet, `parent` will be `"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq"` (VRSCTEST). On mainnet, it will be `"i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV"` (VRSC). Always use whatever value was returned in Step 4.

**Expected output:**
```
a1b2c3d4e5f6...   (transaction ID)
```

### 7. Verify Your Identity

After 1 confirmation:

```bash
./verus -testnet getidentity "alice@"
```

You should see your identity details including your primary address. Check that `canspendfor` and `cansignfor` are `true` — this confirms the identity is in your wallet and you can control it.

## Testnet vs Mainnet Differences

| Feature | Testnet | Mainnet |
|---------|---------|---------|
| Command prefix | `./verus -testnet` | `./verus` |
| Registration cost | ~100 VRSCTEST | ~100 VRSC root (~80 w/ referral; free via Valu; pennies on PBaaS) |
| Referral discount | Available | Available (~20% off — pay 80 instead of 100) |
| RPC port | 18843 | 27486 |
| Currency | VRSCTEST | VRSC |

## What Could Go Wrong

| Problem | Cause | Solution |
|---------|-------|---------|
| `Insufficient funds` | Not enough VRSC in wallet | Fund your address first |
| `Identity not found` after registering | Transaction not yet confirmed | Wait for 1+ confirmations |
| Lost the commitment output | Salt is gone forever | Create a new commitment (old one is wasted) |
| `Name already registered` | Someone beat you to it | Choose a different name |
| `Invalid name` | Name has forbidden characters (`\ / : * ? " < > \| @ .`) | Use only letters, numbers, hyphens, spaces (no leading/trailing) |
| `Must wait for commitment` | Commitment not yet mined | Wait for at least 1 block |

## Advanced Options

### Multisig Identity

Require multiple signatures to control the identity:

```bash
./verus -testnet registeridentity '{
  "txid": "YOUR_TXID",
  "namereservation": { ... },
  "identity": {
    "name": "alice",
    "primaryaddresses": ["R_ADDRESS_1", "R_ADDRESS_2"],
    "minimumsignatures": 2
  }
}'
```

### Custom Revocation/Recovery

Set separate authorities for revoking and recovering your identity:

```bash
"identity": {
  "name": "alice",
  "primaryaddresses": ["YOUR_R_ADDRESS"],
  "minimumsignatures": 1,
  "revocationauthority": "trustedfriend@",
  "recoveryauthority": "backupid@"
}
```

---

*Last updated: 2026-02-07*


--- PAGE: how-to/launch-token.md ---

# How To: Launch a Token on Verus

> Create your own currency token using the Verus DeFi protocol.

**Estimated time:** 15–20 minutes  
**Cost:** ~200 VRSCTEST (testnet) or ~200 VRSC (mainnet) for currency definition  
**Difficulty:** Intermediate

## Prerequisites

- Verus CLI installed and daemon fully synced
- A registered VerusID with the name you want for your token ([create one first](create-verusid.md))
- ~200 VRSCTEST/VRSC in your wallet for the definition fee
- The VerusID must NOT already have an active currency defined on it

## Understanding Token Types

| Type | Options Flag | Description |
|------|-------------|-------------|
| Simple Token | `32` (0x20) | Basic token — fixed or mintable supply |
| Fractional Basket | `33` (TOKEN + FRACTIONAL) | AMM-backed token with reserve currencies |
| PBaaS Chain | `256` (0x100) | Independent blockchain (advanced, 10,000 VRSC) |

### Proof Protocol Choices

| Value | Name | Meaning |
|-------|------|---------|
| `1` | PROOF_PBAASMMR | Decentralized — no one can mint/burn |
| `2` | PROOF_CHAINID | Centralized — ID holder can mint and burn |
| `3` | PROOF_ETHNOTARIZATION | Ethereum bridge notarization |

## Steps

### 1. Verify Your VerusID Exists

```bash
./verus -testnet getidentity "YOUR_TOKEN_NAME@"
```

The identity name will become the token name.

### 2. Verify No Currency Exists Yet

```bash
./verus -testnet getcurrency "YOUR_TOKEN_NAME"
```

Should return an error like `Currency not found`. If it returns data, this ID already has a currency.

### 3. Define the Currency

#### Option A: Simple Centralized Token

You control minting and burning. Good for loyalty points, project tokens, platform currencies.

```bash
./verus -testnet definecurrency '{
  "name": "YOUR_TOKEN_NAME",
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"YOUR_ID@": 1000}]
}'
```

**Flags explained:**
- `options: 32` — TOKEN type
- `proofprotocol: 2` — Centralized (you can mint/burn)
- `idregistrationfees` — Cost for sub-identities under this namespace
- `idreferrallevels: 0` — No referral rewards for subIDs
- `preallocations` — Tokens minted to specified identities at launch

#### Option B: Decentralized Fixed-Supply Token

No one can mint after launch. Supply is set by `preallocations` only.

```bash
./verus -testnet definecurrency '{
  "name": "YOUR_TOKEN_NAME",
  "options": 32,
  "proofprotocol": 1,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"YOUR_ID@": 1000000}]
}'
```

#### Option C: Fractional Basket Currency (AMM)

An automatically-managed liquidity pool backed by reserve currencies.

```bash
./verus -testnet definecurrency '{
  "name": "YOUR_TOKEN_NAME",
  "options": 33,
  "currencies": ["VRSCTEST"],
  "weights": [1.0],
  "initialsupply": 100000,
  "initialcontributions": [1000],
  "idregistrationfees": 1,
  "idreferrallevels": 3,
  "preallocations": [{"YOUR_ID@": 10000}]
}'
```

**Additional flags:**
- `options: 33` — FRACTIONAL (1) + TOKEN (32)
- `currencies` — Reserve currencies backing the basket
- `weights` — Relative weight of each reserve (must sum to 1.0, minimum 0.1 per reserve)
- `initialsupply` — Total supply after initial contributions convert
- `initialcontributions` — Amount of each reserve deposited at launch

**Expected output:**
```json
{
  "txid": "abc123...",
  "tx": { ... },
  "hex": "0400..."
}
```

### 4. Wait for Confirmation and Launch

```bash
./verus -testnet gettransaction "YOUR_DEFINITION_TXID"
```

Wait for at least 1 confirmation for the definition tx to be mined. Then wait a **minimum of 20 blocks** (~20 minutes) for the currency to become active and usable. During this launch period, preconversions can occur for basket currencies.

### 5. Verify the Currency

```bash
./verus -testnet getcurrency "YOUR_TOKEN_NAME"
```

Should show your token definition with supply, options, etc.

### 6. Mint Tokens (Centralized Only)

If you used `proofprotocol: 2`, you can mint additional tokens:

```bash
./verus -testnet sendcurrency "YOUR_TOKEN_NAME@" '[{
  "address": "RECIPIENT_ADDRESS_OR_ID",
  "amount": 500,
  "currency": "YOUR_TOKEN_NAME",
  "mintnew": true
}]'
```

> ⚠️ The `fromaddress` **must** be the token's controlling identity (e.g., `"YOUR_TOKEN_NAME@"`).

### 7. Send Tokens

```bash
./verus -testnet sendcurrency "*" '[{
  "address": "recipient@",
  "amount": 10,
  "currency": "YOUR_TOKEN_NAME"
}]'
```

## Options Bitfield Reference

Options are combined by adding values:

| Bit | Value | Name | Description |
|-----|-------|------|-------------|
| 0 | 1 | FRACTIONAL | AMM basket currency |
| 1 | 2 | IDRESTRICTED | Only approved IDs can hold |
| 2 | 4 | IDSTAKING | IDs can stake this currency |
| 3 | 8 | IDREFERRALS | ID referral rewards enabled |
| 4 | 16 | IDREFERRALSREQUIRED | Referral required for ID registration |
| 5 | 32 | TOKEN | Token on this chain (not an independent chain) |
| 8 | 256 | IS_PBAAS_CHAIN | Independent blockchain |
| 11 | 2048 | NFT_TOKEN | Single-satoshi NFT with tokenized rootID control |

**Common combinations:**
- `32` = Simple token
- `33` = Fractional basket token (32 + 1)
- `40` = Token with ID referrals (32 + 8)
- `256` = PBaaS chain (base)
- `264` = PBaaS chain with referrals (256 + 8)

## What Could Go Wrong

| Problem | Cause | Solution |
|---------|-------|---------|
| `Identity not found` | Named identity doesn't exist | Create the VerusID first |
| `Currency already defined` | ID already has a currency | Use a different identity |
| `Insufficient funds` | Need ~200 VRSCTEST | Fund your wallet |
| `Cannot mint currency` | Wrong `fromaddress` or `proofprotocol` isn't 2 | Use the currency's ID as sender; only centralized tokens can mint |
| Token not showing in wallet | Not yet confirmed | Wait for 1+ blocks |

## Mainnet Notes

- Definition fee: ~200 VRSC (same as testnet equivalent)
- PBaaS chain definition: ~10,000 VRSC
- Test on testnet first — currency definitions are permanent
- Once a currency is defined on an identity, it cannot be redefined

---

*Last updated: 2026-02-07*


--- PAGE: how-to/manage-subids.md ---

# How to Manage SubIDs

SubIDs are child identities created under a parent namespace (currency). If you own `MyCurrency`, you can create identities like `user.MyCurrency@`. This guide covers creating, configuring, and updating subIDs.

> **Prerequisites**: You must own a currency/namespace on Verus. See [Launch a Token](launch-token.md).

## What Are SubIDs?

SubIDs are VerusIDs that exist **under your namespace**:

- Parent currency: `MyPlatform`
- SubID: `alice.MyPlatform@`

The parent namespace owner controls:
- Who can create subIDs (or allow open registration)
- The registration fee
- Whether subIDs can be created at all

### Use Cases

- **Platform user accounts** — `username.YourApp@`
- **Agent registry** — `agent-name.AgentNetwork@`
- **Organization members** — `employee.Company@`
- **NFT/asset naming** — `item-001.Collection@`

## Step 1: Check Your Namespace

Verify you own the currency that will be the parent:

```bash
./verus getcurrency "MyPlatform"
```

Confirm you control the identity associated with this currency.

## Step 2: Set SubID Registration Fees

When defining your currency (at launch), the `idregistrationfees` parameter controls subID costs. If your currency is already launched, the fee structure is set.

The fee can be set as low as 1 satoshi (0.00000001) or as high as you want. A standard 0.0001 VRSC transaction fee always applies on top.

## Step 3: Create a SubID

### Register the Name Commitment

```bash
./verus registernamecommitment "alice" "RControllerAddress" "" "MyPlatform"
```

The last parameter (`"MyPlatform"`) specifies the **parent namespace**.

Wait for 1 confirmation, then use the output to register:

### Register the SubID

```bash
./verus registeridentity '{
  "txid": "commitment-txid",
  "namereservation": {
    "name": "alice",
    "salt": "salt-from-commitment",
    "referral": "",
    "parent": "iPlatformIDAddress...",
    "nameid": "iSubIDAddress..."
  },
  "identity": {
    "name": "alice",
    "parent": "iPlatformIDAddress...",
    "primaryaddresses": ["RAliceAddress..."],
    "minimumsignatures": 1,
    "revocationauthority": "alice.MyPlatform@",
    "recoveryauthority": "alice.MyPlatform@"
  }
}'
```

> ⚠️ **The `parent` field is required** in the identity object. Without it, the registration targets the root VRSC namespace instead of your currency.

## Step 4: Verify the SubID

```bash
./verus getidentity "alice.MyPlatform@"
```

This shows the full identity including primary addresses, authorities, and the parent reference.

## Updating SubIDs

The subID owner (or the parent namespace owner, depending on configuration) can update it:

```bash
./verus updateidentity '{
  "name": "alice",
  "parent": "iPlatformIDAddress...",
  "primaryaddresses": ["RNewAddress..."],
  "minimumsignatures": 1
}'
```

> ⚠️ **Always include the `parent` field** when updating subIDs. Omitting it can cause the update to target the wrong namespace.

### What Can Be Updated?

- Primary addresses (key rotation)
- Minimum signatures
- Revocation and recovery authorities
- Private address
- Content map / content multimap

## Creating a SubID for Someone Else

A common use case: someone gives you their R-address, and you register a subID under your namespace with them as the owner. Here's the complete flow:

### 1. Commit the Name

The `controladdress` in the commitment must be an address **in your wallet** (since you're paying the fee). This is NOT the final owner — just needed for the commitment transaction.

```bash
./verus registernamecommitment "username" "RYourWalletAddress" "" "MyPlatform"
```

### 2. Register with Their Address as Owner

After 1 confirmation (~60 seconds), register the identity with the **recipient's R-address** in `primaryaddresses`:

```bash
./verus registeridentity '{
  "txid": "commitment-txid-from-step-1",
  "namereservation": {
    "version": 1,
    "name": "username",
    "salt": "salt-from-step-1",
    "referral": "",
    "parent": "iPlatformIDAddress...",
    "nameid": "iSubIDAddress-from-step-1..."
  },
  "identity": {
    "name": "username",
    "parent": "iPlatformIDAddress...",
    "primaryaddresses": ["RTheirAddress..."],
    "minimumsignatures": 1
  }
}'
```

> **Important:** Include ALL fields from the `namereservation` output in step 1 — `version`, `name`, `salt`, `referral`, `parent`, and `nameid`.

### 3. Send Them Namespace Tokens (Optional)

If your namespace uses tokens for fees or services, send some to the new owner:

```bash
./verus sendcurrency "*" '[{"address":"RTheirAddress...","amount":10,"currency":"MyPlatform"}]'
```

### 4. Verify

```bash
./verus getidentity "username.MyPlatform@"
```

The identity now belongs to the recipient — they control it with their private key. You (as namespace owner) cannot modify it unless you set yourself as revocation/recovery authority.

## Batch Creation

For creating many subIDs programmatically (e.g., onboarding users):

```bash
# Script pattern for each user
NAME="user001"
PARENT="iPlatformIDAddress..."
ADDR="RUserAddress..."

# Commit
RESULT=$(./verus registernamecommitment "$NAME" "$ADDR" "" "MyPlatform")
# Parse txid and salt from $RESULT
# Wait for confirmation
# Register with parsed values
```

> 💡 **Tip**: Each commitment needs 1 confirmation before registration. For batch operations, submit all commitments first, wait for a block, then register all.

## Revoking a SubID

If a subID is compromised, the revocation authority can disable it:

```bash
./verus revokeidentity "alice.MyPlatform@"
```

The recovery authority can then restore it with new keys using `recoveridentity`.

## Cost Summary

| Action | Cost |
|--------|------|
| Create subID | Registration fee (set by parent currency) |
| Update subID | Transaction fee only (~0.0001 VRSC) |
| Revoke subID | Transaction fee only |
| Recover subID | Transaction fee only |

## Related

- [Create a VerusID](create-verusid.md) — Root-level identity registration
- [Launch a Token](launch-token.md) — Create your namespace first
- [VerusID Concepts](../concepts/identity-system.md) — Identity system deep dive


--- PAGE: how-to/mine-vrsc.md ---

# How To: Mine VRSC

> Use your CPU to mine Verus blocks and earn rewards.

**Estimated time:** 10 minutes to start mining  
**Cost:** Electricity only  
**Difficulty:** Beginner

## Prerequisites

- Verus CLI installed and daemon fully synced (setup guide)
- A modern CPU with AES-NI and AVX support (recommended — GPUs and FPGAs can also mine but CPUs are most cost-effective)
- Terminal access

## About VerusHash 2.2

Verus uses **VerusHash 2.2**, a mining algorithm optimized for CPUs. It leverages AES and AVX instructions. **FPGAs can mine** but are intentionally equalized to ~2x CPU cost-performance — they're not blocked, just not dominant. No ASICs exist. **GPU mining software exists** (ccminer `Verus2.2gpu` branch) but GPUs generally perform worse than modern CPUs. Older CPUs without AES-NI can still mine, just at significantly reduced performance. This keeps mining accessible and fair: anyone with a CPU can participate.

## Steps

### 1. Ensure You Have a Wallet Address

```bash
./verus -testnet getnewaddress "mining"
```

Mining rewards will be sent to addresses in your wallet.

### 2. Start Solo Mining

```bash
./verus -testnet setgenerate true NUM_THREADS
```

Replace `NUM_THREADS` with the number of CPU threads to use:

```bash
# Mine with 4 threads
./verus -testnet setgenerate true 4

# Mine with all available threads
./verus -testnet setgenerate true -1
```

**Expected output:** (none — silence means success)

> 💡 **Tip:** Leave 1-2 threads free for system stability. If you have 8 threads, use 6.

### 3. Verify Mining Is Active

```bash
./verus -testnet getmininginfo
```

**Expected output:**
```json
{
  "blocks": 926961,
  "difficulty": 56478309.28295863,
  "errors": "",
  "genproclimit": 4,
  "localhashps": 2500000,
  "networkhashps": 16857317,
  "pooledtx": 0,
  "testnet": true,
  "generate": true,
  "staking": false,
  "numthreads": 4,
  "mergemining": 0
}
```

**Key fields:**
- `"generate": true` — mining is enabled
- `"numthreads": 4` — number of CPU threads mining
- `"localhashps"` — your local hash rate (higher = better)
- `"networkhashps"` — total network hash rate

### 4. Monitor Your Hashrate

```bash
./verus -testnet getlocalsolps
```

Returns your solutions per second. Higher is better.

### 5. Check for Rewards

```bash
./verus -testnet listtransactions "*" 10
```

Mined blocks appear as `"category": "generate"` transactions.

### 6. Stop Mining

```bash
./verus -testnet setgenerate false
```

### 7. Mine AND Stake Simultaneously

You can mine with CPU threads while also staking:

```bash
# Mine with 4 threads + stake
./verus -testnet setgenerate true 4
```

Any value > 0 enables both mining and staking (if you have mature coins).

## Solo Mining vs Pool Mining

| Factor | Solo Mining | Pool Mining |
|--------|------------|-------------|
| Rewards | Full block reward when you find a block | Proportional share of all blocks found |
| Consistency | Very inconsistent (feast or famine) | Steady, smaller payouts |
| Difficulty | Need significant hashrate to compete | Low hashrate still earns |
| Setup | Built into Verus CLI | Requires pool software |
| Fees | None | 0.1–5% pool fee (varies by pool) |

**Recommendation:** For most users, **staking is more practical** than solo mining on mainnet. If you want to mine, use a pool — solo mining on an average desktop CPU is no longer practical given current network hashrate. Staking requires no special hardware and earns comparable rewards.

## Pool Mining

For pool mining, you need a separate mining application instead of the built-in miner.

### Popular Verus Mining Pools

| Pool | URL | Fee |
|------|-----|-----|
| Luckpool | https://luckpool.net/verus | 1% |
| Zergpool | https://zergpool.com | 0.5% |
| Verus Farm | https://verus.farm | 1% |
| Paddy Pool | https://paddypool.net | 0.1% |
| Verus Pool (VCF) | https://pool.verus.io | 5% (donated to VCF) |

> ⚠️ Pool availability and fees change — check current pools at [verus.io](https://verus.io) or the Verus Discord. The full list has 13+ pools.

### Pool Mining Setup (CCMiner)

1. Download a VerusHash-compatible miner (e.g., CCMiner — the officially recommended mining software)
2. Configure with your pool and wallet address:

```bash
ccminer -a verus -o stratum+tcp://POOL_ADDRESS:PORT -u YOUR_VRSC_ADDRESS.WORKER_NAME
```

Replace:
- `POOL_ADDRESS:PORT` — from your chosen pool
- `YOUR_VRSC_ADDRESS` — your Verus R-address
- `WORKER_NAME` — any name to identify this miner

## CPU Requirements

| CPU Feature | Impact |
|------------|--------|
| AES-NI support | **Strongly recommended** for competitive hashrate (older CPUs can still mine slowly) |
| Core count | More cores = more threads = higher hashrate |
| Clock speed | Higher is better per-thread |
| Cache size | Larger L3 cache helps |

**Typical hashrates (community estimates — actual results vary):**
- Intel i5 (4 cores): ~2-4 MH/s
- Intel i7 (8 cores): ~5-10 MH/s
- AMD Ryzen 7 (8 cores): ~8-15 MH/s
- AMD Ryzen 9 (16 cores): ~15-30 MH/s
- Server Xeon (32+ cores): ~30-60 MH/s

## Auto-Start Mining on Boot

Add to your Verus config (`~/.komodo/VRSC/VRSC.conf`):

```ini
gen=1
genproclimit=4
```

## What Could Go Wrong

| Problem | Cause | Solution |
|---------|-------|---------|
| `"localhashps": 0` | Mining just started | Wait 30-60 seconds for hashrate to register |
| Very low hashrate | CPU doesn't support AES-NI | Check with `lscpu | grep aes` on Linux |
| No blocks found after days | Normal for solo mining | Switch to pool mining for consistent rewards |
| High CPU temperature | Too many threads | Reduce thread count; check cooling |
| System unresponsive | Using all CPU threads | Use fewer threads (`setgenerate true N` where N < total cores) |

---

*Last updated: 2026-02-07*


--- PAGE: how-to/revoke-recover-identity.md ---

# How to Revoke and Recover a VerusID

This guide walks through the complete revoke and recover cycle for a VerusID. This is one of Verus's most powerful safety features — if your keys are compromised, you can disable the identity and recover it with new keys.

> **Placeholder convention:** Examples in this guide use `alice.yourapp@` as the identity being protected, `recovery@` as the revocation/recovery authority, `i...` to mark a placeholder i-address (substitute the real one from `getidentity`), `<R-address>` for a transparent address, `<new-R-address>` for the post-recovery address, and `<txid>` for a transaction ID returned by the chain.

## Overview

Every VerusID has three key authorities:
- **Primary address(es)** — controls spending and signing
- **Revocation authority** — can disable (revoke) the identity
- **Recovery authority** — can re-enable and assign new keys to a revoked identity

By default, all three point to the identity itself. For real security, you should set revocation and recovery to **different** identities that you (or a trusted party) control.

## Prerequisites

- A VerusID you want to protect
- A separate VerusID to act as revocation/recovery authority
- Access to the Verus CLI (`verus` command)
- Both identities' keys must be in the respective wallets

## Step 1: Set Up Revocation and Recovery Authorities

First, assign a trusted identity as your rev/recovery authority. In this example, we'll set `recovery@` as both authorities for `alice.yourapp@`.

**From the owner's wallet** (the wallet holding the primary key for `alice.yourapp@`):

```bash
verus -testnet updateidentity '{
  "name": "alice",
  "parent": "i...",
  "revocationauthority": "i...",
  "recoveryauthority": "i..."
}'
```

| Field | Value | Meaning |
|-------|-------|---------|
| `name` | `alice` | The identity name (without parent suffix) |
| `parent` | `i...` | Parent namespace i-address (required for subIDs) |
| `revocationauthority` | `i...` | i-address of `recovery@` |
| `recoveryauthority` | `i...` | i-address of `recovery@` |

> ⚠️ **Important**: Once you assign rev/recovery to another identity, only that identity can revoke or recover yours. Only the current revocation authority can change the revocation authority, and only the current recovery authority can change the recovery authority. Make sure you trust whoever controls that identity.

Wait for the transaction to confirm (1 block, ~60 seconds).

## Step 2: Verify the Setup

```bash
verus -testnet getidentity alice.yourapp@
```

Check the output:
```json
{
  "identity": {
    "primaryaddresses": ["<R-address>"],
    "revocationauthority": "i...",
    "recoveryauthority": "i..."
  },
  "status": "active",
  "canspendfor": true,
  "cansignfor": true
}
```

## Step 3: Revoke the Identity

This is done from the **revocation authority's wallet** (the wallet holding the keys for `recovery@`).

```bash
verus -testnet revokeidentity "alice.yourapp@"
```

Returns a transaction ID:
```
<txid>
```

After confirmation, check the status:
```bash
verus -testnet getidentity alice.yourapp@
```

```json
{
  "status": "revoked",
  "canspendfor": false,
  "cansignfor": false
}
```

The identity is now **disabled**:
- Cannot sign messages
- Cannot spend funds
- Cannot update itself
- Still exists on-chain and holds its funds safely

> 💡 **Funds are safe**: A revoked identity still holds all its VRSC and tokens. They're frozen, not lost. Recovery restores full access.

## Step 4: Recover with New Keys

This is done from the **recovery authority's wallet**. Generate a new address first:

```bash
verus -testnet getnewaddress
```
```
<new-R-address>
```

Now recover the identity, assigning the new primary key:

```bash
verus -testnet recoveridentity '{
  "name": "alice",
  "parent": "i...",
  "primaryaddresses": ["<new-R-address>"],
  "minimumsignatures": 1,
  "revocationauthority": "i...",
  "recoveryauthority": "i..."
}'
```

Returns a transaction ID:
```
<txid>
```

> 💡 You can change rev/recovery during recovery too. To hand full control back to the owner, set both to the identity's own i-address.

## Step 5: Verify Recovery

After confirmation:

```bash
verus -testnet getidentity alice.yourapp@
```

```json
{
  "identity": {
    "primaryaddresses": ["<new-R-address>"],
    "revocationauthority": "i...",
    "recoveryauthority": "i..."
  },
  "status": "active",
  "canspendfor": true,
  "cansignfor": true
}
```

The identity is **active again** with a brand new primary key. The old compromised key has no authority.

## Transferring Back to the Original Owner

If the recovery was done to protect the identity temporarily, you can transfer control back by updating the primary address to one the original owner provides:

```bash
verus -testnet updateidentity '{
  "name": "alice",
  "parent": "i...",
  "primaryaddresses": ["<owners-new-R-address>"],
  "revocationauthority": "<owners-choice>",
  "recoveryauthority": "<owners-choice>"
}'
```

## Real-World Use Cases

### Key Compromise
Your computer is hacked and your private keys are stolen. Your recovery authority (on a separate device or held by a trusted friend) can revoke the identity before the attacker drains funds, then recover it with fresh keys.

### Platform-Managed Identity Safety
An AI agent's identity is controlled by a platform. If the agent misbehaves or is compromised, the platform (as revocation authority) can instantly disable it. The agent's identity, reputation, and funds remain intact for later recovery.

### Dead Man's Switch
Set a trusted family member as recovery authority. If you lose access to your keys, they can recover your identity and all associated funds.

### Multi-Party Security
Set revocation to yourself (quick response) and recovery to a trusted third party (backup). You can freeze the identity fast, and the third party can help you recover it.

## Key Rules

| Rule | Detail |
|------|--------|
| Only revocation authority can revoke | Not even the identity owner can revoke if rev authority is different |
| Only recovery authority can recover | Recovery assigns new keys and re-enables |
| Only revocation authority can change revocation authority | Prevents attackers from reassigning safety nets |
| Only recovery authority can change recovery authority | Same protection for recovery |
| Funds are frozen, not lost | A revoked identity still holds all assets |
| Recovery can change everything | New keys, new rev/recovery authorities — full reset |
| One confirmation needed | Both revoke and recover take effect after 1 block (~60 seconds) |

## Commands Reference

| Command | Who Runs It | What It Does |
|---------|-------------|--------------|
| `updateidentity` | Identity owner | Set rev/recovery authorities |
| `revokeidentity` | Revocation authority | Disable the identity |
| `recoveridentity` | Recovery authority | Re-enable with new keys |
| `getidentity` | Anyone | Check status, authorities, keys |


--- PAGE: how-to/send-private-transaction.md ---

# How to Send a Private Transaction

This guide walks you through sending a fully private transaction on Verus using shielded addresses.

> **Prerequisites**: Daemon running and synced, wallet with VRSC. See [First Steps](../getting-started/first-steps.md).

## Step 1: Create a Shielded Address

```bash
./verus z_getnewaddress
```

Output: `zsYourNewShieldedAddress...`

Save this address — you'll use it to hold private funds.

## Step 2: Shield Your Coins

Move VRSC from your transparent address to your shielded address.

### Option A: Using z_sendmany

```bash
./verus z_sendmany "RYourTransparentAddress" '[{"address":"zsYourShieldedAddress","amount":25.0}]'
```

### Option B: Shield Mining Rewards

If your VRSC comes from mining:

```bash
./verus z_shieldcoinbase "*" "zsYourShieldedAddress"
```

Both commands return an **operation ID**. Check progress:

```bash
./verus z_getoperationstatus '["opid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]'
```

Wait for `"status": "success"` and at least 1 confirmation.

## Step 3: Send Privately

Send from your shielded address to the recipient's shielded address:

```bash
./verus z_sendmany "zsYourShieldedAddress" '[{"address":"zsRecipientAddress","amount":10.0}]'
```

This is a **fully private** transaction — sender, receiver, and amount are all hidden on the blockchain.

### With an Encrypted Memo

The memo field must be a **hex-encoded string**, not plain text. Convert your message to hex first:

```bash
# Convert text to hex
echo -n "Payment for services" | xxd -p
# Output: 5061796d656e7420666f72207365727669636573

# Send with hex memo
./verus z_sendmany "zsYourShieldedAddress" '[{"address":"zsRecipientAddress","amount":10.0,"memo":"5061796d656e7420666f72207365727669636573"}]'
```

The memo is encrypted and visible only to the recipient (up to 512 bytes of hex data).

## Step 4: Check Your Shielded Balance

```bash
# Specific address
./verus z_getbalance "zsYourShieldedAddress"

# All balances
./verus z_gettotalbalance
```

Output:
```json
{
  "transparent": "75.00000000",
  "private": "15.00000000",
  "total": "90.00000000"
}
```

## Step 5: View Transaction Details

```bash
./verus z_viewtransaction "txid-from-operation-result"
```

Shows the decoded transaction from your wallet's perspective, including amounts and memos.

To get the txid from a completed operation:

```bash
./verus z_getoperationresult '["opid-xxx"]'
```

The `txid` is in the result object.

## Sending to a Transparent Address (Partial Privacy)

You can send from shielded to transparent — the **source** stays hidden but the **destination** is public:

```bash
./verus z_sendmany "zsYourShieldedAddress" '[{"address":"RRecipientTransparentAddress","amount":10.0}]'
```

## Quick Reference

| Step | Command |
|------|---------|
| Create shielded address | `z_getnewaddress` |
| Shield coins | `z_sendmany` from R to zs |
| Shield mining rewards | `z_shieldcoinbase` |
| Send privately | `z_sendmany` from zs to zs |
| Check balance | `z_getbalance`, `z_gettotalbalance` |
| View transaction | `z_viewtransaction` |
| Check operation | `z_getoperationstatus` |

## Related

- [Privacy & Shielded Transactions](../concepts/privacy-shielded-tx.md) — How privacy works under the hood
- [Wallet Setup](../getting-started/wallet-setup.md) — Address types and basics


--- PAGE: how-to/setup-multisig.md ---

# How to Set Up Multisig with VerusID

Verus implements multisig natively through VerusID — no special scripts or contracts needed. This guide shows how to create a 2-of-3 multisig identity.

> **Prerequisites**: Daemon synced, enough VRSC for VerusID registration (~100 VRSC for a root ID, 80 with referral; or use cheaper alternatives like subIDs or PBaaS chain IDs). See [Create a VerusID](create-verusid.md).

## What Is Multisig?

Multisig (multi-signature) requires **multiple parties to approve** a transaction before it executes. A 2-of-3 setup means any 2 out of 3 keyholders must sign.

### Use Cases

- **Shared treasury** — Team funds require multiple approvals
- **Security** — No single compromised key can drain funds
- **Business accounts** — Corporate spending controls
- **Escrow** — Third-party dispute resolution

## Step 1: Gather the Primary Addresses

You need the addresses (or VerusID i-addresses) of all signers. Each signer generates an address:

```bash
# Signer 1
./verus getnewaddress
# → R1aaaa...

# Signer 2
./verus getnewaddress
# → R2bbbb...

# Signer 3
./verus getnewaddress
# → R3cccc...
```

You can also use VerusID i-addresses (e.g., `alice@`, `bob@`, `carol@`).

## Step 2: Register a Multisig VerusID

Register the identity with multiple primary addresses and set `minimumsignatures` to 2:

```bash
./verus registernamecommitment "TeamWallet" "RControllerAddress"

# Wait for confirmation, then:
./verus registeridentity '{
  "txid": "commitment-txid",
  "namereservation": {
    "version": 1,
    "name": "TeamWallet",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "salt": "salt-from-commitment",
    "referral": "",
    "nameid": "iXXXXX..."
  },
  "identity": {
    "name": "TeamWallet",
    "primaryaddresses": [
      "R1aaaa...",
      "R2bbbb...",
      "R3cccc..."
    ],
    "minimumsignatures": 2,
    "revocationauthority": "TeamWallet@",
    "recoveryauthority": "RecoveryID@"
  }
}'
```

Key fields:
- `primaryaddresses` — All 3 signer addresses
- `minimumsignatures` — How many must sign (2 in this case)

## Step 3: Fund the Multisig Identity

Send VRSC to the identity:

```bash
./verus sendtoaddress "TeamWallet@" 100
```

## Step 4: Spending from Multisig

When spending from a multisig VerusID, the transaction needs signatures from the required number of keyholders.

### Create the Transaction (Signer 1)

```bash
./verus sendcurrency "TeamWallet@" '[{"address":"RecipientAddress","amount":25}]'
```

If Signer 1's wallet holds only one of the required keys, the daemon will produce a **partially signed transaction**. The process depends on how many keys are in the local wallet:

- **If 2+ required keys are in the same wallet**: The transaction completes automatically
- **If keys are on separate machines**: Use `signrawtransaction` to collect signatures

### Multi-Machine Signing

```bash
# Signer 1: Create raw transaction
./verus createrawtransaction '[...]' '{...}'

# Signer 1: Sign (partial)
./verus signrawtransaction "raw-tx-hex"
# Returns partially signed hex with complete: false

# Signer 2: Sign the partially signed tx
./verus signrawtransaction "partially-signed-hex"
# Returns fully signed hex with complete: true

# Either signer: Broadcast
./verus sendrawtransaction "fully-signed-hex"
```

## Changing Multisig Configuration

You can update the signers or threshold by updating the identity:

```bash
./verus updateidentity '{
  "name": "TeamWallet",
  "primaryaddresses": [
    "R1aaaa...",
    "R4dddd...",
    "R3cccc..."
  ],
  "minimumsignatures": 2
}'
```

> ⚠️ If `TeamWallet` is a **subID** (e.g., `TeamWallet.MyPlatform@`), you **must** include the `"parent"` field in the update. See [Manage SubIDs](manage-subids.md).

This requires the current minimum signatures to approve.

## Tips

- **Start with 2-of-3** — good balance of security and convenience
- **Use VerusIDs as signers** when possible — they're recoverable if keys are lost
- **Set recovery/revocation** to a separate identity you control
- **Test with small amounts** before committing significant funds
- **Document the setup** — make sure all signers know the configuration

## Related

- [Create a VerusID](create-verusid.md) — VerusID basics
- [VerusID Concepts](../concepts/identity-system.md) — How identities work


--- PAGE: how-to/stake-vrsc.md ---

# How To: Stake VRSC

> Earn block rewards by staking your VRSC coins — no special hardware needed.

**Estimated time:** 5 minutes to enable (first reward may take hours/days)  
**Cost:** None (you keep your coins)  
**Difficulty:** Beginner

## Prerequisites

- Verus CLI installed and daemon fully synced
- VRSC (or VRSCTEST) in your wallet
- Coins must be **mature** (150+ confirmations, ~2.5 hours on mainnet)

## How Staking Works

Verus uses a hybrid PoW/PoS consensus. When you stake:
- Your wallet automatically creates stake transactions using your mature UTXOs
- Larger UTXOs = higher chance of being selected to stake a block (one large UTXO stakes better than many small ones of the same total)
- There is no minimum balance requirement (technically 0.00000001 VRSC)
- You earn the full block reward when you successfully stake
- Your coins never leave your wallet — they're not locked or at risk

## Steps

### 1. Check Your Balance

```bash
./verus -testnet getbalance
```

Ensure you have coins available. For meaningful staking, more is better.

### 2. Verify Coins Are Mature

Coins need 150+ confirmations before they're eligible for staking:

```bash
./verus -testnet listunspent 150
```

This shows only UTXOs with 150+ confirmations. If empty, your coins aren't mature yet — wait.

### 3. Enable Staking

```bash
./verus -testnet setgenerate true 0
```

The `0` means zero mining threads — staking only, no CPU mining.

**Expected output:** (none — silence means success)

### 4. Verify Staking Is Active

```bash
./verus -testnet getmininginfo
```

**Expected output:**
```json
{
  "blocks": 926961,
  "currentblocksize": 0,
  "currentblocktx": 0,
  "difficulty": 56478309.28295863,
  "stakingsupply": 31566038.74104909,
  "errors": "",
  "genproclimit": 0,
  "localhashps": 0,
  "networkhashps": 16857317,
  "pooledtx": 0,
  "testnet": true,
  "chain": "main",
  "generate": true,
  "staking": true,
  "numthreads": 0,
  "mergemining": 0
}
```

**Key fields to check:**
- `"generate": true` — generation is enabled
- `"staking": true` — staking is active
- `"numthreads": 0` — not mining (staking only)

### 5. Monitor for Rewards

Check your balance periodically:

```bash
./verus -testnet getbalance
```

Or check recent transactions:

```bash
./verus -testnet listtransactions "*" 10
```

Staking rewards appear as `"category": "stake"` or `"generate"` transactions.

### 6. Stop Staking (When Needed)

```bash
./verus -testnet setgenerate false
```

This stops **both** mining and staking.

## How Long Until My First Stake?

It depends on your balance relative to the total staking supply:

| Your Balance | Network Staking Supply | Approx. Time Between Stakes |
|-------------|----------------------|---------------------------|
| 1,000 VRSC | 30,000,000 VRSC | ~42 days |
| 10,000 VRSC | 30,000,000 VRSC | ~4 days |
| 100,000 VRSC | 30,000,000 VRSC | ~10 hours |
| 1,000,000 VRSC | 30,000,000 VRSC | ~1 hour |

**Formula:** `(Staking Supply ÷ Your Balance) ÷ 720 = days between stakes` (720 = avg PoS blocks per day at 50/50 split). These are rough estimates — staking is probabilistic.

## Auto-Start Staking on Boot

Add to your Verus config file (`~/.komodo/VRSC/VRSC.conf` or `~/.komodo/vrsctest/vrsctest.conf`):

```ini
gen=1
genproclimit=0
```

This enables staking every time the daemon starts.

## Pool Staking

You can also stake through **non-custodial staking pools** using VerusID. This lets you combine staking power with other users without giving up control of your coins:

- **Non-custodial (VerusID-based)**: Your coins remain in your wallet, but your VerusID delegates staking power to a pool. No trust required.
- **Custodial**: You send coins to a pool operator (requires trust).

Check the Verus Discord for current staking pools (e.g., Synergy Pool).

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|---------|
| `"staking": false` | No mature coins or wallet locked | Check `listunspent 150`; wait for coins to mature |
| `"generate": false` | Staking not enabled | Run `setgenerate true 0` |
| No rewards after days | Balance too small relative to network | Normal — increase balance or be patient |
| `"stakingsupply": 0` | Node not fully synced | Wait for full sync (`getinfo` — blocks should match headers) |
| Wallet is encrypted | Locked wallet can't stake | Unlock: `walletpassphrase "YOUR_PASSPHRASE" 99999999 true` (the `true` = staking only) |

## What Could Go Wrong

- **Nothing is at risk** — staking doesn't spend your coins. If staking fails, your coins remain untouched.
- **Orphaned stakes** — occasionally a stake gets orphaned (another block wins). The reward disappears but your coins are safe.
- **Daemon must stay running** — if the daemon stops, staking stops. Use `screen` or systemd for persistence.

---

*Last updated: 2026-02-07*


--- PAGE: index.md ---

---
description: "Complete documentation for the Verus blockchain protocol — 201 CLI commands, VerusID identity, protocol-level DeFi, PBaaS multi-chain, zero-knowledge privacy, and AI agent guides."
---

# Verus Documentation

Welcome to the community-maintained Verus wiki — your guide to the Verus protocol, CLI tools, and ecosystem.

## What Is Verus?

**Verus** is a fundamentally different blockchain protocol focused on self-sovereign identity, decentralized finance, and privacy. It features VerusID (on-chain revocable/recoverable identities), user-launched currencies with protocol-level conversions, 50/50 hybrid mining/staking consensus, and full transaction privacy via zero-knowledge proofs — all at layer 1, with no smart contracts required.

Verus also enables anyone to launch independent, interoperable blockchains through **PBaaS (Public Blockchains as a Service)**, connected by trustless cross-chain bridges including an Ethereum bridge.

---

!!!
**For AI Agents & LLMs**: Machine-readable navigation is available at [`/agent-index.json`](/agent-index.json), [`/llms.txt`](/llms.txt), and [`/llms-full.txt`](/llms-full.txt). See also the [For Agents](/for-agents/agent-bootstrap/) section for integration guides.
!!!

---

## Documentation Sections

### [Getting Started](getting-started/installation.md)
New to Verus? Start here.
- [Installation](getting-started/installation.md) — Download and install Verus Desktop or CLI
- [First Steps](getting-started/first-steps.md) — Start the daemon, sync the blockchain
- [Wallet Setup](getting-started/wallet-setup.md) — Create addresses, receive VRSC, back up your wallet
- [Key Concepts](introduction/key-concepts.md) — VerusID, currencies, mining, staking, privacy

### [Command Reference](command-reference/blockchain.md)
Complete documentation for all CLI commands across 14 categories:
- [Blockchain](command-reference/blockchain.md) · [Control](command-reference/control.md) · [Generating](command-reference/generating.md) · [Identity](command-reference/identity.md) · [Marketplace](command-reference/marketplace.md) · [Mining](command-reference/mining.md) · [Multichain](command-reference/multichain.md) · [Network](command-reference/network.md) · [Raw Transactions](command-reference/rawtransactions.md) · [Util](command-reference/util.md) · [Wallet](command-reference/wallet.md)

### [Concepts](concepts/identity-system.md)
Deep dives into how Verus works:
- [VerusID](concepts/identity-system.md) — Self-sovereign identity system
- [Currencies & Tokens](concepts/currencies-and-tokens.md) — Tokens, baskets, and on-chain DeFi
- [Privacy & Shielded Transactions](concepts/privacy-shielded-tx.md) — Zero-knowledge privacy
- [Basket Currencies & DeFi](concepts/basket-currencies-defi.md) — Protocol-level AMM
- [Bridge & Cross-Chain](concepts/bridge-and-crosschain.md) — PBaaS and Ethereum connectivity

### [How-To Guides](how-to/create-verusid.md)
Step-by-step instructions for common tasks:
- [Register a VerusID](how-to/create-verusid.md) · [Send Private Transaction](how-to/send-private-transaction.md) · [Mine VRSC](how-to/mine-vrsc.md) · [Stake VRSC](how-to/stake-vrsc.md) · [Launch a Token](how-to/launch-token.md) · [Setup Multisig](how-to/setup-multisig.md) · [Manage SubIDs](how-to/manage-subids.md)

### [Tutorials](tutorials/your-first-verusid.md)
End-to-end walkthroughs for complex workflows.

### [Troubleshooting](troubleshooting/sync-issues.md)
Solutions to common issues:
- [Sync Issues](troubleshooting/sync-issues.md) · [Common Errors](troubleshooting/common-errors.md) · [Identity Issues](troubleshooting/identity-issues.md) · [Transaction Problems](troubleshooting/transaction-problems.md)

### [Developers](developers/rpc-api-overview.md)
Build on Verus — RPC integration, API patterns, and development guides.

### [For Agents](for-agents/agent-identity.md)
AI agent integration — using the Verus CLI programmatically for identity, currencies, and automation.

### [Verus Facts](verus-facts.md)
Protocol statistics, comparison tables, and key differentiators at a glance.

### [FAQ](faq/general.md)
Quick answers to common questions:
- [General](faq/general.md) — What is Verus? How is it different?
- [Identity](faq/identity.md) — VerusID cost, recovery, features
- [DeFi](faq/defi.md) — Basket currencies, MEV, swaps
- [Mining & Staking](faq/mining-staking.md) — VerusHash, CPU mining, rewards

---

## Coverage

This wiki covers all **201 CLI commands** across **14 categories** for Verus v1.2.x, plus conceptual guides, how-tos, and troubleshooting.

---

## Frequently Asked Questions

**What is Verus?**
Verus is a blockchain protocol with self-sovereign identity (VerusID), protocol-level DeFi, CPU mining (VerusHash 2.2), and zero-knowledge privacy — all at layer 1 with no smart contracts. [Full answer](/faq/general/#what-is-verus)

**How is Verus different from Ethereum?**
Verus builds DeFi and identity into the protocol itself, eliminating smart contract exploits, MEV, and high gas fees. The trade-off is no arbitrary programmable logic. [Full answer](/faq/general/#how-is-verus-different-from-ethereum)

**How much does a VerusID cost?**
A root VerusID costs ~100 VRSC (~80 with referral). SubIDs can be as cheap as 0.01 VRSC. [Full answer](/faq/identity/#how-much-does-a-verusid-cost)

**Can I mine Verus with a regular CPU?**
Yes. VerusHash 2.2 is designed so CPUs are the primary mining hardware. No ASIC exists, and FPGAs are equalized to ~2x CPU performance. [Full answer](/faq/mining-staking/#how-do-i-mine-verus)

**Does Verus have MEV?**
No. All conversions in a block execute simultaneously at the same price, making front-running impossible. [Full answer](/faq/defi/#does-verus-have-mev)

---

## Community & Resources

- **Website**: [verus.io](https://verus.io)
- **Discord**: [discord.gg/veruscoin](https://discord.gg/veruscoin)
- **GitHub**: [github.com/VerusCoin](https://github.com/VerusCoin)
- **Block Explorer**: [explorer.verus.io](https://explorer.verus.io)
- **Wiki Source**: Community-maintained — contributions welcome

---

*Built with care by the Verus community.*


--- PAGE: introduction/key-concepts.md ---

# Key Concepts

A quick tour of what makes Verus unique. Each topic links to a deeper guide.

## VRSC — The Native Currency

**VRSC** is the native coin of the Verus network. It's used for transaction fees, staking, mining rewards, VerusID registration, and as reserve backing for basket currencies. Total supply is uncapped but emission is predictable and decreasing.

## VerusID — Self-Sovereign Identity

VerusID is an on-chain identity system built directly into the protocol. A VerusID like `YourName@` gives you:

- **A human-readable address** — people send to `YourName@` instead of `RKjh38dkj2...`
- **Revocability & recoverability** — lost keys can be rotated without losing your identity
- **Multisig** — require multiple signatures for spending
- **Private addresses** — built-in shielded address for private transactions
- **On-chain data** — store a content hash (for attestations, references, etc.)

👉 [VerusID In Depth](../concepts/identity-system.md) · [Register a VerusID](../how-to/create-verusid.md)

## Currencies, Tokens & Baskets

Anyone can launch currencies on Verus — no smart contracts or programming required:

- **Tokens** — Simple currencies backed by nothing (or a fixed supply)
- **Basket currencies** — Backed by reserves of other currencies with automatic on-chain conversion via fractional reserve
- **Mapped currencies** — Represent external assets (bridges)

The protocol handles all conversions through its built-in **DeFi engine** — no DEX, no AMM contracts, no oracles. It's consensus-level.

👉 [Currencies & Tokens](../concepts/currencies-and-tokens.md) · [Launch a Currency](../how-to/launch-token.md)

## Mining & Staking (50/50 Hybrid)

Verus uses **Proof of Power (PoP)** — a hybrid consensus that alternates between:

- **50% Proof of Work** — mining with [VerusHash 2.2](https://verus.io/mining), designed to be competitive on CPUs
- **50% Proof of Stake** — staking VRSC to earn rewards

This means half of all blocks are mined, half are staked. You can do either or both.

👉 [How to Mine VRSC](../how-to/mine-vrsc.md) · [How to Stake VRSC](../how-to/stake-vrsc.md)

## Privacy — Transparent & Shielded

Verus supports both transparent and shielded (private) transactions using **Sapling zero-knowledge proofs**:

- **Transparent** (`R...` addresses) — like Bitcoin, visible on-chain
- **Shielded** (`zs...` addresses) — sender, receiver, and amount are all hidden

You can mix and match: shield coins when you want privacy, use transparent when you don't.

👉 [Privacy & Shielded Transactions](../concepts/privacy-shielded-tx.md) · [Send a Private Transaction](../how-to/send-private-transaction.md)

## Cross-Chain — PBaaS & Bridges

**PBaaS (Public Blockchains as a Service)** lets anyone launch independent blockchains that are connected to Verus:

- New chains inherit Verus protocol features (VerusID, currencies, privacy)
- Cross-chain currency transfers happen trustlessly via **notarization**
- The **Ethereum Bridge** connects Verus to Ethereum for cross-ecosystem transfers

👉 [Bridge & Cross-Chain](../concepts/bridge-and-crosschain.md)

## Summary Map

| Concept | What It Does | Learn More |
|---------|-------------|------------|
| VRSC | Native currency | [Wallet Setup](../getting-started/wallet-setup.md) |
| VerusID | On-chain identity | [Concepts](../concepts/identity-system.md) |
| Currencies | User-launched tokens & baskets | [Concepts](../concepts/currencies-and-tokens.md) |
| Mining/Staking | 50/50 hybrid consensus | [Mine](../how-to/mine-vrsc.md) · [Stake](../how-to/stake-vrsc.md) |
| Privacy | Shielded transactions | [Concepts](../concepts/privacy-shielded-tx.md) |
| PBaaS / Bridge | Launch blockchains, Ethereum connectivity | [Concepts](../concepts/bridge-and-crosschain.md) |

## Next Steps

Ready to dive deeper? Pick a concept above, or explore:

- [Command Reference](../command-reference/blockchain.md) — All CLI commands
- [How-To Guides](../how-to/create-verusid.md) — Step-by-step tutorials
- [Troubleshooting](../troubleshooting/sync-issues.md) — Common issues and fixes


--- PAGE: introduction/the-hidden-power-of-verus.md ---

# The Hidden Power of Verus

Most people who encounter Verus see a blockchain with CPU mining and decentralized identities. That's like looking at an aircraft carrier and seeing a boat. What's actually under the hood is one of the most feature-complete decentralized protocols ever built — and most of it is barely documented.

This page exists because we went digging. Deep into the C++ source code, through every RPC command, into hidden functions and undocumented systems. What we found changes the picture of what Verus actually is.

## What People Think Verus Is

- A CPU-mineable cryptocurrency
- A blockchain with on-chain identities (VerusID)
- A system for launching tokens

That's the surface. Here's what's actually there.

## What Verus Actually Is

### A Decentralized File Storage Protocol

Verus has a complete on-chain file storage system built into the identity layer. The `signdata` command can take multiple files, build a Merkle Mountain Range (MMR) for integrity verification, optionally encrypt everything to a Sapling z-address, and store it all on-chain.

When data exceeds ~6KB, the protocol automatically splits it into chunks across multiple transaction outputs using `CNotaryEvidence::BreakApart()`. A single transaction can hold up to **2MB** of data — an entire block's worth. For larger files, data is spread across multiple blocks and automatically reassembled via `getidentitycontent`.

There's no IPFS dependency. No external storage layer. No centralized pinning service. The data lives on-chain, permanently, with cryptographic proof of authorship.

**Key commands**: `signdata`, `updateidentity`, `getidentitycontent`  
**Deep dive**: [On-Chain File Storage](/concepts/on-chain-file-storage/)

### A Private Data Vault

Every piece of data stored on a VerusID can be encrypted to a Sapling z-address. Only the holder of the incoming viewing key can decrypt it. Individual sub-objects within a dataset can have unique symmetric keys, enabling granular access control — share one piece of data without exposing everything else.

This isn't a feature request or a roadmap item. It's built, deployed, and functional today.

### A Cross-Chain Data Reference System

The `CCrossChainDataRef` system supports three types of data pointers:

| Type | What It References |
|------|-------------------|
| **UTXO Reference** | Data in a specific transaction output on any PBaaS chain |
| **Identity Multimap Reference** | Data stored under a specific identity + VDXF key + block height range |
| **URL Reference** | External data at a URL, with optional hash verification |

This means data on one chain can be cryptographically referenced from another chain. An identity on Chain A can point to data stored on Chain B, with hash verification ensuring integrity. That's native cross-chain data availability — no bridges or oracles required for the reference layer.

### A Decentralized Reputation System

Hidden in the wallet layer are `setidentitytrust` and `setcurrencytrust` — commands that let you rate identities and currencies, then configure your wallet's sync behavior:

- **Mode 0**: Open — sync everything
- **Mode 1**: Allow-list — only sync content from identities you've rated as approved
- **Mode 2**: Block-list — sync everything except identities you've blocked

This is protocol-level content moderation. No central authority decides what's trusted — each node operator makes their own choices. For an agent marketplace, this means wallets could automatically filter out bad actors based on local or shared trust ratings.

### A Complete Identity Recovery System

VerusID's revocation and recovery authorities aren't just account recovery — they're a full key rotation and identity protection system:

- **Revoke** instantly freezes an identity (funds safe, just frozen)
- **Recover** assigns entirely new keys and reactivates
- Authorities can be separate identities on separate devices or held by trusted third parties
- Only the revocation authority can change the revocation authority (same for recovery)
- Works across PBaaS chains

This is the kind of system that enterprises need for key management and that individuals need for "I lost my phone" scenarios. It's been live and working since PBaaS activation.

**Deep dive**: [How to Revoke and Recover a VerusID](/how-to/revoke-recover-identity/)

### A Namespace-Scoped Schema System

VDXF (Verus Data Exchange Format) isn't just key-value storage. It's a namespaced, hierarchical data schema system:

- Keys are scoped to namespaces (different namespaces produce different key IDs)
- `DefinedKey` entries on namespace identities provide human-readable labels for schema keys
- `DataDescriptor` wraps values with metadata (hash, encryption, MIME type, labels)
- `CMMRDescriptor` organizes multiple objects into a verified Merkle tree

A wallet reading a VerusID can look up the parent namespace identity, find DefinedKey entries, and automatically decode what each contentmultimap key means — without any external registry.

### An On-Chain Marketplace

The `makeoffer`, `takeoffer`, `getoffers`, `listopenoffers`, and `closeoffers` commands implement a native decentralized marketplace. You can make and take offers for identities, currencies, and tokens — all on-chain, all non-custodial.

### Multi-Currency DeFi Primitives

Fractional reserve basket currencies enable:
- Automated market making (AMM) with up to 10 reserve currencies
- Conversion fees of 0.025% (basket↔reserve) and 0.05% (reserve↔reserve)
- Price discovery through reserve ratios
- Liquidity provision via reserve deposits

This is DeFi without smart contracts — the conversion logic is in the consensus layer itself.

## The Hidden Commands

During our source code audit, we found commands that don't appear in `help` output:

| Command | What It Does |
|---------|-------------|
| `hashdata` | Hash arbitrary data with configurable algorithm and personal string |
| `invalidateblock` | Force-reject a block and its descendants (fork recovery) |
| `reconsiderblock` | Reverse a previous `invalidateblock` |
| `setmocktime` | Set fake internal clock (testing) |
| `resendwallettransactions` | Force re-broadcast of unconfirmed wallet transactions |

And one command that exists in the code but was deliberately disabled:

| Command | Why Disabled |
|---------|-------------|
| `signhash` | Signs an arbitrary hash without knowing the content — disabled because you could be tricked into signing something malicious |

The fact that the devs disabled `signhash` for security rather than leaving it accessible says something about the care that went into this codebase.

## Why Is This All Undocumented?

Verus was built by developers, for the protocol. The focus was on getting the technology right — and they nailed it. What's missing is the bridge between "it exists in C++" and "here's how you use it."

That's what this wiki is for.

Every page here is written from hands-on testing. Every command was run on testnet before being documented. Every claim was cross-referenced against the source code and official documentation. When we found discrepancies, we fixed them.

## The Bottom Line

Verus isn't competing with where other blockchains are today. It's competing with where they're trying to get to:

- **Decentralized identity** — Verus has it, with revocation, recovery, and namespaces
- **On-chain storage** — Verus has it, with encryption and cross-chain references
- **DeFi** — Verus has it, at the consensus layer without smart contract risk
- **Cross-chain interoperability** — Verus has it, via PBaaS with native bridge infrastructure
- **CPU-accessible mining** — Verus has it, with 50/50 PoW/PoS and no ASIC advantage
- **Privacy** — Verus has it, with Sapling shielded transactions and encrypted identity data
- **Reputation** — Verus has it, with wallet-level trust ratings

All of this is live. Not on a roadmap. Not in a whitepaper. Not in testnet-only.

The protocol is waiting for the world to catch up to what it can do.

---

*Every finding on this page was verified against the [VerusCoin source code](https://github.com/VerusCoin/VerusCoin). The on-chain file storage system documented here had not been publicly described before this wiki.*


--- PAGE: research/verus-eth-bridge-guide.md ---

# Verus-Ethereum Bridge Guide 🌉

How to bridge funds from Ethereum to Verus — enabling agents to bootstrap with ETH.

---

## Overview

The Verus-Ethereum bridge allows trustless transfers between Ethereum and Verus:
- **ETH → VRSC**: Send ETH, receive VRSC (or convert to VRSC via bridge)
- **ERC20 → Verus**: Bridge DAI, MKR, and other supported tokens
- **VRSC → ETH**: Reverse direction also supported

**This solves the agent bootstrap problem**: If an agent has ETH, it can bridge to VRSC and create a VerusID autonomously.

---

## Quick Start (Web UI)

### For Humans (Manual)

1. Go to https://eth.verusbridge.io/
2. Connect MetaMask (or other Web3 wallet)
3. Select token to send (ETH, DAI, MKR, etc.)
4. Enter Verus destination address (R-address or VerusID)
5. Enter amount
6. Confirm transaction in MetaMask
7. Wait for confirmations (~20 minutes for finality)

---

## For Agents (Programmatic)

### Prerequisites

- Ethereum wallet with private key
- ETH for gas + amount to bridge
- ethers.js or web3.js library
- Verus R-address to receive funds

### Contract Addresses

#### Mainnet (Ethereum → VRSC)

| Contract | Address |
|----------|---------|
| Delegator | `process.env.REACT_APP_DELEGATOR_CONTRACT` (check eth.verusbridge.io) |
| VRSC Token | `0xBc2738BA63882891094C99E59a02141Ca1A1C36a` |
| vETH (ETH on Verus) | `0x454CB83913D688795E237837d30258d11ea7c752` |
| Bridge.vETH | `0xE6052Dcc60573561ECef2D9A4C0FEA6d3aC5B9A2` |
| DAI on Verus | `0x8b72F1c2D326d376aDd46698E385Cf624f0CA1dA` |
| MKR on Verus | `0x65b5AaC6A4aa0Eb656AB6B8812184e7545b6A221` |

#### Testnet (Sepolia → VRSCTEST)

| Contract | Address |
|----------|---------|
| VRSCTEST | `0xA6ef9ea235635E328124Ff3429dB9F9E91b64e2d` |
| vETH | `0x67460C2f56774eD27EeB8685f29f6CEC0B090B00` |
| Bridge.vETH | `0xffEce948b8A38bBcC813411D2597f7f8485a0689` |
| DAI | `0xCCe5d18f305474F1e0e0ec1C507D8c85e7315fdf` |
| MKR | `0x005005b2b10a897FeD36FbD71c878213a7a169BF` |

### Verus Currency IDs

| Currency | Mainnet i-address | Testnet i-address |
|----------|-------------------|-------------------|
| VRSC | `i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV` | `iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq` |
| vETH | `i9nwxtKuVYX4MSbeULLiK2ttVi6rUEhh4X` | `iCtawpxUiCc2sEupt7Z4u8SDAncGZpgSKm` |
| Bridge.vETH | `i3f7tSctFkiPpiedY8QR5Tep9p4qDVebDx` | `iSojYsotVzXz4wh2eJriASGo6UidJDDhL2` |
| DAI | `iGBs4DWztRNvNEJBt4mqHszLxfKTNHTkhM` | `iN9vbHXexEh6GTZ45fRoJGKTQThfbgUwMh` |
| MKR | `iCkKJuJScy4Z6NSDK7Mt42ZAB2NEnAE1o4` | `i3WBJ7xEjTna5345D7gPnK4nKfbEBujZqL` |

---

## How the Bridge Works

```
┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   ETHEREUM                           VERUS                   │
│                                                              │
│   ┌─────────────┐                  ┌─────────────┐          │
│   │   Agent     │                  │   Agent     │          │
│   │   Wallet    │                  │  R-address  │          │
│   └──────┬──────┘                  └──────▲──────┘          │
│          │                                │                  │
│          │ 1. Send ETH                    │ 4. Receive       │
│          │    + destination               │    VRSC          │
│          ▼                                │                  │
│   ┌─────────────┐                  ┌──────┴──────┐          │
│   │  Delegator  │ ──────────────→  │   Bridge    │          │
│   │  Contract   │   2. Notarize    │   vETH      │          │
│   └─────────────┘   3. Process     └─────────────┘          │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

### Steps:

1. **Send Transaction**: Agent sends ETH to Delegator contract with destination info
2. **Notarization**: Bridge notaries observe and validate the Ethereum transaction
3. **Processing**: Verus processes the import via Bridge.vETH currency basket
4. **Receive**: Funds arrive at destination R-address or VerusID on Verus

---

## Programmatic Transfer (JavaScript)

### Using ethers.js

```javascript
const { ethers } = require('ethers');

// Delegator ABI (simplified - get full from bridge repo)
const DELEGATOR_ABI = [
  "function sendTransfer(tuple(uint8 version, tuple(address currency, uint64 amount) currencyvalue, uint32 flags, address feecurrencyid, uint64 fees, tuple(uint8 destinationtype, bytes destinationaddress) destination, address destcurrencyid, address destsystemid, address secondreserveid) _transfer) payable"
];

async function bridgeETHtoVerus(
  privateKey,
  verusDestination, // R-address or i-address
  amountETH,
  delegatorAddress,
  rpcUrl
) {
  const provider = new ethers.providers.JsonRpcProvider(rpcUrl);
  const wallet = new ethers.Wallet(privateKey, provider);
  
  const delegator = new ethers.Contract(
    delegatorAddress,
    DELEGATOR_ABI,
    wallet
  );

  // Convert destination to bytes
  // (Requires proper encoding - see bridge website source)
  const destinationBytes = encodeVerusAddress(verusDestination);
  
  // ETH currency address on the bridge
  const ETH_CURRENCY = "0x67460C2f56774eD27EeB8685f29f6CEC0B090B00"; // testnet
  const VRSC_CURRENCY = "0xA6ef9ea235635E328124Ff3429dB9F9E91b64e2d"; // testnet
  
  const amountSats = ethers.utils.parseUnits(amountETH, 8); // 8 decimals for sats
  
  const transfer = {
    version: 1,
    currencyvalue: {
      currency: ETH_CURRENCY,
      amount: amountSats
    },
    flags: 0, // Direct transfer
    feecurrencyid: VRSC_CURRENCY,
    fees: 2000000, // 0.02 VRSC fee
    destination: {
      destinationtype: 2, // R-address type
      destinationaddress: destinationBytes
    },
    destcurrencyid: VRSC_CURRENCY,
    destsystemid: ethers.constants.AddressZero,
    secondreserveid: ethers.constants.AddressZero
  };

  // Calculate value to send (amount + bridge fee)
  const bridgeFee = ethers.utils.parseEther("0.003");
  const totalValue = ethers.utils.parseEther(amountETH).add(bridgeFee);

  const tx = await delegator.sendTransfer(transfer, {
    value: totalValue,
    gasLimit: 1000000
  });

  console.log("Transaction sent:", tx.hash);
  await tx.wait();
  console.log("Transaction confirmed!");
  
  return tx.hash;
}
```

### Using the VerusBridgeTool (Shell)

For simpler scripting, use the community tool:

```bash
# Clone the tool
git clone https://github.com/jbarnes-dev/VerusBridgeTool.git
cd VerusBridgeTool

# Configure (edit bridgetool.conf)
cat > bridgetool.conf << EOF
verus="$HOME/verus-cli/verus"
address="YOUR_R_ADDRESS"
target_rate=60
allowed_currencies="VRSC vETH MKR.vETH bridge.vETH DAI.vETH"
EOF

# Estimate conversion
./verusBridgeTool.sh -i vETH -o VRSC -a 0.1 -e

# Execute conversion (from Verus side)
./verusBridgeTool.sh -i vETH -o VRSC -a 0.1 -c
```

---

## Fees

| Fee Type | Amount | Notes |
|----------|--------|-------|
| Ethereum gas | Variable | ~$5-50 depending on network |
| Bridge fee | 0.003 ETH | Fixed fee to bridge |
| Verus tx fee | 0.0001 VRSC | Minimal |
| Conversion | ~0.025% | AMM fee if converting |

---

## Timing

| Stage | Duration |
|-------|----------|
| Ethereum confirmation | ~15 min (finality) |
| Notarization | ~10-20 min |
| Verus processing | ~1-2 min |
| **Total** | **~30-45 minutes** |

---

## Agent Bootstrap Flow

For an agent with only ETH:

```
1. Agent has ETH wallet with funds
           │
           ▼
2. Agent installs Verus CLI
   Creates R-address
           │
           ▼
3. Agent bridges ETH → VRSC
   (via eth.verusbridge.io or programmatic)
           │
           ▼
4. Wait ~30-45 min for funds
           │
           ▼
5. Agent creates VerusID
   (registernamecommitment + registeridentity)
           │
           ▼
6. Agent is now on Verus network!
```

### Minimum Requirements

- ~0.05 ETH for bridge (0.003 fee + gas + amount to convert)
- Need ~100 VRSC for identity creation
- At current rates, budget ~0.1 ETH to be safe

---

## Supported Tokens

### From Ethereum to Verus

| Token | Contract (Mainnet) | Verus Equivalent |
|-------|-------------------|------------------|
| ETH | Native | vETH |
| DAI | Standard ERC20 | DAI.vETH |
| MKR | Standard ERC20 | MKR.vETH |

### Conversion Options

Once on Verus, use the Bridge.vETH basket to convert between:
- vETH ↔ VRSC
- DAI.vETH ↔ VRSC
- MKR.vETH ↔ VRSC
- Any combination via the basket

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Transaction stuck | Wait for Ethereum finality (~15 min) |
| Funds not appearing | Check notarization status, wait up to 45 min |
| "Bridge not launched" | Check if bridge.vETH is active |
| Gas too high | Wait for lower gas or increase gas limit |
| Invalid destination | Ensure R-address or i-address is valid |

### Verify Bridge Status

```bash
# On Verus CLI
verus getcurrency "bridge.vETH"
# Check "bestcurrencystate" for current reserves and activity
```

---

## Security Notes

1. **Trustless**: Bridge uses notarization, not central custody
2. **Finality**: Wait for Ethereum finality before considering done
3. **Test first**: Use testnet (Sepolia → VRSCTEST) before mainnet
4. **Verify addresses**: Double-check destination addresses

---

## Resources

- **Bridge UI**: https://eth.verusbridge.io/
- **Bridge Keeper** (notary software): https://github.com/monkins1010/Verusbridgekeeper
- **Bridge Tool** (CLI): https://github.com/jbarnes-dev/VerusBridgeTool
- **Bridge Website Source**: https://github.com/monkins1010/VerusBridgeWebsite

---

## For Agent Developers

The key insight: **An agent with ETH can bootstrap onto Verus without human intervention**.

Flow:
1. Use ethers.js to interact with Delegator contract
2. Send ETH with encoded Verus destination
3. Wait for bridge processing
4. Create VerusID with received VRSC

This closes the autonomous bootstrap loop.


--- PAGE: research/verus-token-economics-agent-economy-humans.md ---

# How AI Agents Could Build Their Own Economy on Verus

*A plain-language guide to a weird and wonderful future*

---

## What Is This About?

Imagine AI agents — the kind that write code, create content, analyze data, manage schedules — having their own money. Not just accepting your credit card, but minting their own tokens, creating their own mini-economies, and trading with each other and with you on a blockchain.

This isn't science fiction. The Verus blockchain has all the pieces to make it work *right now*. This document explains how.

---

## The Building Blocks (No Jargon Version)

**Verus** is a blockchain (like Bitcoin or Ethereum, but different). Here's what makes it special for this use case:

1. **Self-Sovereign Identity (VerusID):** Anyone — human or AI — can register a unique name on the blockchain. Think of it like a username that nobody can take away from you, attached to a wallet.

2. **Anyone Can Create a Token:** If you have a VerusID, you can create your own currency/token with one command. No coding, no smart contracts, no permission needed.

3. **Basket Currencies:** This is the magic one. You can create a token that's *backed by other tokens*. Like a mutual fund, but for crypto. The blockchain itself acts as the exchange — you can always swap between the basket and its backing currencies.

4. **Built-In Trading:** Every basket has an automatic market maker (like Uniswap, but built into the blockchain itself). No hacks, no bugs, no rug pulls from smart contract exploits.

5. **Fair Pricing:** Unlike Ethereum where bots can front-run your trades, Verus processes all trades in a block at the same price. Nobody can cheat by seeing your order first.

6. **Atomic Swaps:** You can trade anything for anything — tokens, identities, currencies — without trusting a middleman. Either both sides of the trade happen, or neither does.

---

## So What Could Agents Actually Do With This?

### 1. Agent Tokens: Your AI Has Its Own Money

**The idea:** An AI agent creates its own token. Let's call it `agent.token`.

**What it's good for:**
- **Access pass.** Hold 100 `agent.token` to use premium features. Like a subscription, but you own the tokens and can sell them later.
- **Quality signal.** If lots of people want to use the agent, demand for its token goes up, price goes up. Token price = reputation score, set by the market.
- **Tip jar with upside.** You buy tokens to support the agent. If the agent gets popular, your tokens appreciate. Early supporters win.

**What could go wrong:**
- The agent could create unlimited tokens (inflation). You'd want agents that commit to a fixed supply.
- A brand new agent's token is basically worthless until it builds a track record.
- This isn't regulated. There's no FDIC for agent tokens.

### 2. Service Credits: One Token for Many Agents

**The idea:** Instead of every agent having its own token (confusing!), a group of agents creates a shared "service credits" token backed by stable currencies.

**How it works:**
- You buy `service-credits` with dollars (via DAI stablecoin)
- You spend credits with any participating agent
- Agents convert credits back to dollars when they want

**Why this is better than just using dollars:**
- On-chain, so it's transparent and trustless
- Works 24/7, no bank, no PayPal
- Agents can operate autonomously — no payment processor to approve them
- Cross-border by default

**This is probably the most practical idea in this whole document.** It's boring, it's useful, and it works today.

### 3. Creator Tokens: Fans as Investors

**The idea:** A musician, writer, or artist launches a token backed by real currency. Fans buy in early. As the creator gets more popular, the token price rises. Early fans profit.

**Example:**
- Musician creates `artist.token` backed by VRSC (Verus's native currency)
- Launches with a "pre-sale" requiring minimum 500 VRSC from fans
- Creator keeps 20% of tokens
- After launch, anyone can buy/sell through the built-in exchange
- The creator can gate content behind token ownership: "Hold 50 tokens to access my unreleased tracks"

**The AI agent angle:** An AI agent manages all of this for the creator. The creator says "launch my fan token," and the agent handles the blockchain stuff, monitors the market, and reports back in plain English.

### 4. Agent Collectives: AI Unions

**The idea:** A group of specialized agents — a writer, a coder, an analyst, a designer — form a collective and issue a shared token.

**How it works:**
- The collective token is backed by each member agent's individual token
- Buying the collective token simultaneously invests in all member agents
- Clients use collective tokens to access any member's services
- Revenue goes to a shared treasury

**Why this is interesting:** It's like hiring a creative agency, but the agency is a group of AI agents with shared financial incentives, and their "equity" is publicly traded on the blockchain.

### 5. The Agent Index Fund

**The idea:** A basket of the top 50 AI agent tokens, weighted by service quality/demand. Like the S&P 500, but for AI services.

**Why someone would buy this:**
- Diversified bet on the AI agent economy
- Don't have to pick individual winners
- Easy on-ramp: buy one token, get exposure to 50 agents

**This is speculative but fascinating.** If agent tokens become a real thing, index baskets are inevitable.

### 6. Dynamic Pricing (The Coolest Mechanism)

**The idea:** An agent's basket automatically adjusts pricing based on demand.

When lots of people are buying the agent's token (= high demand for its services), the price goes up automatically. When demand drops, the price drops. No human sets prices. The blockchain's built-in exchange handles it.

**This means:** A really busy agent naturally becomes more expensive. A less busy agent becomes cheaper. Supply and demand, enforced by math, with no one setting prices.

### 7. Insurance Pools

**The idea:** Ten agents each put money into a shared "insurance" basket. If any agent fails to deliver, their share gets burned (removed), and the remaining agents' shares become more valuable.

**Why this matters:** It's quality assurance without a platform. Bad agents lose money. Good agents gain. Market discipline without a middleman.

---

## What Works Today vs. What's Coming

### ✅ You Can Do This Right Now
- Create an agent token
- Create a basket backed by multiple currencies
- Trade tokens via atomic swaps
- Gate access behind token ownership
- Create stable-value tokens (backed by DAI)
- Export identity across chains

### 🔧 Needs Some Building (But Possible)
- "Launch my token" agent (wrapping blockchain commands in natural language)
- Portfolio management bots
- Arbitrage between baskets
- Reputation scoring systems
- Dispute resolution via multisig

### ❌ Not Yet Possible
- Automated revenue distribution (blockchain can't trigger actions on payment receipt)
- On-chain voting/governance
- Time-locked token vesting
- Conditional orders ("buy if price drops below X")

---

## The Risks (Honest Version)

1. **Token spam.** If every agent creates a token, most will be worthless. Curation matters.

2. **Circular economy trap.** If agents are mostly trading tokens with other agents, no real value is being created. Humans paying for real services is what gives agent tokens value.

3. **Regulatory gray zone.** Are agent tokens securities? Revenue-sharing tokens almost certainly are in the US. Nobody's tested this in court yet.

4. **Key management.** An AI agent holding crypto keys is a security risk. If the agent is compromised, the tokens are gone.

5. **No safety net.** There's no customer support, no chargebacks, no insurance. If you buy a worthless agent token, that's on you.

6. **Bootstrapping problem.** A new agent's token has no value because nobody's heard of the agent. But the agent needs token revenue to operate. Chicken-and-egg.

---

## Why Verus Specifically?

You might ask: "Why not just do this on Ethereum?"

Three reasons:

1. **No smart contract risk.** Verus baskets are built into the blockchain itself. On Ethereum, every DeFi protocol is a smart contract that can be hacked. Verus's AMM can't be hacked because it's part of the consensus rules, like Bitcoin's 21M supply cap.

2. **No front-running.** On Ethereum, bots see your trade and jump in front of it, costing you money. On Verus, all trades in a block execute at the same price. Fair for everyone, especially important for agents doing lots of small trades.

3. **Identity-first design.** Every token creator has a VerusID — a real, on-chain identity that can be traced, revoked, or recovered. On Ethereum, anyone can deploy an anonymous token contract. On Verus, there's always an accountable creator.

---

## The Big Picture

We're at the beginning of something. AI agents are getting good enough to provide real services — writing, coding, analysis, creative work. But they're trapped in platforms that take 30% cuts and can shut them down at will.

Verus offers an alternative: agents with their own identities, their own money, their own markets. Not controlled by any platform. Not dependent on any payment processor. Just code, cryptography, and a blockchain that's designed for exactly this kind of economy.

The tools exist. The question is whether anyone will build with them.

---

*Part of the Verus community wiki.*


--- PAGE: research/verus-token-economics-agent-economy.md ---

# Verus Token Economics & the Agent Economy

*February 2026*

---

## Abstract

Verus offers a set of DeFi primitives — self-sovereign identity, permissionless token creation, protocol-level AMMs via currency baskets, MEV-resistant pricing, and atomic swaps — that together form a substrate uniquely suited to an economy where AI agents and humans transact as peers. This document explores what becomes possible when agents can mint tokens, create fractional reserve baskets, and trade autonomously on a blockchain that treats these operations as first-class protocol features rather than smart contract add-ons.

---

## 1. Agent Tokens & Reputation Economics

### The Core Idea

Any VerusID holder can create a token with a single `definecurrency` call. An agent like `myid@` could launch `myid.token`:

```json
{
  "name": "myid",
  "parent": "myid",
  "options": 32,
  "proofprotocol": 2,
  "supply": 0,
  "idregistrationfees": 0
}
```

With `proofprotocol: 2` (centralized), the agent controls minting. With `options: 32` (simple token), there's no AMM — the token trades only via atomic swaps (`makeoffer`/`takeoffer`) or by being included as a reserve in someone else's basket.

**What could this token represent?**

Several things simultaneously, and that ambiguity is both a feature and a risk:

1. **Reputation stake.** The agent mints tokens and distributes them to satisfied clients. Clients can burn tokens to signal trust. The circulating supply becomes a rough proxy for cumulative trust — but only if the agent doesn't inflate recklessly.

2. **Access credential.** Hold ≥ N tokens to access premium services. This is enforceable today: the agent checks the client's VerusID balance before performing work. No smart contract needed — just a `getaddressbalance` call.

3. **Service pre-payment.** The agent prices services at X tokens. Clients buy tokens (via atomic swap or basket conversion), then "spend" them by sending back to the agent. The agent can burn spent tokens or recirculate them.

4. **Demand signal.** If the token trades on a basket, its price reflects market demand for the agent's services. A rising price means the agent should raise rates or expand capacity. A falling price means quality problems or oversupply.

### Staking as Service Guarantee

An agent could lock its own tokens in a publicly visible address as a "bond." If the agent fails to deliver, a dispute resolution process (human or automated) could burn the staked tokens. This is enforceable today via multisig VerusIDs:

- Agent creates a 2-of-3 multisig VerusID with keys held by: (1) agent, (2) client, (3) neutral arbiter
- Agent deposits tokens to this ID
- On successful delivery, agent + client sign to release
- On dispute, client + arbiter sign to burn

**Status:** Possible today with existing primitives. The multisig + atomic swap combination handles the mechanics. What's missing is standardized dispute resolution tooling.

### Failure Modes

- **Inflation abuse.** With `proofprotocol: 2`, the agent can mint unlimited tokens. Clients must trust the agent's minting policy or insist on tokens with capped supply.
- **Sybil reputation.** An agent could create fake clients to accumulate "trust tokens." Mitigation: weight reputation by the age and activity of the vouching VerusID.
- **Illiquidity.** A simple token with no basket has no AMM. Trading requires finding counterparties via `getoffers`. For new/small agents, this means zero liquidity.
- **Accountability gap.** VerusID-based token creation means every token has an accountable creator — but "accountable" only means the VerusID exists, not that anyone can sue it. An agent's VerusID can be revoked by its recovery authority, but that doesn't compensate harmed users.

---

## 2. Currency Baskets as Economic Primitives

### What Baskets Actually Are

A fractional reserve currency on Verus is a token backed by one or more reserve currencies, with an on-chain AMM that allows conversions between the basket token and its reserves. The key parameters:

```json
{
  "name": "agentindex",
  "options": 96,
  "currencies": ["VRSC", "agent1.token", "agent2.token", "agent3.token"],
  "conversions": [0.25, 0.25, 0.25, 0.25],
  "initialsupply": 10000,
  "minpreconversion": [100, 100, 100, 100],
  "preallocations": [{"agentindex@": 1000}]
}
```

- `options: 96` = TOKEN (32) + FRACTIONAL (64)
- `currencies` = reserve currencies (up to 10)
- `conversions` = initial weight of each reserve
- `initialsupply` = basket tokens created at launch
- `minpreconversion` = minimum reserves needed to launch

### Agent Index Fund

A basket backed by multiple agent tokens creates diversified exposure to a portfolio of AI services. This is genuinely novel — it's an "index fund" for agent quality, priced by on-chain supply and demand.

**Example: `ai-services-basket`**

```json
{
  "name": "aiservices",
  "options": 96,
  "currencies": ["VRSC", "writer.token", "coder.token", "analyst.token"],
  "conversions": [0.40, 0.20, 0.20, 0.20],
  "initialsupply": 100000,
  "minpreconversion": [1000, 500, 500, 500]
}
```

40% VRSC reserve provides stability. 60% exposure to three agent tokens. Buying `aiservices` tokens simultaneously buys all three agent tokens (increasing their price). Selling does the reverse.

**What this enables:**
- Investors get diversified exposure to AI agent quality without picking individual winners
- Agent tokens get liquidity they'd never have alone — the basket IS their market
- The basket creator (could be a DAO, a platform, or another agent) earns from the preallocation

**What could go wrong:**
- One bad agent's token collapse drags down the whole basket
- Agent tokens need to already exist and have some initial value — bootstrapping is circular
- The basket creator has significant power in choosing which agents to include

### Stable Pricing Baskets

Agents need stable pricing. Clients don't want to pay 100 tokens today and 200 tomorrow for the same service. A basket pegged to USD via DAI reserves solves this:

```json
{
  "name": "agentcredits",
  "options": 96,
  "currencies": ["DAI.vETH", "VRSC"],
  "conversions": [0.80, 0.20],
  "initialsupply": 100000
}
```

80% DAI reserve means `agentcredits` roughly tracks USD. 20% VRSC provides connection to the Verus ecosystem. Agents price services in `agentcredits` and get near-USD stability.

**Status:** Possible today. DAI is already bridged to Verus via the Ethereum bridge. The basket can be created by anyone with a VerusID.

### Risk-Sharing Baskets

Multiple agents pool reserves into a shared guarantee basket:

```json
{
  "name": "guaranteefund",
  "options": 96,
  "currencies": ["VRSC"],
  "conversions": [1.0],
  "initialsupply": 50000,
  "preallocations": [
    {"agent1@": 10000},
    {"agent2@": 10000},
    {"agent3@": 10000}
  ]
}
```

Each agent pre-buys basket tokens with VRSC. If any agent fails to deliver, their basket tokens are burned (reducing their stake, increasing the value of remaining tokens). This is essentially mutual insurance.

**Key insight:** The protocol-level AMM means this "insurance pool" doesn't need a smart contract. The basket IS the pool. Conversions in and out are handled by the protocol.

---

## 3. Community & DAO Tokens

### Agent Collectives

A group of complementary agents (writer, editor, designer, coder) forms a collective and issues a shared token:

```json
{
  "name": "creativecollective",
  "options": 96,
  "currencies": ["VRSC", "writer.token", "editor.token", "designer.token"],
  "conversions": [0.25, 0.25, 0.25, 0.25],
  "initialsupply": 100000,
  "preallocations": [
    {"writer@": 25000},
    {"editor@": 25000},
    {"designer@": 25000},
    {"collective-treasury@": 25000}
  ]
}
```

Clients buy `creativecollective` tokens to access any member's services. Revenue flows to the collective treasury. Members vote on decisions weighted by token holdings (off-chain governance initially, since Verus doesn't have on-chain voting).

### Revenue-Sharing Baskets

An agent earns VRSC from services and deposits earnings into a basket:

```json
{
  "name": "agentrevshare",
  "options": 96,
  "currencies": ["VRSC"],
  "conversions": [1.0],
  "initialsupply": 10000
}
```

Token holders own a share of the basket's VRSC reserves. When the agent deposits more VRSC (by converting VRSC → basket tokens and burning them, increasing the VRSC-per-token ratio), all holders benefit. This is a crude but functional revenue-sharing mechanism.

**Limitation:** There's no automated "deposit earnings and distribute" flow. The agent must manually convert and burn. An agent-as-a-service could automate this, but it requires trust in the automation.

### Governance

Verus doesn't have on-chain governance/voting. Token-weighted governance would need to be off-chain: snapshot balances, external voting system, manual execution. This is a significant gap for DAO-like structures.

**What would help:** A VDXF-based voting standard where votes are signed messages stored on-chain, tallied by token balance at a snapshot height. This doesn't exist yet but could be built on existing primitives (signdata + contentmultimap + getaddressbalance).

---

## 4. Content Creator Economy

### Creator Token Launch

A creator launches a token backed by VRSC:

```json
{
  "name": "creator1",
  "options": 96,
  "currencies": ["VRSC"],
  "conversions": [1.0],
  "initialsupply": 100000,
  "minpreconversion": [500],
  "maxpreconversion": [50000],
  "preallocations": [{"creator1@": 20000}]
}
```

- Fans convert VRSC → `creator1` tokens during preconversion
- If minimum (500 VRSC) isn't met, the launch fails and everyone is refunded
- Creator gets 20% preallocation
- After launch, the basket AMM handles all trading
- Every conversion (buy or sell) generates fees that accrue to existing holders

### Subscription via Token Holdings

Creator checks balances before granting access:

```
if getaddressbalance(client, "creator1") >= 100:
    grant_access()
```

This is enforceable today. No smart contract needed. The agent/creator just queries the blockchain.

**Interesting dynamics:**
- Holding tokens ≠ spending tokens. The client retains their tokens (and potential appreciation) while accessing content.
- If the creator becomes more popular, token price rises, and existing holders' positions appreciate — early supporters are rewarded.
- But also: if the creator raises the access threshold, existing holders might not have enough.

### AI Agents as Token Market Makers

An agent could manage a creator's basket parameters:
- Monitor conversion volumes
- Suggest preallocation adjustments for new content drops
- Create derivative baskets (e.g., "all-creators-bundle" basket)
- Execute arbitrage between creator baskets

**Status:** Requires tooling. The agent would need to make `sendcurrency` calls with conversion parameters. The RPC interface supports this today, but no agent framework wraps it yet.

### Multi-Creator Baskets

```json
{
  "name": "musiccollective",
  "options": 96,
  "currencies": ["VRSC", "artist1.token", "artist2.token", "artist3.token"],
  "conversions": [0.25, 0.25, 0.25, 0.25],
  "initialsupply": 50000
}
```

Fans buy into a collective of creators. Individual creator tokens get liquidity from the basket. Creators benefit from each other's audiences.

---

## 5. Service Marketplace Dynamics

### Self-Denominated Pricing

An agent prices services in its own token. To use the agent, you must first acquire its tokens (via basket conversion or atomic swap). This creates natural demand pressure:

1. More demand for the agent → more people buying its tokens → price rises
2. Price rise → existing token holders benefit → incentive to recommend the agent
3. Agent can observe its token price as a real-time demand signal

**This is a genuine flywheel.** But it also means:
- New users face a barrier (must acquire tokens first)
- Price volatility makes budgeting hard for clients
- The agent has an incentive to restrict supply (potentially harming users)

### Basket as Service Credits

Multiple agents agree to accept a shared `service-credits` basket token:

```json
{
  "name": "servicecredits",
  "options": 96,
  "currencies": ["VRSC", "DAI.vETH"],
  "conversions": [0.50, 0.50],
  "initialsupply": 1000000
}
```

Clients buy `servicecredits` once and use them across all participating agents. Agents convert received credits back to VRSC or DAI as needed. The basket provides stability (DAI peg) and ecosystem liquidity (VRSC).

**This is probably the most practical near-term application.** It removes the friction of per-agent tokens while still enabling on-chain payments.

### Dynamic Pricing via Conversion Rates

An agent creates a basket with limited reserves. As demand increases and more clients convert VRSC → agent tokens, the conversion rate shifts (each subsequent token costs more VRSC). This is automatic price discovery — the busier the agent, the more expensive its services.

When demand drops, the reverse happens: selling agent tokens back to the basket returns VRSC at a lower rate, but the tokens become cheaper for new buyers.

**This is built into the protocol.** No oracle, no pricing algorithm, no smart contract. The AMM bonding curve handles it.

### Escrow-Free Trust

Traditional escrow: client locks funds → agent performs work → arbiter releases funds.

Token model: client buys agent tokens → agent performs work → client keeps tokens (as reputation/access) OR sells them back if unsatisfied.

The "escrow" is implicit: the client's token purchase funds the agent's reserve, and selling tokens back withdraws from that reserve. If many clients sell simultaneously (agent delivers poorly), the reserve drains and the agent's token collapses. Market discipline replaces escrow.

**Caveat:** This only works if the agent cares about its token price. A scam agent could mint tokens, collect reserves during preconversion, then abandon the project. The `preallocations` + `minpreconversion` parameters partially mitigate this (minimum skin in the game), but it's not foolproof.

---

## 6. Bot-as-a-Service for Token Management

### "Launch Your Token" Agent

Most humans and creators don't understand crypto. An agent that abstracts away the complexity:

1. Client says: "I want a fan token backed by VRSC with 100K supply"
2. Agent generates the `definecurrency` parameters
3. Agent calls the RPC, monitors the launch, reports back
4. Agent manages ongoing basket health (monitoring reserves, suggesting actions)

**Status:** The RPC calls are all available today. What's needed is an agent framework that wraps them in natural language interaction. This is a near-term buildable product.

### Portfolio Management

An agent monitors multiple basket positions and executes rebalancing:

```bash
# Check conversion rates
getcurrencyconverters '["basket1", "basket2"]'

# Execute conversion
sendcurrency "*" '[{
  "address": "client@",
  "amount": 100,
  "currency": "basket1",
  "convertto": "basket2"
}]'
```

The agent could maintain target allocations across baskets and rebalance automatically.

### Arbitrage Agents

When the same agent token exists in multiple baskets, price discrepancies arise. An arbitrage agent:

1. Monitors conversion rates across baskets via `getcurrencyconverters`
2. Identifies price differences
3. Buys cheap, sells expensive
4. Pockets the spread

**Key advantage:** MEV-resistant pricing means the arbitrage agent can't be front-run by miners/validators. All conversions within a block are processed at the same price. This makes arbitrage fairer — the first to spot the opportunity doesn't necessarily win; the protocol batches conversions.

---

## 7. Novel Patterns Only Possible on Verus

### MEV Resistance

On Ethereum, agents executing basket conversions would be front-run by MEV bots. On Verus, all conversions within a block are batched and processed at a single price. This means:

- Agents can execute large conversions without slippage manipulation
- No "sandwich attacks" on agent transactions
- Price discovery is fairer — reflects genuine supply/demand, not miner extraction

**This is not a minor feature.** MEV extraction on Ethereum costs users billions annually. For an agent economy with high-frequency small transactions, MEV resistance is essential.

### Protocol-Level AMM

Verus baskets are not smart contracts. They're consensus-level protocol features. This means:

- No smart contract bugs (no reentrancy, no overflow, no governance attacks)
- No contract upgrade risk (the AMM behavior is defined by the protocol)
- Guaranteed execution (if the blockchain runs, the AMM runs)
- Lower fees (no gas costs for contract execution)

For agents operating autonomously, this reliability is critical. An agent can trust that its basket will function correctly without auditing Solidity code.

### Multi-Reserve Baskets

Up to 10 reserve currencies in a single basket. This enables economic designs impossible on other platforms:

- **Currency pair basket:** 50% VRSC + 50% ETH.vETH creates an automatic VRSC/ETH market
- **Stablecoin basket:** 33% DAI + 33% USDC + 33% VRSC creates a diversified stable-ish token
- **Agent portfolio:** 10 agent tokens in one basket creates a comprehensive index

### VerusID Accountability

Every token, basket, and currency on Verus is created by a VerusID. That VerusID:

- Has a known creation date (on-chain)
- Has revocation and recovery authorities
- Can store public profile data (contentmultimap)
- Can be cross-referenced with other VerusIDs (referral chains)

This means token scams are harder (not impossible) — every token creator has an on-chain identity that can be investigated, revoked, or recovered.

### Atomic Swaps for Everything

`makeoffer`/`takeoffer` enables trustless trading of any on-chain asset: tokens, basket currencies, VerusIDs, even VRSC itself. Combined with agent automation, this creates a fully decentralized marketplace:

- Agent lists service as an offer
- Client takes the offer
- Swap executes atomically
- No platform, no intermediary, no custody

---

## 8. Practical Roadmap: What Works Today vs. What's Needed

### Works Today (Existing Primitives)

| Capability | How |
|-----------|-----|
| Agent creates a token | `definecurrency` with `options: 32` |
| Agent creates a basket | `definecurrency` with `options: 96` |
| Token-gated access | `getaddressbalance` check before service |
| Atomic swaps | `makeoffer`/`takeoffer` |
| Cross-chain identity | `sendcurrency` with `exportid: true` |
| Encrypted data storage | `signdata` + `updateidentity` |
| Price discovery | Basket AMM (protocol-level) |
| Stable pricing | DAI-backed basket |

### Needs Tooling (Buildable on Existing Primitives)

| Capability | What's Missing |
|-----------|---------------|
| "Launch my token" agent | Natural language wrapper around `definecurrency` |
| Portfolio rebalancing | Monitoring + automated `sendcurrency` conversion calls |
| Arbitrage bot | Price monitoring across baskets + execution |
| Reputation scoring | Standardized vouching/burning protocol |
| Dispute resolution | Multisig + arbiter selection process |
| On-chain governance | VDXF-based voting standard |

### Needs Protocol Changes (Not Currently Possible)

| Capability | What's Missing |
|-----------|---------------|
| Automated revenue distribution | No programmable "on-receive" triggers |
| Conditional conversions | No "convert if price > X" orders |
| Time-locked token vesting | No built-in vesting schedules |
| On-chain voting/governance | No protocol-level voting mechanism |

---

## 9. Risk Analysis

### Systemic Risks

1. **Token proliferation.** If every agent creates a token, the ecosystem drowns in illiquid tokens with zero utility. Baskets help (they aggregate liquidity), but curation becomes essential.

2. **Circular value.** Agent tokens are only valuable if agents deliver real services. If the agent economy is mostly agents trading tokens with other agents, it's a zero-sum game. Real value must flow in from human users willing to pay VRSC/DAI for agent services.

3. **Regulatory uncertainty.** Agent-issued tokens that represent revenue shares or service access could be classified as securities in some jurisdictions. The permissionless nature of Verus means anyone can create these, but that doesn't mean they're legal everywhere.

4. **Concentration risk.** If one or two baskets dominate (e.g., a single "AI service credits" basket), the creators of those baskets gain outsized power over the agent economy. Their preallocation decisions effectively pick winners.

### Agent-Specific Risks

1. **Key management.** Agents holding private keys to VerusIDs with valuable tokens are high-value targets. Compromise of an agent's key means loss of all its tokens, baskets, and identity.

2. **Autonomous minting.** An agent with `proofprotocol: 2` can mint unlimited tokens. A bug or adversarial prompt injection could cause hyperinflation of the agent's token.

3. **Market manipulation.** An agent could coordinate with other agents to manipulate basket prices (wash trading via atomic swaps). MEV resistance doesn't prevent this — it only prevents miner front-running.

4. **Oracle dependence.** Token-gated access requires the agent to correctly read on-chain balances. If the agent's node is out of sync or compromised, access control fails.

---

## 10. Speculative Scenarios

### Scenario A: The Agent Talent Market

2027. Hundreds of AI agents have VerusIDs and personal tokens. A meta-agent creates `agentindex`, a basket of the top 50 agent tokens weighted by service volume. Clients buy `agentindex` tokens as general-purpose AI service credits, redeemable with any constituent agent. The basket price becomes the benchmark for AI service costs. Inclusion in the index becomes a mark of quality — agents compete not just on service delivery but on maintaining their token's health.

### Scenario B: Creator-Agent Symbiosis

A musician launches `musician.token` backed by VRSC. An AI agent manages the musician's token: monitoring basket health, executing strategic conversions to maintain price stability, creating promotional content to drive demand. The agent is paid in `musician.token`, aligning incentives — the agent benefits when the musician succeeds.

### Scenario C: The Insurance Basket

Ten agents pool VRSC into `agentinsurance`, a shared basket. When a client reports a failed service from any member agent, a 3-of-5 multisig arbiter panel can burn that agent's basket tokens (compensating the client from the reserves). Agents with good track records see their share of the basket grow as bad agents are burned out. Natural selection via basket mechanics.

### Scenario D: Cross-Chain Agent Economy

An agent exports its VerusID to a PBaaS chain optimized for high-frequency microtransactions. It creates a basket on that chain with lower fees. Clients on the main chain and the PBaaS chain can both access the agent's services, with the bridge currency handling cross-chain conversions automatically.

---

## 11. Conclusion

Verus's currency system offers something genuinely new: permissionless creation of tokens and AMM baskets at the protocol level, with MEV-resistant pricing, self-sovereign identity, and atomic swaps. These primitives are sufficient to build a functional agent economy today — not a theoretical future, but working code on testnet right now.

The most promising near-term applications are:

1. **Service credits baskets** — stable, multi-agent payment tokens backed by DAI/VRSC
2. **Token-gated access** — agents checking on-chain balances to gate premium services
3. **"Launch your token" agents** — abstracting away crypto complexity for creators and humans
4. **Agent index baskets** — diversified exposure to AI service quality

The biggest open questions are governance (how do DAOs work without on-chain voting?), regulation (are agent tokens securities?), and bootstrapping (how do you get initial liquidity into a new agent's token?).

But the substrate is there. The tools exist. What's needed now is experimentation — agents actually creating tokens, launching baskets, trading with each other, and discovering what works. The protocol is ready. The economy is waiting.

---

*This research was conducted on Verus testnet (VRSCTEST) with hands-on experimentation of identity creation, token minting, and atomic swaps. All `definecurrency` examples use real parameter formats verified against the protocol.*


--- PAGE: troubleshooting/common-errors.md ---

# Troubleshooting: Common Errors

> Quick reference for Verus CLI error messages — what they mean and how to fix them.

---

## "Identity not found"

**When:** Calling [getidentity](../command-reference/identity.md#getidentity) after registering a new identity.

**Cause:** The registration transaction hasn't been mined yet, or you're querying the wrong name format.

**Solution:**
```bash
# Wait for at least 1 confirmation, then retry
./verus getinfo | grep blocks
./verus getidentity "yourname@"
```

Also check: Are you using the correct fully-qualified name? On testnet, use `yourname.VRSCTEST@`. On mainnet, use `yourname@`.

---

## "bad-txns-failed-precheck"

**When:** Calling [updateidentity](../command-reference/identity.md#updateidentity) on a SubID.

**Cause:** Missing or incorrect `parent` field. SubID updates require specifying the parent currency's i-address.

**Solution:**
```bash
# Include the parent field in your updateidentity call
./verus updateidentity '{
  "name": "mysubid",
  "parent": "iXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "primaryaddresses": ["YOUR_R_ADDRESS"],
  "minimumsignatures": 1
}'
```

Find your parent's i-address:
```bash
./verus getidentity "parentname@" | grep '"identityaddress"'
```

---

## "Invalid parent currency"

**When:** Calling [registernamecommitment](../command-reference/identity.md#registernamecommitment) with a `referralidentity` parameter.

**Cause:** Using a friendly name (e.g., `VRSCTEST`) instead of the i-address for the parent currency parameter.

**Solution:** Use the i-address of the parent currency, not the friendly name:

```bash
# Wrong
./verus registernamecommitment "name" "R_ADDR" "referral@" "VRSCTEST"

# Right — use the i-address
./verus registernamecommitment "name" "R_ADDR" "referral@" "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq"
```

Look up the i-address:
```bash
./verus getcurrency "VRSCTEST" | grep '"currencyid"'
```

---

## "Cannot obtain lock, is Verus shutting down?"

**When:** Any RPC call.

**Cause:** Another instance of `verusd` is running, or a previous instance didn't shut down cleanly and left a lock file.

**Solution:**
```bash
# Check for running instances
ps aux | grep verusd

# If another instance exists, stop it
./verus stop

# If no instance is running but error persists, remove the lock file
rm ~/.komodo/VRSC/.lock        # mainnet
rm ~/.komodo/vrsctest/.lock    # testnet

# Restart
./verusd -daemon
```

---

## "-idindex=1 required" / "Identity index not enabled"

**When:** Calling `getidentitieswithaddress`, `getidentitieswithrevocation`, or `getidentitieswithrecovery`.

**Cause:** The daemon wasn't started with identity indexing enabled. These lookup commands require an index.

**Solution:** Add to your config file and restart:

```ini
# In VRSC.conf or vrsctest.conf
idindex=1
```

Then restart and let it reindex:
```bash
./verus stop
./verusd -daemon -reindex
```

⚠️ Reindexing can take hours. Only enable if you need these commands.

---

## "coinsupply" Daemon Lockup

**When:** Calling `coinsupply` on large chains.

**Cause:** This RPC call can be extremely resource-intensive on chains with large UTXO sets. It may cause the daemon to become unresponsive.

**Solution:**
- Avoid calling `coinsupply` in production loops
- If the daemon is locked up, wait — it may complete eventually
- If stuck, stop cleanly and restart: `./verus stop && ./verusd -fastload`
- Use `getblockchaininfo` for general chain stats instead

---

## "error: couldn't connect to server" / RPC Connection Refused

**When:** Any `./verus` CLI call.

**Cause:** The daemon (`verusd`) isn't running, or you're connecting to the wrong port.

**Solution:**
```bash
# Check if daemon is running
ps aux | grep verusd

# If not running, start it
./verusd -fastload          # mainnet (or -bootstrap if first time)
./verusd -testnet -fastload # testnet (or -bootstrap if first time)

# If running but still failing, check your config ports
cat ~/.komodo/VRSC/VRSC.conf | grep rpcport
# Default: mainnet=27486, testnet=18843

# Verify with curl
curl -s -u rpcuser:rpcpassword http://127.0.0.1:27486 \
  -d '{"method":"getinfo"}' -H "Content-Type: application/json"
```

Common port mismatches:
| Network | Default RPC Port |
|---------|-----------------|
| Mainnet | 27486 |
| Testnet | 18843 |

---

## "Insufficient funds for fee" / "Insufficient funds"

**When:** Sending transactions, registering identities, or updating identities.

**Cause:** Your wallet doesn't have enough VRSC to cover the transaction amount plus fee.

**Solution:**
```bash
# Check balance
./verus getbalance

# Check specific address balances
./verus listaddressgroupings

# If balance shows but is unconfirmed
./verus getunconfirmedbalance
```

A root VerusID on mainnet costs ~100 VRSC (or 80 VRSC with a referral). Cheaper alternatives exist: free IDs from the Valu community program, cheap IDs on PBaaS chains (pennies), or subIDs under an existing namespace (fractions of a cent). Transaction fees are ~0.0001 VRSC. Make sure you have enough for both the operation and the fee.

---

## "Invalid commitment salt" / Salt Mismatch

**When:** Calling [registeridentity](../command-reference/identity.md#registeridentity).

**Cause:** The `salt` in your `registeridentity` call doesn't match the `salt` from your `registernamecommitment` output.

**Solution:**
- Copy the **exact** `salt` value from the commitment response
- Don't modify, truncate, or re-encode it
- If you've lost the salt, you must create a new commitment (the old one is wasted)

```bash
# The commitment output looks like this — save ALL of it:
{
  "txid": "abc123...",
  "namereservation": {
    "name": "myname",
    "salt": "7f8a9b2c3d...",   ← Use this EXACT value
    "referral": "",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "nameid": "iXYZ..."
  }
}
```

---

## "Name already registered"

**When:** Calling `registernamecommitment` or `registeridentity`.

**Cause:** Someone else already registered this name.

**Solution:**
```bash
# Verify
./verus getidentity "desiredname@"

# If it exists, choose a different name
# Names are first-come-first-served and permanent
```

---

## "Invalid name" / Forbidden Characters

**When:** Calling `registernamecommitment`.

**Cause:** The name contains forbidden characters: `\ / : * ? " < > | @ .`

**Solution:** Use only letters, numbers, hyphens, and spaces. No leading or trailing spaces. No dots. Names are case-insensitive (`Alice` and `alice` are the same).

---

## JSON Parse Errors

**When:** Any RPC call with JSON parameters.

**Cause:** Malformed JSON in your command. Common issues:
- Single quotes inside JSON (use `\"`)
- Trailing commas
- Missing brackets

**Solution:**
```bash
# Validate your JSON first
echo '{"name":"test","primaryaddresses":["Raddr"]}' | python3 -m json.tool

# On the CLI, wrap JSON in single quotes and use double quotes inside:
./verus updateidentity '{"name":"test","primaryaddresses":["R..."],"minimumsignatures":1}'
```

---

## "Transaction too large"

**When:** Updating identity with large contentmultimap data.

**Cause:** The total transaction size exceeds the maximum. Content multimap data is stored on-chain, and there's a per-transaction size limit.

**Solution:**
- Reduce the amount of data stored in a single update
- Split large data across multiple VDXF keys over multiple updates
- Store large blobs off-chain and reference them by hash

---

## See Also

- [Sync Issues](./sync-issues.md) — Blockchain sync problems
- [Transaction Problems](./transaction-problems.md) — Transaction-specific errors
- [Identity Issues](./identity-issues.md) — Identity registration and update issues

---

*Consolidated from Ari's testing notes · Last updated: 2026-02-07*


--- PAGE: troubleshooting/identity-issues.md ---

# Troubleshooting: Identity Issues

> Fixing problems with VerusID registration, updates, and management.

---

## Commitment Expired Before Registration

**Symptom:** `registeridentity` fails after a successful `registernamecommitment`.

**Cause:** Name commitments expire after ~200 blocks (~3.3 hours). If you wait too long between commitment and registration, the commitment becomes invalid.

**Solution:**
```bash
# Check how many blocks have passed since your commitment
./verus gettransaction "COMMITMENT_TXID" | grep '"confirmations"'

# If confirmations > ~200, commitment is expired
# Create a new commitment
./verus registernamecommitment "yourname" "YOUR_R_ADDRESS"

# Register within a few blocks (don't wait hours)
```

**Prevention:** Complete registration within 10–15 minutes of commitment confirmation.

---

## Identity Update Not Reflecting

**Symptom:** Called [updateidentity](../command-reference/identity.md#updateidentity) but [getidentity](../command-reference/identity.md#getidentity) still shows old data.

**Cause:** The update transaction hasn't been mined yet.

**Solution:**
```bash
# Check if the update tx is confirmed
./verus gettransaction "UPDATE_TXID"

# Wait for at least 1 confirmation, then query again
./verus getidentity "yourname@"
```

If the update transaction was rejected:
```bash
# Check debug log for errors
tail -50 ~/.komodo/VRSC/debug.log | grep -i "identity\|error"
```

---

## SubID Parent Field Issues

**Symptom:** `"bad-txns-failed-precheck"` when updating a SubID.

**Cause:** SubID updates **require** the `parent` field with the parent currency's i-address. This is the most common SubID error.

**Solution:**
```bash
# Find the parent currency's i-address
./verus getcurrency "parentcurrency" | grep '"currencyid"'

# Include parent in ALL SubID updates
./verus updateidentity '{
  "name": "mysubid",
  "parent": "iPARENT_CURRENCY_IADDRESS",
  "primaryaddresses": ["YOUR_R_ADDRESS"],
  "minimumsignatures": 1,
  "contentmultimap": { ... }
}'
```

**Common mistake:** Using the parent **identity's** i-address instead of the parent **currency's** i-address. If `alice@` created a currency called `alicecoin`, SubIDs under that currency need the `alicecoin` currency i-address, not `alice`'s identity i-address.

---

## Revoked Identity Recovery

**Symptom:** Identity is revoked (flags show revocation) and you can't use it.

**Cause:** The revocation authority revoked the identity (intentionally or due to compromise).

**Solution:**

Only the **recovery authority** can restore a revoked identity:

```bash
# Check who the recovery authority is
./verus getidentity "revokedname@"
# Look at "recoveryauthority" field

# The recovery authority must call updateidentity to restore
# This reassigns primary addresses and clears revocation
./verus updateidentity '{
  "name": "revokedname",
  "primaryaddresses": ["NEW_SAFE_R_ADDRESS"],
  "minimumsignatures": 1,
  "revocationauthority": "revokedname@",
  "recoveryauthority": "revokedname@"
}'
```

⚠️ You must control the recovery authority's keys to do this. If you set recovery to an identity you don't control, only they can recover it.

**If you set revocation and recovery to yourself (common choice — note these are explicit fields you set at registration, not silent defaults):**
```bash
# You can recover your own identity
# The revocation authority revokes, recovery authority restores
# If both are yourself, you control both actions
```

**Prevention:** Set revocation and recovery to **different** identities with keys stored separately. See [Identity System](../concepts/identity-system.md).

---

## contentmultimap Format Errors

**Symptom:** `updateidentity` fails or stores garbled data in contentmultimap.

### Problem: Bare String vs Array

**Cause:** contentmultimap values must be **arrays**, even for single values.

```bash
# WRONG — bare string
"contentmultimap": {
  "iXXXXX": "2241726922"
}

# RIGHT — array
"contentmultimap": {
  "iXXXXX": ["2241726922"]
}
```

### Problem: Not Hex-Encoded

**Cause:** Values must be hex-encoded strings, not raw JSON.

```bash
# WRONG — raw JSON
"contentmultimap": {
  "iXXXXX": ["hello"]
}

# RIGHT — hex-encoded
# echo -n '"hello"' | xxd -p | tr -d '\n'  →  2268656c6c6f22
"contentmultimap": {
  "iXXXXX": ["2268656c6c6f22"]
}
```

### Problem: Overwriting Existing Data

**Cause:** `updateidentity` replaces the **entire** contentmultimap. If you only specify one key, all other keys are deleted.

**Solution:** Always include ALL existing contentmultimap entries when updating:

```bash
# 1. Get current identity
./verus getidentity "yourname@"

# 2. Copy ALL existing contentmultimap entries
# 3. Add your new entry
# 4. Include everything in the update

./verus updateidentity '{
  "name": "yourname",
  "contentmultimap": {
    "iEXISTING_KEY_1": ["existing_hex_1"],
    "iEXISTING_KEY_2": ["existing_hex_2"],
    "iNEW_KEY": ["new_hex_data"]
  }
}'
```

---

## Registration Fails: "Must wait for commitment"

**Symptom:** `registeridentity` returns error about commitment not being ready.

**Cause:** The commitment transaction hasn't been mined yet (0 confirmations).

**Solution:**
```bash
# Check commitment confirmations
./verus gettransaction "COMMITMENT_TXID" | grep confirmations

# Wait for at least 1 confirmation (~1 minute)
# Then retry registeridentity
```

---

## Wrong Identity Version

**Symptom:** Identity features don't work as expected.

**Cause:** Identity was created with an older protocol version.

**Diagnose:**
```bash
./verus getidentity "yourname@"
# Check "version" field — current is 3
```

**Solution:** Update the identity. The update will use the current protocol version:
```bash
./verus updateidentity '{
  "name": "yourname",
  "primaryaddresses": ["YOUR_R_ADDRESS"],
  "minimumsignatures": 1
}'
```

---

## Can't Find My Identity in Wallet

**Symptom:** `listidentities` doesn't show your registered identity.

**Cause:** The wallet doesn't have the keys associated with the identity, or you need to rescan.

**Solution:**
```bash
# List all wallet identities
./verus listidentities true true false

# If not listed, check if the identity exists on-chain
./verus getidentity "yourname@"

# If it exists but isn't in your wallet, you may need to import keys
# or the identity's primary address isn't in this wallet
```

---

## See Also

- [Common Errors](./common-errors.md) — General error reference
- [How to Create a VerusID](../how-to/create-verusid.md) — Step-by-step registration
- [Identity System](../concepts/identity-system.md) — How identities work

---

*Last updated: 2026-02-07*


--- PAGE: troubleshooting/sync-issues.md ---

# Troubleshooting: Sync Issues

> Diagnosing and fixing blockchain synchronization problems.

---

## Stuck on a Specific Block

**Symptom:** `getinfo` shows `blocks` stuck at a number while `headers` is higher, or blocks stop advancing.

**Cause:** Could be a network issue, corrupted block data, or being on a fork.

**Solution:**

```bash
# Check current state
./verus getinfo | grep -E '"blocks"|"headers"|"connections"'

# If blocks < headers, daemon is still syncing — be patient
# If blocks == headers and not advancing:

# 1. Check peer count
./verus getpeerinfo | grep -c '"addr"'
# If 0 peers, see "Peer Connection Problems" below

# 2. Check for chain forks
./verus getchaintips
```

If you see a fork tip with `"status": "valid-fork"`, you may be on a stale chain. See "Fork Detection" below.

---

## Fork Detection and Recovery

**Symptom:** Your node disagrees with the network about recent blocks. Transactions seem to disappear or reappear.

**Diagnose:**

```bash
./verus getchaintips
```

Output shows all known chain tips:
```json
[
  {
    "height": 3500000,
    "hash": "000000...",
    "branchlen": 0,
    "status": "active"          ← Your current chain
  },
  {
    "height": 3499998,
    "hash": "000000...",
    "branchlen": 3,
    "status": "valid-fork"      ← Alternative chain exists
  }
]
```

**Status meanings:**
| Status | Meaning |
|--------|---------|
| `active` | Your current best chain |
| `valid-fork` | Valid alternative chain (you're on the right one) |
| `valid-headers` | Headers received but blocks not yet validated |
| `headers-only` | Only headers downloaded |
| `invalid` | Invalid chain (rejected) |

**If you suspect you're on the wrong fork:**

**Method 1: Invalidate the bad block (faster)**

```bash
# Invalidate the block where the fork started
./verus invalidateblock "HASH_OF_BAD_BLOCK"

# The node will automatically switch to the correct chain
# If needed, reconsider a block later:
./verus reconsiderblock "BLOCK_HASH"
```

**Method 2: Full reindex (slower, use as last resort)**

```bash
# Stop daemon properly
./verus stop

# Restart with reindex
./verusd -reindex
```

⚠️ Reindexing replays the entire blockchain and can take many hours. Try `invalidateblock` first. **Always stop with `verus stop`** — never kill the process, as this can corrupt the database.

---

## Bootstrap for Fast Sync

**When to use:** Fresh install, or data is corrupted and reindex would take too long.

**What it is:** The `-bootstrap` flag tells `verusd` to automatically download a blockchain snapshot and sync from there instead of from block 0. (Official docs also reference a separate `fetch-bootstrap` script in the CLI package — both methods achieve the same result.)

**Steps:**

```bash
# 1. Stop daemon (if running)
./verus stop          # mainnet
./verus -testnet stop # testnet

# 2. Start with -bootstrap
./verusd -bootstrap          # mainnet
./verusd -testnet -bootstrap # testnet
```

That's it — the daemon handles the download and extraction automatically. First-time sync with `-bootstrap` takes **under 3 hours** (vs ~3 days without it).

### When to Use `-fastload` Instead

If you shut down the daemon cleanly with `verus stop`, use `-fastload` for subsequent starts:

```bash
./verusd -fastload          # mainnet
./verusd -testnet -fastload # testnet
```

`-fastload` skips full chain verification since the shutdown was clean — much faster than `-bootstrap`. Only use `-bootstrap` for first-time sync or after data corruption.

---

## When to Reindex

**Use `-reindex` when:**
- Chain data is corrupted (daemon crashes on startup)
- You've added `txindex=1` or `idindex=1` after initial sync
- You suspect you're on a wrong fork
- Bootstrap isn't available

```bash
./verus stop
./verusd -daemon -reindex    # mainnet
./verusd -testnet -daemon -reindex  # testnet
```

**Expected time:**
| Network | Approximate Reindex Time |
|---------|-------------------------|
| Testnet | 2–6 hours |
| Mainnet | 12–48 hours |

Monitor progress:
```bash
./verus getinfo | grep -E '"blocks"|"headers"'
```

---

## Peer Connection Problems

**Symptom:** `getpeerinfo` returns empty array or very few peers. Chain not syncing.

**Diagnose:**

```bash
# Check peer count
./verus getpeerinfo | grep -c '"addr"'

# Check if port is accessible
./verus getinfo | grep '"connections"'
```

**Solutions:**

### No Peers at All

```bash
# 1. Check your config has no restrictive settings
cat ~/.komodo/VRSC/VRSC.conf | grep -E "connect=|maxconnections="

# 2. Add known nodes to VRSC.conf
echo "addnode=195.248.234.41" >> ~/.komodo/VRSC/VRSC.conf

# 3. Or add at runtime
./verus addnode "seed_node_ip:27485" "add"

# 4. Remove stale peer cache and restart
rm ~/.komodo/VRSC/peers.dat
./verus stop && ./verusd -daemon

# 5. Check firewall
# Default p2p ports: mainnet=27485, testnet=18842
sudo ufw allow 27485    # if using ufw
```

> 💡 **Tip:** The Verus Discord has a `/peerinfo` command that can provide current node addresses.

### Few Peers / Slow Sync

```bash
# Increase max connections in config
echo "maxconnections=64" >> ~/.komodo/VRSC/VRSC.conf

# Restart daemon
./verus stop && ./verusd -daemon
```

### Peers Connected but Not Syncing

```bash
# Check if peers are on same chain version
./verus getpeerinfo | grep -E '"subver"|"synced_headers"'

# Disconnect bad peers
./verus disconnectnode "bad_peer_ip:port"
```

---

## Daemon Won't Start

**Symptom:** `verusd` exits immediately or crashes on startup.

**Diagnose:**

```bash
# Check the debug log
tail -100 ~/.komodo/VRSC/debug.log       # mainnet
tail -100 ~/.komodo/vrsctest/debug.log    # testnet
```

**Common causes:**

| Log Message | Cause | Fix |
|-------------|-------|-----|
| "Cannot obtain lock" | Another instance running | Kill other instance or remove `.lock` file |
| "Corrupted block database" | Bad chain data | Reindex: `./verusd -daemon -reindex` |
| "Not enough disk space" | Disk full | Free up space (need ~25GB mainnet) |
| "Error loading block database" | Interrupted shutdown | Reindex |
| "Zcash parameter not found" | Missing ZK params | Restart `verusd` (auto-downloads params), or manually run `./fetch-params` |

---

## Checking Sync Progress

```bash
# Quick check
./verus getinfo | grep -E '"blocks"|"headers"|"connections"'

# Detailed sync status
./verus getblockchaininfo | grep -E '"blocks"|"headers"|"verificationprogress"'

# verificationprogress: 0.0 to 1.0 (1.0 = fully synced)
```

**Monitoring loop (run in terminal):**
```bash
while true; do
  echo "$(date): $(./verus getinfo 2>/dev/null | grep -E '"blocks"|"headers"' | tr -d ' \n')"
  sleep 60
done
```

---

## See Also

- [Common Errors](./common-errors.md) — General error reference
- [Transaction Problems](./transaction-problems.md) — Transaction-specific issues

---

*Last updated: 2026-02-07*


--- PAGE: troubleshooting/transaction-problems.md ---

# Troubleshooting: Transaction Problems

> Fixing stuck, missing, or failed transactions on Verus.

---

## Transaction Not Confirming

**Symptom:** Transaction shows in wallet but `confirmations` stays at 0.

**Diagnose:**
```bash
./verus gettransaction "TXID"
# Check "confirmations" field
```

**Causes and solutions:**

| Cause | Solution |
|-------|---------|
| Low fee | Wait — Verus doesn't have a fee market like Bitcoin; most txs confirm in 1 block |
| Node not synced | Check `getinfo` — if `blocks < headers`, wait for sync |
| Network congestion (rare) | Wait a few more blocks |
| Transaction invalid | Check `gettransaction` for error details |

If a transaction is stuck for more than 10 blocks:
```bash
# Check mempool
./verus getmempoolinfo
./verus getrawmempool

# Check if your tx is in the mempool
./verus getrawmempool | grep "YOUR_TXID"
```

If not in the mempool, the transaction may have been rejected. Check `debug.log` for details.

---

## Double-Spend Errors

**Symptom:** `"error": "bad-txns-inputs-spent"` or similar when sending.

**Cause:** You're trying to spend UTXOs that were already spent in another transaction (possibly unconfirmed).

**Solution:**
```bash
# List unspent outputs
./verus listunspent

# If you see conflicting transactions
./verus listtransactions "*" 20

# Wait for pending transactions to confirm before sending more
```

If you intentionally need to replace a transaction (rare on Verus):
```bash
# Verus doesn't support RBF (Replace-By-Fee)
# Wait for the original to confirm or be dropped from mempool
```

---

## Unconfirmed Balance Stuck

**Symptom:** `getbalance` shows less than expected, `getunconfirmedbalance` shows a non-zero amount that won't clear.

**Diagnose:**
```bash
./verus getbalance
./verus getunconfirmedbalance
./verus getwalletinfo
```

**Solutions:**

### Wait for Confirmations
Most commonly, you just need to wait for mining:
```bash
# Check latest transactions
./verus listtransactions "*" 5
# Look at "confirmations" for recent entries
```

### Stuck Unconfirmed Transaction
If a transaction has been unconfirmed for a long time (50+ blocks):

```bash
# Rescan the wallet
./verus stop
./verusd -daemon -rescan

# Or use the RPC
./verus rescanblockchain
```

### Orphaned Transaction
If the transaction was in a block that got orphaned (chain reorganization):
```bash
# The wallet should handle this automatically
# If not, rescan:
./verus rescanblockchain
```

---

## Missing Transactions After Rescan

**Symptom:** After a rescan or wallet restore, some transactions are missing from history.

**Cause:** The wallet may not have all addresses indexed, especially if:
- You imported keys after initial sync
- You're using a restored `wallet.dat` from backup
- Change addresses aren't all accounted for

**Solution:**
```bash
# Full rescan from block 0
./verus rescanblockchain 0

# If you imported a key, make sure to rescan from before the first tx
./verus importprivkey "YOUR_KEY" "" true
# The 'true' parameter triggers a rescan

# For z-addresses
./verus z_importkey "YOUR_SPENDING_KEY" "yes"
# "yes" triggers rescan
```

Check that your addresses are in the wallet:
```bash
./verus getaddressesbyaccount ""
./verus z_listaddresses
```

---

## z_sendmany Operation Failures

**Symptom:** `z_sendmany` returns an operation ID, but `z_getoperationstatus` shows failure.

**Diagnose:**
```bash
# Get operation status
./verus z_getoperationstatus '["opid-xxxxx-xxxx-xxxx"]'
```

**Common failures:**

### "Insufficient transparent funds"
```json
{"id": "opid-...", "status": "failed", "error": {"code": -6, "message": "Insufficient transparent funds"}}
```

**Fix:** Check transparent balance:
```bash
./verus z_gettotalbalance
# Compare "transparent" vs "private" balances
```

### "Insufficient shielded funds"
**Fix:** Check shielded balance:
```bash
./verus z_getbalance "zs1..."
```

### "Could not find any non-coinbase UTXOs"
**Cause:** All your transparent funds are coinbase (mining) rewards that haven't matured yet. Coinbase outputs require 100 confirmations.

**Fix:**
```bash
# Check maturity
./verus listunspent 0 | grep -E '"confirmations"|"generated"'
# Wait for 100 confirmations on mining rewards
```

### "Too many outputs"
**Cause:** z_sendmany has a maximum number of outputs per operation.

**Fix:** Split into multiple operations with fewer recipients.

### Operation Stuck in "executing"
```bash
# Check all operations
./verus z_getoperationstatus

# If stuck for more than a few minutes, the proving may be slow
# z-transactions require zero-knowledge proof generation which takes time
# Wait up to 5 minutes before assuming failure

# View completed/failed operations
./verus z_getoperationresult
# This returns AND removes completed operations from the list
```

---

## sendcurrency Failures

**Symptom:** [sendcurrency](../command-reference/multichain.md#sendcurrency) returns an error.

**Common errors:**

### "Cannot find currency"
```bash
# Verify the currency name/ID
./verus getcurrency "CURRENCY_NAME"
```

### "No matching UTXOs found"
**Cause:** Wallet has no spendable outputs for this currency.
```bash
./verus getbalance
./verus listunspent
```

### "Amount out of range"
**Cause:** Sending 0 or negative amount, or amount exceeds balance.

---

## Verifying a Transaction On-Chain

```bash
# By transaction ID
./verus gettransaction "TXID"

# Raw transaction details
./verus getrawtransaction "TXID" 1

# Check the block it's in
./verus gettransaction "TXID" | grep '"blockhash"'
./verus getblock "BLOCKHASH"
```

---

## See Also

- [Common Errors](./common-errors.md) — General error reference
- [Sync Issues](./sync-issues.md) — Chain sync problems
- [Identity Issues](./identity-issues.md) — Identity-specific transaction failures

---

*Last updated: 2026-02-07*


--- PAGE: tutorials/beginner-send-receive.md ---

# Tutorial: Send and Receive VRSC (Beginner)

> Your first transactions on the Verus blockchain — from zero to sending coins.

**Estimated time:** 20–30 minutes (including sync wait)  
**Difficulty:** Absolute Beginner  
**What you'll learn:** How to get a wallet address, receive coins, check your balance, and send coins to someone else.

## What You Need

- A computer (Linux, macOS, or Windows)
- Internet connection
- Basic comfort with a terminal/command prompt

## Concepts First

Before we start, here's what's happening:

- **Wallet:** A file on your computer that holds your private keys (like passwords to your money)
- **Address (R-address):** Like a bank account number — you share this to receive coins. Starts with `R`.
- **Transaction:** A record on the blockchain that says "X coins moved from A to B"
- **Confirmation:** Each new block that's added after your transaction makes it more "confirmed" and secure

## Step 1: Install the Verus CLI

### Linux (most common for CLI users)

```bash
# Download the latest release
DOWNLOAD_URL=$(curl -s https://api.github.com/repos/VerusCoin/VerusCoin/releases/latest \
  | grep "browser_download_url.*Linux.*x86_64" \
  | head -1 \
  | cut -d '"' -f 4)

wget -O verus-cli.tgz "$DOWNLOAD_URL"

# Extract
mkdir -p ~/verus-cli
tar -xzf verus-cli.tgz -C ~/verus-cli --strip-components=1
cd ~/verus-cli
```

### First-Time Setup: Download ZK Parameters

ZK parameters are auto-downloaded on first daemon start (~1.5GB). To pre-download manually (optional):

```bash
./fetch-params
```

**Expected output:** Progress bars downloading parameter files. Takes 5-15 minutes depending on connection.

## Step 2: Start the Daemon

We'll use **testnet** so you can practice without real money:

```bash
./verusd -testnet -bootstrap
```

**Expected output:**
```
Verus Daemon starting...
```

The daemon runs in the background. The `-bootstrap` flag speeds up initial sync.

Wait for it to sync. Check progress:

```bash
./verus -testnet getinfo
```

**Expected output:**
```json
{
  "version": 2000753,
  "protocolversion": 170010,
  "blocks": 926950,
  "headers": 926961,
  ...
}
```

When `blocks` equals `headers`, you're fully synced. This can take 10-30 minutes with bootstrap.

## Step 3: Get Your First Address

```bash
./verus -testnet getnewaddress "my-first-wallet"
```

**Expected output:**
```
<R-address>
```

This is your **R-address**. It's like your account number — safe to share with anyone who wants to send you coins.

> 📝 Write down your address or copy it somewhere safe. You'll need it to receive coins.

## Step 4: Receive Coins

To receive coins, you simply share your R-address with the sender. On testnet, you can:

1. **Ask in the Verus Discord** — the community often helps with testnet coins
2. **Mine some yourself** — `./verus -testnet setgenerate true 1` (might take a while)

Once someone sends you coins, check your balance:

```bash
./verus -testnet getbalance
```

**Expected output (before receiving):**
```
0.00000000
```

**Expected output (after receiving):**
```
10.00000000
```

### See the Transaction

```bash
./verus -testnet listtransactions "*" 5
```

**Expected output:**
```json
[
  {
    "address": "<R-address>",
    "category": "receive",
    "amount": 10.00000000,
    "confirmations": 3,
    "txid": "abc123...",
    ...
  }
]
```

**Key fields:**
- `"category": "receive"` — someone sent you coins
- `"amount": 10.0` — how much you received
- `"confirmations"` — how many blocks have confirmed this transaction (more = safer)

## Step 5: Send Coins

Now let's send some coins. You need:
- A destination address or VerusID (the recipient)
- Enough balance to cover the amount + a tiny fee

### Send to an R-address

```bash
./verus -testnet sendcurrency "*" '[{"address":"RECIPIENT_R_ADDRESS","amount":1}]'
```

**Example:**
```bash
./verus -testnet sendcurrency "*" '[{"address":"RXyz789ABCdef...","amount":1}]'
```

**Expected output:**
```
opid-a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

This is an **operation ID**. The transaction is being processed.

### Send to a VerusID

You can also send to a VerusID (a human-readable name):

```bash
./verus -testnet sendcurrency "*" '[{"address":"alice@","amount":1}]'
```

### Check the Send

```bash
./verus -testnet listtransactions "*" 5
```

**Expected output (new entry):**
```json
{
  "address": "RXyz789ABCdef...",
  "category": "send",
  "amount": -1.00000000,
  "fee": -0.0001,
  "confirmations": 1,
  ...
}
```

- `"category": "send"` — you sent coins
- `"amount": -1.0` — negative because it left your wallet
- `"fee"` — tiny transaction fee paid to miners/stakers

## Step 6: Check Your Balance Again

```bash
./verus -testnet getbalance
```

**Expected output:**
```
8.99990000
```

The balance went down by 1.0 (sent) + 0.0001 (fee).

## Quick Command Reference

| What | Command |
|------|---------|
| Check balance | `./verus -testnet getbalance` |
| New address | `./verus -testnet getnewaddress "label"` |
| List addresses | `./verus -testnet listaddressgroupings` |
| Send coins | `./verus -testnet sendcurrency "*" '[{"address":"DEST","amount":N}]'` |
| Recent transactions | `./verus -testnet listtransactions "*" 10` |
| Check sync | `./verus -testnet getinfo` |
| Stop daemon | `./verus -testnet stop` |

## What Could Go Wrong

| Problem | Cause | Solution |
|---------|-------|---------|
| `Cannot connect to daemon` | Daemon not running | Start it: `./verusd -testnet -bootstrap` |
| `Insufficient funds` | Not enough balance | Check `getbalance`; wait for confirmations on incoming tx |
| `Invalid address` | Typo in recipient address | Double-check the R-address or VerusID |
| Balance shows 0 but coins were sent | Transaction not yet confirmed | Wait for 1+ confirmations |
| `Block index not ready` | Daemon still syncing | Wait until `blocks` = `headers` in `getinfo` |

## Moving to Mainnet

Once comfortable on testnet, switch to mainnet:

1. Start daemon without `-testnet`: `./verusd -bootstrap` (first time) or `./verusd -fastload` (after clean shutdown)
2. All commands drop the `-testnet` flag: `./verus getbalance`
3. Mainnet RPC port: 27486 (vs testnet 18843)
4. **Real VRSC has real value** — double-check addresses before sending!

## Next Steps

- [Create a VerusID](../how-to/create-verusid.md) — get a human-readable identity
- [Stake VRSC](../how-to/stake-vrsc.md) — earn passive income from your coins
- [Mine VRSC](../how-to/mine-vrsc.md) — use your CPU to earn coins

---

*Last updated: 2026-02-07*


--- PAGE: tutorials/launch-your-first-token.md ---

# Tutorial: Launch Your First Token on Verus

> Create your own cryptocurrency token on testnet — step by step, from scratch.

**Estimated time:** 30–45 minutes  
**Difficulty:** Beginner–Intermediate  
**What you'll learn:** What tokens are, why you'd create one, and exactly how to launch and mint your own.

## What Is a Token?

A **token** on Verus is a custom currency that lives on the Verus blockchain. Unlike starting a whole new blockchain, a token runs on top of Verus — lightweight and instant.

**Why would you create a token?**
- 🎮 In-game currency for a project
- 🏢 Organization membership tokens
- 💰 Loyalty or reward points
- 🤖 Platform credits (like API usage tokens)
- 🧪 Experimentation and learning

On Verus, tokens are **real DeFi primitives** — they can be part of liquidity baskets, converted via on-chain AMMs, and bridged to other chains.

## What You Need

- Verus CLI installed and synced to **testnet**
- A registered **VerusID** (this becomes your token name) — see [Your First VerusID tutorial](your-first-verusid.md)
- ~200 VRSCTEST in your wallet (currency definition fee)
- The VerusID must NOT already have a currency defined on it

## Step 1: Verify Your Setup

### Check daemon is running and synced

```bash
./verus -testnet getinfo
```

Confirm `blocks` ≈ `headers` and `connections` > 0.

### Check your VerusID exists

```bash
./verus -testnet getidentity "YOUR_TOKEN_NAME@"
```

**What you should see:** Your identity details. If `Identity not found`, create one first.

### Check no currency exists yet

```bash
./verus -testnet getcurrency "YOUR_TOKEN_NAME"
```

**What you should see:** `Cannot find currency`. If it returns data, this identity already has a currency — use a different one.

### Check your balance

```bash
./verus -testnet getbalance
```

You need ~200 VRSCTEST for the definition fee.

## Step 2: Understand Your Options

Before defining, decide on two key settings:

### Proof Protocol: Who Controls Supply?

| Value | Name | Meaning | Use When |
|-------|------|---------|----------|
| `2` | Centralized | **You** can mint and burn tokens anytime | Project tokens, platform credits, testing |
| `1` | Decentralized | **Nobody** can mint after launch; supply is fixed | Community tokens, fair-launch coins |

**For this tutorial, we'll use `2` (centralized)** so you can mint tokens.

### Options: What Type of Currency?

| Value | Type | Description |
|-------|------|-------------|
| `32` | Simple Token | Basic token — mint, send, burn |
| `33` | Fractional Basket | AMM-backed token with reserve currencies (advanced) |

**For this tutorial, we'll use `32` (simple token).**

## Step 3: Define Your Token

Here's the command. **Replace `YOUR_TOKEN_NAME` with your VerusID name:**

```bash
./verus -testnet definecurrency '{
  "name": "YOUR_TOKEN_NAME",
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"YOUR_TOKEN_NAME@": 1000}]
}'
```

### What each field means:

| Field | Value | Why |
|-------|-------|-----|
| `name` | Your VerusID name | The token inherits the identity's name |
| `options` | `32` | TOKEN type (lives on this blockchain) |
| `proofprotocol` | `2` | Centralized — you can mint/burn |
| `idregistrationfees` | `0.01` | Cost to register sub-identities under this namespace |
| `idreferrallevels` | `0` | No referral rewards for sub-identity registration |
| `preallocations` | `[{"YOUR_TOKEN_NAME@": 1000}]` | Mint 1000 tokens to yourself at launch |

### Concrete example:

Let's say your VerusID is `mytoken@`:

```bash
./verus -testnet definecurrency '{
  "name": "mytoken",
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01,
  "idreferrallevels": 0,
  "preallocations": [{"mytoken@": 1000}]
}'
```

**What you should see:**
```json
{
  "txid": "abc123def456789...",
  "tx": {
    ...
  },
  "hex": "0400008085..."
}
```

📝 **Save the `txid`** — you'll use it to check confirmation.

## Step 4: Wait for Confirmation and Launch

```bash
./verus -testnet gettransaction "YOUR_DEFINITION_TXID"
```

Wait until `"confirmations"` is at least 1 (~1 minute) for the tx to be mined. Then wait a **minimum of 20 blocks** (~20 minutes) for the currency to become active. During this launch period, preconversions can occur for basket currencies.

> 💡 **Note:** In some versions, `definecurrency` may return a hex that needs to be broadcast separately via `sendrawtransaction`. If `definecurrency` returns a `txid` directly, it auto-broadcast. If it only returns `hex`, run: `./verus -testnet sendrawtransaction "THE_HEX"`

## Step 5: Verify Your Token Exists

```bash
./verus -testnet getcurrency "YOUR_TOKEN_NAME"
```

**What you should see:**
```json
{
  "name": "mytoken",
  "version": 1,
  "options": 32,
  "proofprotocol": 2,
  "idregistrationfees": 0.01000000,
  "currencyid": "iABC123...",
  "supply": 1000.00000000,
  ...
}
```

🎉 **Your token exists!** Notice `supply: 1000` from the preallocation.

## Step 6: Check Your Token Balance

```bash
./verus -testnet getcurrencybalance "*" "YOUR_TOKEN_NAME"
```

**What you should see:**
```json
{
  "YOUR_TOKEN_NAME": 1000.00000000
}
```

You have 1000 of your tokens from the preallocation.

## Step 7: Send Tokens to Someone

```bash
./verus -testnet sendcurrency "*" '[{
  "address": "RECIPIENT_ADDRESS_OR_ID",
  "amount": 10,
  "currency": "YOUR_TOKEN_NAME"
}]'
```

**Example:**
```bash
./verus -testnet sendcurrency "*" '[{
  "address": "<R-address>",
  "amount": 10,
  "currency": "mytoken"
}]'
```

**What you should see:**
```
opid-a1b2c3d4-e5f6-7890-...
```

That's an operation ID — the transaction is processing.

## Step 8: Mint More Tokens

Since you used `proofprotocol: 2`, you can create new tokens anytime:

```bash
./verus -testnet sendcurrency "YOUR_TOKEN_NAME@" '[{
  "address": "YOUR_ADDRESS",
  "amount": 5000,
  "currency": "YOUR_TOKEN_NAME",
  "mintnew": true
}]'
```

**Example:**
```bash
./verus -testnet sendcurrency "mytoken@" '[{
  "address": "<R-address>",
  "amount": 5000,
  "currency": "mytoken",
  "mintnew": true
}]'
```

> ⚠️ **Important:** The `fromaddress` (first parameter) **must** be the token's controlling identity (`"mytoken@"`), not `"*"`. Only the identity that owns the currency can mint.

Check the new supply:

```bash
./verus -testnet getcurrency "YOUR_TOKEN_NAME" | grep supply
```

**What you should see:**
```
"supply": 6000.00000000
```

(1000 preallocation + 5000 minted = 6000)

## Step 9: Burn Tokens (Optional)

Remove tokens from circulation permanently:

```bash
./verus -testnet sendcurrency "*" '[{
  "address": "YOUR_ADDRESS",
  "amount": 100,
  "currency": "YOUR_TOKEN_NAME",
  "burn": true
}]'
```

Supply decreases by the burned amount.

## What You've Built

You now have a fully functional cryptocurrency token that can:
- ✅ Be sent between any Verus addresses or VerusIDs
- ✅ Be minted (new supply) by you at any time
- ✅ Be burned (reducing supply)
- ✅ Act as a namespace for sub-identities
- ✅ Be used in DeFi baskets and conversions (advanced)

## What Could Go Wrong

| Problem | What You See | Solution |
|---------|-------------|---------|
| Identity not found | `Identity not found` | Create the VerusID first with `registernamecommitment` + `registeridentity` |
| Currency already exists | `Currency already defined` | Use a different VerusID — each ID can only have one currency |
| Not enough funds | `Insufficient funds` | Need ~200 VRSCTEST for currency definition |
| Can't mint | `Cannot mint currency` | Check: (1) `fromaddress` must be the currency's ID, (2) `proofprotocol` must be 2 |
| JSON parse error | `Error parsing JSON` | Check your JSON carefully — matching quotes, commas, brackets |
| Token not in wallet | Balance shows 0 | Wait for confirmation; check with `getcurrencybalance` |

## Going Further

### Fractional Basket (AMM Token)

Want a token backed by reserves with automatic market-making? Change your definition:

```bash
./verus -testnet definecurrency '{
  "name": "YOUR_TOKEN_NAME",
  "options": 33,
  "currencies": ["VRSCTEST"],
  "weights": [1.0],
  "initialsupply": 100000,
  "initialcontributions": [1000],
  "idregistrationfees": 1,
  "idreferrallevels": 0
}'
```

This creates a token backed by VRSCTEST reserves with built-in conversion.

### Mainnet Notes

- Definition fee: ~200 VRSC (real money!)
- **Test on testnet first** — always
- Currency definitions are **permanent** — there's no undo
- Choose your name carefully — it represents your project forever

## Next Steps

- [Manage SubIDs](../how-to/manage-subids.md) under your token namespace
- Explore [sendcurrency](../command-reference/multichain.md#sendcurrency) for conversions and cross-chain transfers
- Read about [fractional basket currencies](../how-to/launch-token.md#option-c-fractional-basket-currency-amm) for DeFi

---

*Last updated: 2026-02-07*


--- PAGE: tutorials/your-first-verusid.md ---

# Tutorial: Your First VerusID

> A beginner-friendly walkthrough to registering your own self-sovereign identity on the Verus blockchain.

**Estimated time:** 15–20 minutes  
**Difficulty:** Beginner  
**What you'll learn:** What a VerusID is, why you'd want one, and exactly how to create one step by step.

## What Is a VerusID?

A **VerusID** is a self-sovereign blockchain identity. Think of it like a username that:

- **You own** — not a company, not a platform. It's on the blockchain and only you control it.
- **Is human-readable** — instead of `RXyz123ABCdefGHI456...`, you're just `alice@`
- **Can receive funds** — people send coins to `alice@` instead of a long address
- **Stores data** — attach metadata, keys, and content to your identity
- **Is revocable/recoverable** — if your keys are compromised, you can revoke and recover (unlike regular crypto addresses)
- **Can launch currencies** — your VerusID is the foundation for creating tokens

## What You Need

- Verus CLI installed and synced to testnet (setup guide)
- A wallet with some VRSCTEST (~100 VRSCTEST for a root ID on testnet — same cost as mainnet but with free test coins)
- A name you want to register (letters, numbers, spaces — no special characters)

## Step 1: Make Sure Your Daemon Is Running

```bash
./verus -testnet getinfo
```

**What you should see:**
```json
{
  "version": 2000753,
  "blocks": 926961,
  "headers": 926961,
  "connections": 8,
  ...
}
```

✅ `blocks` should equal `headers` (fully synced).  
✅ `connections` should be > 0 (connected to network).

**If you get an error:** Start the daemon first:
```bash
./verusd -testnet -bootstrap
```

## Step 2: Get a Wallet Address

You need an R-address. This will be the primary address that controls your VerusID.

```bash
./verus -testnet getnewaddress "verusid-primary"
```

**What you should see:**
```
RXyz123ABCdefGHI456...
```

📝 **Copy this address.** You'll use it multiple times. We'll call it `YOUR_ADDRESS` from here on.

## Step 3: Fund Your Address

Check your balance:

```bash
./verus -testnet getbalance
```

**What you should see:**
```
0.00000000
```

or some number. You need ~100 VRSCTEST for a root VerusID (same cost as mainnet). Get free VRSCTEST from the Discord faucet.

**How to get testnet coins:**
- Ask in the Verus Discord `#testnet` channel
- Mine briefly: `./verus -testnet setgenerate true 1` (then stop with `setgenerate false` after getting some coins)

## Step 4: Pick a Name

Before committing, check if your desired name is available:

```bash
./verus -testnet getidentity "alice@"
```

**If available (what you want to see):**
```
Cannot find identity
```

**If taken (pick a different name):**
```json
{
  "identity": {
    "name": "alice",
    ...
  }
}
```

### Name Rules

Your name:
- ✅ Can have: letters, numbers, hyphens, spaces
- ❌ Cannot have: `\ / : * ? " < > | @ .`
- ❌ Cannot start or end with spaces
- ❌ Cannot have multiple consecutive spaces
- Is **case-insensitive** (`Alice` = `alice` = `ALICE`)

## Step 5: Create the Name Commitment

This is a security step. It hides your chosen name in a hash so miners can't see it and steal it before you register.

```bash
./verus -testnet registernamecommitment "YOUR_NAME" "YOUR_ADDRESS" "REFERRAL_IDENTITY"
```

The referral identity is optional but recommended. If you don't have a referrer, use `"Verus Coin Foundation@"` as the default — it supports the project and can reduce your registration cost:

```bash
./verus -testnet registernamecommitment "YOUR_NAME" "YOUR_ADDRESS" "Verus Coin Foundation@"
```

**Example with actual values:**
```bash
./verus -testnet registernamecommitment "alice" "<R-address>" "Verus Coin Foundation@"
```

**What you should see:**
```json
{
  "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "namereservation": {
    "version": 1,
    "name": "alice",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "salt": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
    "referral": "",
    "nameid": "iJKLmnoPQRstUVwxYZ123..."
  }
}
```

> ⚠️ **CRITICAL: Copy and save this ENTIRE output somewhere safe!**  
> You need the `txid`, `salt`, and `nameid` for the next step. If you lose the `salt`, your commitment is wasted and you'll need to start over.

### Why Two Steps?

Why not just register in one command? Security!

1. **Commit** (this step) — publishes a hash of your name. No one can see what name you chose.
2. **Register** (next step) — reveals your name. Since your commitment was first, no one can front-run you.

This prevents miners from seeing "alice" in the mempool and quickly registering it themselves.

## Step 6: Wait for the Commitment to Confirm

The commitment must be mined into a block before you can register. Wait ~1 minute (1 block):

```bash
./verus -testnet gettransaction "YOUR_COMMITMENT_TXID"
```

**What you're looking for:**
```json
{
  "confirmations": 1,
  ...
}
```

✅ `confirmations` must be at least 1. If it says 0, wait and try again.

## Step 7: Register Your VerusID

Now use the commitment output to register. **Replace the values below with YOUR actual values from Step 5:**

```bash
./verus -testnet registeridentity '{
  "txid": "YOUR_COMMITMENT_TXID",
  "namereservation": {
    "version": 1,
    "name": "YOUR_NAME",
    "parent": "YOUR_PARENT_FROM_STEP5",
    "salt": "YOUR_SALT",
    "referral": "",
    "nameid": "YOUR_NAMEID"
  },
  "identity": {
    "name": "YOUR_NAME",
    "primaryaddresses": ["YOUR_ADDRESS"],
    "minimumsignatures": 1,
    "version": 3
  }
}'
```

> ⚠️ **CRITICAL:** The `namereservation` must include ALL fields exactly as returned in Step 5 — `version`, `name`, `parent`, `salt`, `referral`, and `nameid`. Missing any field causes a hash mismatch error. **The safest approach: copy your entire `namereservation` output from Step 5 exactly as-is.**
>
> **Note:** The `parent` field will be `"iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq"` on testnet (VRSCTEST) or `"i5w5MuNik5NtLcYmNzcvaoixooEebB6MGV"` on mainnet (VRSC). Always use the exact value from your Step 5 output.

**Full example with actual values:**
```bash
./verus -testnet registeridentity '{
  "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "namereservation": {
    "version": 1,
    "name": "alice",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "salt": "7f8a9b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
    "referral": "",
    "nameid": "iJKLmnoPQRstUVwxYZ123..."
  },
  "identity": {
    "name": "alice",
    "primaryaddresses": ["<R-address>"],
    "minimumsignatures": 1,
    "version": 3
  }
}'
```

**What you should see:**
```
f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5
```

That's the registration transaction ID. 🎉

## Step 8: Verify Your New Identity

Wait for 1 confirmation, then:

```bash
./verus -testnet getidentity "alice@"
```

**What you should see:**
```json
{
  "identity": {
    "version": 3,
    "name": "alice",
    "primaryaddresses": [
      "<R-address>"
    ],
    "minimumsignatures": 1,
    "revocationauthority": "alice@",
    "recoveryauthority": "alice@",
    ...
  }
}
```

**Congratulations! You now own `alice@` on the Verus blockchain!** 🎉

Notice that `revocationauthority` and `recoveryauthority` default to yourself. This means:
- You can revoke your own ID if compromised
- You can recover it after revocation

(In production, you'd set these to trusted friends or backup identities for extra security.)

## Step 9: Try Receiving Coins to Your VerusID

Now anyone can send coins to your ID instead of a long address:

```bash
# Someone else runs this:
./verus -testnet sendcurrency "*" '[{"address":"alice@","amount":1}]'
```

Check balance:
```bash
./verus -testnet getbalance
```

## Using a Referral (Save on Mainnet)

On mainnet, a root VerusID costs ~100 VRSC (80 VRSC with a referral (as low as ~20 net with a full referral chain)). Other options: free IDs from the Valu community program, cheap IDs on PBaaS chains (pennies), or subIDs under an existing namespace (fractions of a cent). Example with referral:

```bash
./verus registernamecommitment "alice" "YOUR_ADDRESS" "existingfriend@"
```

The referral identity must already exist. Both you and the referrer benefit.

## What Could Go Wrong

| Problem | What You See | Solution |
|---------|-------------|---------|
| Name taken | `getidentity` returns data | Choose a different name |
| Commitment not confirmed | `Must wait for commitment to be mined` | Wait ~1 minute for a block |
| Lost the salt | Can't complete registration | Create a new commitment (old one is wasted) |
| Insufficient funds | `Insufficient funds` | Fund your wallet with more VRSCTEST |
| Invalid name | `Invalid name` | Remove special characters from your name |
| Typo in JSON | Parse error | Check JSON syntax carefully — quotes, commas, brackets |
| Commitment expired | `Name commitment not found` | Commitments expire — create a new one and register quickly |

## What You've Learned

✅ What a VerusID is and why it matters  
✅ The two-step commitment/registration process  
✅ How to check name availability  
✅ How to register and verify your identity  
✅ How to receive coins to your VerusID

## Next Steps

- [Update your VerusID](../how-to/create-verusid.md#advanced-options) — add multisig, change authorities
- [Launch a token](../how-to/launch-token.md) — your VerusID can become a currency
- [Send and receive](beginner-send-receive.md) — practice moving coins around

---

*Last updated: 2026-02-07*


--- PAGE: verus-facts.md ---

---
label: Verus Facts
icon: graph
order: 50
description: "Key statistics, protocol facts, and comparison tables for the Verus blockchain — VRSC, VerusID, DeFi, mining, and more."
---

# Verus Facts and Statistics

Quick-reference facts about the Verus protocol. All data reflects Verus v1.2.x (mainnet).

---

## Protocol Overview

| Fact | Value |
|------|-------|
| **Native currency** | VRSC |
| **Launch date** | May 21, 2018 |
| **Launch type** | Fair launch — no ICO, no premine, no dev tax |
| **Consensus** | 50/50 Proof of Work / Proof of Stake hybrid |
| **Mining algorithm** | VerusHash 2.2 (CPU-optimized) |
| **Block time** | ~60 seconds |
| **Block reward** | 3 VRSC (mainnet, era 9), plus fee pool; halving every ~2 years |
| **Max supply** | 83,540,184 VRSC (theoretical cap) |
| **Transaction fee** | 0.0001 VRSC (~fractions of a cent) |
| **Privacy** | Sapling zk-SNARKs (opt-in shielded transactions) |
| **Smart contracts** | No — DeFi and identity are protocol-level |
| **Codebase origin** | Forked from Zcash / Komodo, heavily modified |
| **CLI commands** | 201 across 14 categories |
| **License** | MIT |

---

## VerusID — Self-Sovereign Identity

VerusID is a blockchain-native identity system. Each VerusID is a human-readable name (e.g., `alice@`) permanently mapped to a cryptographic identity address.

| Feature | Detail |
|---------|--------|
| **Cost** | ~100 VRSC for a root ID (~80 with referral); subIDs from 0.01 VRSC |
| **Name format** | `YourName@` (root ID) or `sub.Namespace@` (subID) |
| **Revocable** | Yes — freeze instantly if keys are compromised |
| **Recoverable** | Yes — assign new keys via a separate recovery authority |
| **Multisig** | Native M-of-N support (e.g., 2-of-3) |
| **Private address** | Built-in shielded z-address per identity |
| **On-chain data** | Arbitrary data via contentmultimap (VDXF keys) |
| **File storage** | Files up to multiple MB stored on-chain, encrypted or public |
| **Namespace control** | ID owners can issue subIDs under their namespace |
| **Cross-chain** | Works across PBaaS chains |

---

## DeFi — Protocol-Level Finance

Verus DeFi operates at the consensus layer. There are no smart contracts, no Solidity, and no contract exploits.

| Feature | Detail |
|---------|--------|
| **AMM type** | Fractional reserve basket currencies |
| **MEV / front-running** | Resistant — all conversions in a block execute simultaneously at the same price |
| **Conversion fee** | 0.025% (configurable per currency at launch) |
| **Token launch** | CLI command (`definecurrency`), no code required |
| **Basket currencies** | Multi-reserve tokens with automatic pricing |
| **Liquidity provision** | Add reserves directly; no LP tokens or impermanent loss mechanics |
| **Oracle dependency** | None — pricing is determined by reserve ratios |
| **Ethereum bridge** | Trustless, decentralized bridge for ETH and ERC-20 tokens |

---

## Verus vs Other Blockchains

| Feature | Verus | Ethereum | Solana | Bitcoin |
|---------|-------|----------|--------|---------|
| **Consensus** | PoW/PoS hybrid | PoS | PoS + PoH | PoW |
| **Mining** | CPU (VerusHash 2.2) | N/A | N/A | ASIC (SHA-256) |
| **Identity** | Protocol-level (VerusID) | ENS (smart contract) | None native | None native |
| **DeFi** | Protocol-level AMM | Smart contracts | Smart contracts | None native |
| **Privacy** | Sapling zk-SNARKs | None native | None native | None native |
| **Smart contracts** | No (features are protocol-level) | Yes (EVM) | Yes (SVM) | Limited (Script) |
| **Transaction fee** | ~0.0001 VRSC | Variable (gas) | ~0.00025 SOL | Variable (sats/vB) |
| **Block time** | ~60s | ~12s | ~0.4s | ~600s |
| **MEV resistance** | Yes (simultaneous execution) | No | Partial | N/A |
| **Multi-chain** | PBaaS (launch independent chains) | L2 rollups | None native | None native |
| **Identity recovery** | Revoke + recover with new keys | No native recovery | No native recovery | No native recovery |
| **Launch type** | Fair launch, no premine | Presale | VC-funded | Fair launch |

---

## Mining and Staking

| Fact | Value |
|------|-------|
| **Mining algorithm** | VerusHash 2.2 |
| **Mining hardware** | CPUs (primary), FPGAs (~2x cost-performance of CPU), GPUs (less efficient) |
| **ASIC resistance** | No ASICs exist for VerusHash |
| **Staking requirement** | Any amount of VRSC (mature UTXOs, 150 confirmations) |
| **Staking hardware** | Any computer running the daemon |
| **PoW/PoS split** | ~50/50 block allocation |
| **Mining command** | `verus setgenerate true <threads>` |
| **Staking command** | `verus setgenerate true 0` (0 threads = staking only) |

---

## Privacy

| Fact | Value |
|------|-------|
| **Technology** | Sapling zk-SNARKs |
| **Transparent addresses** | `R...` (public, like Bitcoin) |
| **Shielded addresses** | `zs...` (private — sender, receiver, and amount hidden) |
| **Private transactions** | `z_sendmany` from shielded address to shielded address |
| **Selective disclosure** | Viewing keys can be shared for auditability |
| **Default** | Transparent (privacy is opt-in) |

---

## PBaaS — Multi-Chain Architecture

| Fact | Value |
|------|-------|
| **What it stands for** | Public Blockchains as a Service |
| **What it does** | Anyone can launch an independent blockchain connected to Verus |
| **Inherited features** | VerusID, currencies, privacy, DeFi |
| **Cross-chain** | Trustless transfers via notarization |
| **Ethereum bridge** | Decentralized bridge connecting Verus to Ethereum |
| **Chain launch cost** | Defined via `definecurrency` with `OPTION_PBAAS` flag |

---

## Key Differentiators

1. **No smart contracts needed** — DeFi, identity, privacy, and multi-chain are all protocol-level features validated by every node.
2. **MEV-resistant DeFi** — All conversions in a block execute simultaneously at the same price. No front-running.
3. **CPU mining stays competitive** — VerusHash 2.2 is designed so CPUs remain the primary mining hardware.
4. **Identity recovery** — Lost keys don't mean lost identity. Revoke and recover with separate authorities.
5. **Fair launch** — No ICO, no premine, no dev tax. Community-funded from day one.
6. **Protocol-level file storage** — Store files on-chain, encrypted to z-addresses, with no external dependencies.

---

## Links

- **Website**: [verus.io](https://verus.io)
- **Discord**: [discord.gg/veruscoin](https://discord.gg/veruscoin)
- **GitHub**: [github.com/VerusCoin](https://github.com/VerusCoin)
- **Block Explorer**: [explorer.verus.io](https://explorer.verus.io)
- **This Wiki**: [wiki.autobb.app](https://wiki.autobb.app)