# Wallet Exporter

The **Wallet Exporter** is an optional telemetry component that periodically exposes comprehensive statistics about Curio wallets, miners and the messages they send. The metrics are exported via the built-in Prometheus endpoint and can be scraped by any Prometheus compatible monitoring stack.

> ⚠️ IMPORTANT: **Enable the exporter on exactly *****one***** Curio node in the cluster.** Enabling it on multiple nodes would cause duplicated metric series which leads to incorrect dashboards and aggregated values.

***

## Why would I enable it?

* Track wallet balances for every on-chain address that appears in the `wallet_names` table. Those are wallets with a name on the Wallets page.
* Observe storage-provider balances and power in real-time.
* Monitor message throughput, gas usage and fees broken down by sender, receiver and reason.
* Build Grafana dashboards that correlate wallet activity with other Curio subsystems.

## How does it work?

1. Every 30 seconds (`WalletExporterInterval`) Curio executes one exporter cycle.
2. During a cycle Curio gathers the following information:
   * Wallet balances
   * Miner available balance and power (for the SP IDs configured on this node)
   * Newly sent messages that are waiting to land
   * Messages that have already landed (executed) and their execution result
3. For every data-point the exporter records an *OpenCensus measure* which is immediately made available as a Prometheus metric.

## Enabling the exporter

Add the following to one layer which is active on *exactly one* node:

```toml
[CurioSubsystems]
EnableWalletExporter = true
```

Restart the node. The new metrics will appear at the standard metrics endpoint within \~30 seconds.

## Exported metrics

| Metric name                            | Type      | Description                                                                |
| -------------------------------------- | --------- | -------------------------------------------------------------------------- |
| `wallet_balance_nfil`                  | gauge     | Wallet or miner balance in **NanoFIL**                                     |
| `wallet_power`                         | gauge     | Storage-provider power in **bytes** (label `type` = `raw` or `qap`)        |
| `wallet_message_sent`                  | counter   | Number of messages that have been **submitted**                            |
| `wallet_message_landed`                | counter   | Number of messages that have **executed** on-chain                         |
| `wallet_gas_units_requested`           | counter   | Gas units requested by submitted messages                                  |
| `wallet_gas_units_used`                | counter   | Gas units used by executed messages                                        |
| `wallet_sent_nfil`                     | counter   | NanoFIL **value** transferred by executed messages                         |
| `wallet_gas_paid_nfil`                 | counter   | NanoFIL **gas fee** paid by executed messages                              |
| `wallet_message_land_duration_seconds` | histogram | Distribution of time (in seconds) between message submission and execution |


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://docs.curiostorage.org/experimental-features/wallet-exporter.md?ask=<question>
```

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

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