# 🌐 What is QIE?

QIE Blockchain is a high-performance Layer 1 blockchain originally useful for defi and gaming, now transformed into a multi-ecosystem, developer-first protocol. Built to support both EVM and Cosmos ecosystems, QIE combines the best of scalability, decentralization, and cross-chain interoperability.

Our mission is to provide a next-generation infrastructure for DeFi, gaming, and scalable dApps, without compromising on speed, user experience, or decentralization.

Whether you're a validator, builder, or investor—QIE Blockchain offers the tools, incentives, and architecture to grow with you.

<br>


# 🚀 Why QIE Version 3?

After the success and learnings of QIE Version 2, we built QIE V3 from the ground up to solve limitations and introduce powerful innovations. V2 served as a foundation, but V3 elevates QIE into a truly production-grade Layer 1 chain.

✅ QIE V2 = EVM-compatible chain with basic staking.

&#x20;🚀 QIE V3 = Multi-ecosystem, high-speed, dual-wallet chain designed for DeFi, NFTs, gaming, and real-world apps

Here's how QIE V3 is different from QIE V2:\ <br>

| Feature                 | QIE V2   | QIE V3 (Now)                               |
| ----------------------- | -------- | ------------------------------------------ |
| Delegation Support      | Null     | ✅ Native delegator support for staking     |
| Ecosystem Compatibility | EVM only | ✅ EVM + Cosmos dual compatibility          |
| Reward Distribution     | Periodic | ✅ Daily rewards to validators + delegators |
| Block Finality          | Slower   | ✅ 1-2 second finality                      |
| Throughput              | Moderate | ✅ Up to 30,000 TPS                         |
| Interoperability        | Basic    | ✅ Cross-ecosystem (Cosmos ↔ EVM)           |
| Wallet Structure        | EVM-only | ✅ Dual wallet (0x for EVM, QIE for native) |
| Use-case Optimization   | General  | ✅ Tailored for DeFi & Web3 Gaming          |

<br>


# 🌟 QIE V3 — Key Features

QIE Blockchain V3 sets itself apart from traditional L1s by offering:

#### 🔐 1. Built-in Delegator Support

Stake with validators, earn shared rewards, and participate in on-chain governance—all from day one.

#### 🔄 2. Dual Ecosystem: EVM + Cosmos

Enjoy the flexibility to build dApps that tap into both ecosystems, unlocking new use cases and liquidity.

#### 💸 3. Daily Reward Payouts

Forget waiting weeks—validators and delegators receive fair, transparent rewards every 24 hours.

#### ⚡ 4. 1-2 Second Finality

Transactions are confirmed in just one - two second—ideal for fast-paced DeFi and real-time gaming experiences.

#### 🚅 5. Scalable up to 30,000 TPS

Mass adoption-ready with industry-leading throughput.

#### 🌉 6. Cross-Ecosystem Interoperability

Easily bridge and build across Cosmos and EVM networks. Perfect for cross-chain DeFi, NFT platforms, and GameFi.

#### 🧠 7. Dual Wallet System (Single Private Key)

Use one private key to control two wallet formats:

* 0x... for EVM-based operations\ <br>
* QIE... for native QIE functions

#### 🎮 8. Purpose-Built for DeFi & Gaming

From consensus to wallet architecture, QIE is tailored for high-growth use cases—scalable DeFi protocols and immersive Web3 games.

🧩9. Fully **EVM-compatible**&#x20;

Deploy Ethereum smart contracts with no major changes.

🪙 **10. Scheduled Halving Every 2 Years**\
QIE features a predictable tokenomics model with block reward halving every two years—supporting long-term value and scarcity.<br>


# 🌍 Why QIE V3 Matters

### 💼 Why It Matters to Investors

QIE V3 is designed for **long-term growth and value**:\
\
🔥 **Burn mechanics** reduce coin supply over time\
🗳️ **Community-governed halving** controls inflation\
🌉 **Cross-ecosystem access** opens doors to more liquidity\
💸 **Daily rewards** provide steady passive income\
⚡ **Fast & scalable** network ready for mass adoption\
\
Investors get a sustainable, transparent platform with real earning potential.

***

### 👩‍💻 Why It Matters to Developers

QIE V3 empowers developers to **build without limits**:\
\
🔄 **Dual Ecosystem (EVM + Cosmos)** expands reach and flexibility\
⚡ **1-2 second finality & 30K TPS** for fast, scalable dApps\
🌐 **Seamless cross-chain interoperability** simplifies complex builds\
🎮 Tailored for **DeFi & gaming**—perfect for innovative use cases\
\
Developers gain a robust, versatile environment to launch next-gen applications.

***

### 🌍 Why It Matters to the Community

QIE V3 puts **power in your hands**:\
\
🤝 **Stake & delegate easily** to support network security\
🗳️ **Participate in governance**—vote on halving and upgrades\
🔐 **Secure dual-wallet system** protects your assets across ecosystems\
🎉 **Join a vibrant ecosystem** built for DeFi enthusiasts and gamers alike\
\
The community drives growth, security, and evolution of the QIE network.


# 🚀 Getting Started with QIE Blockchain

Welcome to the QIE Blockchain V3 ecosystem — a high-performance, dual-compatible Layer 1 network designed for DeFi, gaming, and scalable cross-chain dApps.

In this section, you will learn how to :

* Set up your full node on mainnet.
* Access supported wallets (CLI and GUI)
* Connect using Keplr, MetaMask, or the native QIE wallet
* Use the QIE faucet to obtain testnet coins

Dive in and start your journey with QIE!


# ⚙️ 1. How to Run a Full Node on QIE V3

### 🛠️ Step-by-Step Node Setup

#### 🔁 Step 1: Clone the QIE Repository

```bash
cd $HOME
sudo apt-get install wget
wget https://github.com/qieadmin/qiev3-mainnet/releases/download/v3/qiemainnetv3.zip
unzip qiemainnetv3.zip
cd QIEV3Mainnet
rm -rf qied
wget https://github.com/qieadmin/qiev3-mainnet/releases/download/v4/qied
chmod +x qied
```

***

#### 🧭 Step 2: Add the Binary to Your PATH

In the QIEV3Mainnet directory, run:

```bash
sudo cp -r ./qied /usr/bin
cd $HOME
```

This allows you to use `qied` globally from anywhere.

***

#### 🧰 Step 3: Initialize the Node

```bash
qied init --chain-id="<chain-id>" <node-name> --home "<path-to-config>"
```

**Example:**

```bash
qied init --chain-id="qie_1990-1" fullnode --home "$HOME/.qieMainnetNode"
```

This will generate the required structure in `~/.`qieMainnetNode, including:

* `config/` – blockchain config files
* `data/` – block data

***

#### 🧾 Step 4: Replace the Genesis File

Delete the auto-generated genesis file and other files as well :

```bash
rm -rf  $HOME/.qieMainnetNode/config/genesis.json
rm -rf  $HOME/.qieMainnetNode/config/config.toml
rm -rf  $HOME/.qieMainnetNode/config/client.toml
rm -rf  $HOME/.qieMainnetNode/config/app.toml
```

#### 🧾 Step 5: Replace the Genesis File and others.

```bash
cp -r $HOME/QIEV3Mainnet/genesis.json $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/config.toml $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/client.toml $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/app.toml $HOME/.qieMainnetNode/config
```

Then, copy the `genesis.json` and other Necesories files from your existing Node 1 and place it here.

***

#### 🧾 Step 6: Set a Name for Your Full Node

To personalize and identify your full node on the QIE Mainnet, you need to set a unique name (moniker). This name will be visible on the [QIE Validators Page](https://mainnet.qie.digital/validators).

**🔧 Edit the Configuration File**

Run the following command to open the configuration file in the terminal:

```
nano $HOME/.qieMainnetNode/config/config.toml
```

Inside the file, locate the following line:

```
moniker = "<Add_your_name>"
```

Replace `"<Add_your_name>"` with your preferred **unique** node name. This will serve as your validator identity on the network.

> 💡 **Tip:** Choose a recognizable and meaningful name, especially if you plan to become a validator.

**💾 Save and Exit**

After editing the line:

1. Press `Ctrl + X` to exit.
2. Press `Y` to confirm saving the changes.
3. Hit `Enter` to finalize and close the file.

Your node name has now been successfully updated!

#### ▶️ Step 7: Start the Node

```bash
qied start --home "$HOME/.qieMainnetNode"
```

Your node will begin syncing with the network.

***

#### ⏳ Step 8: Wait for Full Sync

You’ll see blocks being synced in logs.

You can also verify sync status using:

```bash
curl localhost:26657/status
```

***

### 🎉 Step 9: Done!

Congratulations — your QIE full node is now successfully running and connected to the network.

<br>


# 📦 QIE Mainnet — Latest Mainnet Snapshot

The latest **QIE Mainnet snapshot** is available for validator operators to download and use for faster node synchronization.

#### Snapshot Details

* **Network:** QIE Mainnet
* **Snapshot Height:** `10,024,923`
* **Snapshot Size:** \~`206 GiB`
* **Snapshot Contents:** `data/` directory only

#### 📥 Download Snapshot

[Download QIE Mainnet V6 Snapshot](https://qie-snapshot-share.sgp1.digitaloceanspaces.com/qie-mainnet-v6-snapshot/?utm_source=chatgpt.com)

The snapshot is hosted as an **S3-compatible directory** and should be downloaded recursively using `rclone`.

```
rclone copy \  :s3:qie-snapshot-share/qie-mainnet-v6-snapshot/ \  <QIE_DATA_DIRECTORY>/ \  --s3-provider DigitalOcean \  --s3-endpoint https://sgp1.digitaloceanspaces.com \  --s3-no-check-bucket \  -P
```

Replace `<QIE_DATA_DIRECTORY>` with your validator's existing QIE data directory.

> ⚠️ **Important:** Stop `qied` before restoring the snapshot. The snapshot contains only blockchain `data/` and does **not** include validator keys, signing keys, node identity, or configuration files. Keep your existing validator-specific files intact.


# 👛 2. Set Up a Wallet

### 🔒 CLI Wallet Management with `qied keys`

#### Step 1: Generate a New Wallet Key

Create a new wallet key pair (private + public key):

```
qied keys add <wallet_name>

```

* Replace `<wallet_name>` with your preferred name.
* You will be prompted to set a secure password to encrypt your key.

***

#### Step 2: List Existing Wallet Keys

To see all wallet keys stored locally:

```
qied keys list
```

This will display your wallet names and their associated addresses.

***

#### Step 3: Recover Wallet from Seed Phrase

If you have an existing seed phrase, restore your wallet with:

```
qied keys add <wallet_name> --recover

```

Enter your mnemonic seed phrase when prompted.

***

#### Step 4: Export Public Address<br>

To get the public address of a wallet key:

```
qied keys show <wallet_name> -a
```

#### Step 5: Delete a Wallet Key (Optional)

```
qied keys delete <wallet_name>
```

#### Additional Tips:

* **Backup your seed phrase securely** — it’s the only way to recover your wallet.
* **Never share your private key or password.**
* Use these CLI commands only on trusted machines.
* For transactions, use the `--from <wallet_name>` flag referencing your wallet name.

***

### 🦊 GUI Wallets: Using MetaMask with QIE

#### What is MetaMask?

MetaMask is a popular Web3 browser extension wallet that allows you to interact with Ethereum-compatible blockchains through a graphical interface. Since QIE supports EVM compatibility, you can use MetaMask (or similar wallets) to manage your QIE coins and interact with dApps.

#### How MetaMask Works with QIE:

* **Add QIE Network to MetaMask:**\
  You manually configure MetaMask to connect to the QIE blockchain by adding the network details.
* **Manage QIE Coins:**\
  Once connected, you can send, receive, and stake QIE coins using MetaMask’s simple interface.
* **Interact with dApps:**\
  Use MetaMask to access decentralized applications built on QIE’s EVM layer.

***

#### How to Set Up MetaMask for QIE:

1. **Install MetaMask** browser extension (Chrome, Firefox, Brave).
2. Open MetaMask and click **‘Add Network’**.
3. Enter QIE network details:
   * Network Name: QIEMainnet
   * RPC URL: `https://rpc5mainnet.qie.digital/`     &#x20;
   * Chain ID: `1990`
   * Currency Symbol: `QIEV3`
   * Block Explorer URL: `https://mainnet.qie.digital/`
4. Save and switch to the QIE network.
5. Import your wallet using seed phrase or create a new account.
6. Start managing your QIE coins!

***

#### Advantages of Using MetaMask with QIE:

* **User-friendly interface** for coin management.
* Supports **multiple networks**, so you can manage QIE alongside Ethereum and other chains.
* Seamless interaction with **EVM-compatible dApps** on QIE.
* Well-known and widely supported across Web3 projects.

***

#### Important Security Tips:

* Only add trusted RPC URLs and network details.
* Keep your MetaMask seed phrase and private keys **secure and private**.
* Beware of phishing sites and always verify the dApps you connect t


# 🌐 4. Access Mainnet or Testnet

#### 🔵 QIE Mainnet

* **Chain ID**: 1990
* **RPC1**: <https://rpc1mainnet.qie.digital/>
* **RPC2**: <https://rpc2mainnet.qie.digital/>
* **RPC3**: <https://rpc5mainnet.qie.digital/>
* **RPC4**: <https://rpc4mainnet.qie.digital/>
* **RPC5**: <https://rpc3mainnet.qie.digital/><br>
* Symbol: QIEV3
* Name: QIEMainnet
* **Explorer**: <https://mainnet.qie.digital/>

#### 🧪 QIE Testnet

* **Explorer**: <https://testnet.qie.digital/>
* Name: QIE testnet
* Symbol: QIE
* **RPC1**: <https://rpc1testnet.qie.digital/>    (recommend)&#x20;
* **RPC2**: <https://rpc2testnet.qie.digital/>
* **RPC3**: <https://rpc3testnet.qie.digital/>
* **RPC4**: <https://rpc4testnet.qie.digital/>
* **RPC5**: <https://rpc5testnet.qie.digital/>
* **RPC6**: <https://rpc6testnet.qie.digital/>
* **Chain ID**: 1983

\ <br>

* Faucet: <https://www.qie.digital/faucet>\ <br>

Use testnet for experimenting with staking, contracts, and tools.\
\
**Note:** We provide List of RPC URLs. If one RPC is not working or appears offline, please switch to another available RPC URL.

<br>


# 🪙 4. Get Testnet Coins (Faucet)

**To test features on QIE :**<br>

1. Open: QIE Testnet Faucet
2. Connect with Keplr or MetaMask
3. Enter your wallet address
4. Click “Request Test Coins”
5. Coins will appear within 1 minute

<br>


# 🧾 What Are Validators?

Validators are network participants who **secure and maintain the QIE blockchain** by validating and proposing new blocks. They play a critical role in:

* **Confirming transactions**
* **Ensuring consensus and network security**
* **Distributing rewards to themselves and their delegators**
* **Participating in on-chain governance decisions**

Validators run dedicated nodes and stake their coins  as collateral, helping keep the network decentralized, trustworthy, and efficient.


# 🔄 What Do Validators Do in QIE V3?

Validators are the backbone of the QIE network. In QIE V3, they perform a range of **critical responsibilities** that ensure the security, functionality, and decentralization of the blockchain:

***

#### ✅ 1. Validate and Propose Blocks

Validators participate in block production by verifying transactions and proposing new blocks to be added to the chain.

***

#### 🔐 2. Secure the Network via Proof of Stake

By locking up (staking) QIE coins, validators help maintain consensus and protect the network from malicious attacks. Their stake is at risk if they act dishonestly.

***

#### 💸 3. Distribute Rewards

Validators collect rewards from block emissions, transaction fees, and delegation commissions — and distribute a fair share to their delegators daily.

***

#### 📊 4. Participate in Governance

Validators vote on key on-chain proposals, including changes to protocol parameters (e.g., halving events), upgrades, or community decisions — giving them influence over the future of QIE.

***

#### 🌉 5. Support Interoperability

Validators help maintain QIE’s cross-chain capabilities by enabling communication between **EVM** and **Cosmos-based** chains, contributing to a more connected and versatile ecosystem.

***

Validators in QIE V3 do much more than validate blocks — they **govern, secure, incentivize, and scale** the entire network.


# 👥 Validators vs Delegators

In the QIE network, both **validators** and **delegators** play essential roles in securing the blockchain and participating in its economic and governance systems. However, their responsibilities, risks, and rewards differ.

Below is a side-by-side comparison:

***

## 🧑‍⚖️ Validators

| **Role**             | Actively participate in block production, consensus, and governance.                                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Responsibilities** | <p>- Propose and validate blocks<br>- Secure the network via staking<br>- Distribute rewards<br>- Vote on governance proposals<br>- Maintain node infrastructure</p> |
| **Rewards**          | Earn block rewards, transaction fees, and commissions from delegators.                                                                                               |
| **Risks**            | <p>Subject to <strong>slashing</strong> and <strong>jailing</strong> for:<br>- Downtime<br>- Double signing<br>- Misbehavior</p>                                     |
| **Requirements**     | <p>- Run a full validator node<br>- Maintain high uptime<br>- Technical expertise<br>- QIE self-stake</p>                                                            |
| **Governance**       | Full voting rights on proposals. Their votes influence network decisions.                                                                                            |

## 🙋 Delegators

| **Role**             | Stake QIE coins with a trusted validator to earn passive rewards.                                |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| **Responsibilities** | - Choose trustworthy validators - Monitor validator performance - Redelegate or unbond as needed |
| **Rewards**          | Receive a share of validator rewards **after commission** is deducted.                           |
| **Risks**            | Can lose part of their stake if the validator is slashed.                                        |
| **Requirements**     | No need to run a node. Only requires holding QIE and choosing a validator.                       |
| **Governance**       | Indirect. Delegator voting power is passed to the validator they stake with.                     |

| Feature          | **Validator**                     | **Delegator**                 |
| ---------------- | --------------------------------- | ----------------------------- |
| Stake Required   | Yes (self-stake)                  | Yes (delegated to validator)  |
| Node Operation   | Required                          | Not required                  |
| Reward Source    | Block rewards + fees + commission | Share of validator rewards    |
| Risk of Slashing | Yes                               | Yes (if validator misbehaves) |
| Technical Skill  | High                              | Low                           |
| Governance Power | Direct                            | Indirect (via validator)      |

Validators and delegators **work together** to maintain network health. Validators secure and govern the chain, while delegators provide support and decentralization through their stake.

> 🤝 Choose your role based on your technical skills, risk tolerance, and level of involvement you want in the QIE ecosystem.


# 🗳 QIE Blockchain Governance Model

QIE Blockchain uses an on-chain, decentralized governance system. it empowers coin holders to submit proposals, vote, and make binding decisions for the protocol.

This page explains how governance works in QIE and how it's configured in the blockchain's genesis parameters.

***

### 📌 What Is On-Chain Governance?

On-chain governance allows all QIE coin holders (via staking) to participate in major decisions such as:

* Parameter changes (e.g., inflation rate, block size , halving)
* Protocol upgrades
* Community fund spending
* Text-based community proposals

Decisions are made through **coin-weighted voting**, and successful proposals are executed automatically by the blockchain.

***

### 🔄 Governance Lifecycle

#### 1. **Proposal Submission**

Anyone can submit a proposal by attaching a deposit of at least `10,000 QIE`.

Proposal types:

* Parameter change
* Community pool spend
* Software upgrade
* Text proposal

If the minimum deposit is not reached during the deposit period, the proposal is discarded.

#### 2. **Deposit Period**

* Duration: `48 hours`
* Required Deposit: `10,000 QIE`
* Denomination: `aqie` (1 QIE = `10^18` aqie)

Community members can contribute to meet the deposit threshold.

#### 3. **Voting Period**

* Begins once the deposit threshold is met
* Duration: `48 hours` (or `24 hours` for expedited proposals)
* Voting Options:
  * ✅ Yes
  * ❌ No
  * 🛑 NoWithVeto (burns deposit if threshold is reached)
  * ⚪ Abstain

Only staked QIE is eligible to vote. Delegators may override their validator’s vote.

#### 4. **Tally & Results**

A proposal passes if:

* **Quorum**: ≥ 33.4% of total staked QIE voted
* **Threshold**: ≥ 50% of non-abstain votes are "Yes"
* **Veto**: < 33.4% voted "NoWithVeto"

If vetoed, the proposer’s deposit is **burned**.

#### 5. **Execution**

If approved:

* Parameter changes are applied automatically
* Fund transfers are executed
* Upgrade proposals are scheduled

***

### ⚙️ QIE Governance Parameters

These values are configured in the blockchain’s `genesis.json`.

#### Deposit Parameters

| Parameter             | Value                      |
| --------------------- | -------------------------- |
| Minimum Deposit       | `10,000 QIE`               |
| Max Deposit Period    | `48 hours`                 |
| Expedited Min Deposit | `20,000 QIE`               |
| Denomination          | `aqie` (1 QIE = 10¹⁸ aqie) |

#### Voting Parameters

| Parameter               | Value      |
| ----------------------- | ---------- |
| Voting Period           | `48 hours` |
| Expedited Voting Period | `24 hours` |

#### Tally Parameters

| Parameter                      | Value |
| ------------------------------ | ----- |
| Quorum                         | 33.4% |
| Threshold (Yes Votes Required) | 50%   |
| Veto Threshold                 | 33.4% |
| Expedited Threshold            | 66.7% |
| Minimum Initial Deposit Ratio  | 0%    |
| Minimum Deposit Ratio          | 1%    |
| Proposal Cancel Ratio          | 50%   |

***

### 🔥 Deposit Burning Rules

Burning applies only under certain conditions.

| Scenario                                | Burned |
| --------------------------------------- | ------ |
| Quorum not reached                      | ❌ No   |
| Proposal rejected during deposit period | ❌ No   |
| Proposal vetoed by >33.4% "NoWithVeto"  | ✅ Yes  |

This mechanism discourages spam and harmful proposals.

***

### 🛑 Proposal Cancellation

Proposals can be canceled if at least **50% of voting power** agrees. No destination address is set, so default cancellation applies (no refund if burned).

***

### ✅ Summary

| Feature             | Value                         |
| ------------------- | ----------------------------- |
| Minimum Deposit     | `10,000 QIE`                  |
| Voting Period       | `48 hours`                    |
| Quorum              | 33.4% of staked QIE           |
| Pass Threshold      | 50% "Yes" (excluding abstain) |
| Veto Threshold      | 33.4% "NoWithVeto"            |
| Expedited Threshold | 66.7%                         |
| Burn on Veto        | ✅ Yes                         |

***

### 💡 Notes for Community

* You must **stake QIE** to vote.
* Delegators inherit validator votes by default.
* Voting power is proportional to staked QIE.
* Deposit and vote amounts use the smallest unit: `aqie`.


# 🗳 QIE Blockchain Governance: Step-by-Step Guide

### Prerequisites

* `qied` CLI installed and fully synced
* Wallet funded with enough coins (≥ min deposit, e.g., 10,000 QIE)
* Chain ID and RPC node URL
* coin denom is `aqie` (1 QIE = 10^18 aqie)

#### Step 1: Create Proposal File

Create a file named `proposal.json` with:

```
{
  "title": "Example Proposal Title",
  "description": "This is a test proposal for demonstration purposes.",
  "type": "Text",
  "deposit": "10000000000000000000000aqie"
}

```

*Note:* Deposit is 10,000 QIE (in raw form `aqie`).

***

#### Step 2: Submit Proposal

Run:

```
qied tx gov submit-proposal ./proposal.json \
  --from <key_name> \
  --chain-id qie_1990-1 \
  --node "tcp://node5mainnet.qie.digital:26657" \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --gas auto \
  -y

```

Replace placeholders accordingly.

***

#### Step 3: Confirm Proposal ID

After submission, look for output similar to:

```
"proposal_id": "1"
```

Save this proposal ID for future steps.

***

#### Step 4: Deposit More Coins (Optional)

If the initial deposit is insufficient, deposit more:

```
qied tx gov deposit 1 1000000000000000000000aqie \
  --from <key_name> \
  --chain-id qie_1990-1 \
  --node "tcp://node5mainnet.qie.digital:26657" \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --gas auto \
  -y

```

***

#### Step 5: Vote on Proposal

Vote options: `yes`, `no`, `abstain`, `nowithveto`

```
qied tx gov vote 1 yes \
  --from <key_name> \
  --chain-id qie_1990-1 \
  --node "tcp://node5mainnet.qie.digital:26657" \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --gas auto \
  -y

```

***

#### Step 6: Check Proposal Status

```
qied query gov proposal 1 --node "tcp://node5mainnet.qie.digital:26657"
```

***

#### Step 7: View All Proposals

```
qied query gov proposals --node "tcp://node5mainnet.qie.digital:26657"
```

***

#### Optional Queries

* **Tally votes:**

```
qied query gov tally 1 --node "tcp://node5mainnet.qie.digital:26657"
```

Example output fields:

`yes`: total yes votes

`no`: total no votes

`abstain`: total abstain votes

`no_with_veto`: total veto votes

* **List votes:**

```
qied query gov votes 1 --node "tcp://node5mainnet.qie.digital:26657"
```


# 🎯 Why Become a QIE Validator?

### 🚀 Why Become a QIE Validator?

Becoming a validator on QIE isn’t just about earning rewards — it’s about being a core part of a high-performance, real-use Layer 1 blockchain designed for the future of DeFi and GameFi.

Here’s why you should consider joining as a validator:

***

#### ✅ 1. Earn Daily Rewards + Commission

* Receive **daily staking rewards** for validating blocks and supporting consensus.
* **Set your own commission rate** and earn a portion of the rewards generated by your delegators.
* Benefit from consistent and transparent reward cycles.

***

#### ⚙️ 2. Operate in a Dual-Ecosystem (EVM + Cosmos)

* QIE is built with **Cosmos SDK** and **EVM compatibility**, giving validators access to both ecosystems.
* Participate in a chain designed to bridge smart contracts, IBC-enabled modules, and scalable dApps — all under one network.

***

#### 🧠 3. Participate in On-Chain Governance

* As a validator, you help shape QIE’s future by **voting on key proposals**:
  * Coin emission and halving schedules
  * Protocol upgrades
  * Parameter changes
  * Community initiatives

Your vote carries real weight and community impact.

***

#### 🔥 4. Benefit from a Deflationary Coin Model

* QIE has **no unlimited minting** — rewards come from a **fixed supply**.
* A portion of **transaction fees is burned**, creating deflationary pressure over time.
* As demand grows, coin scarcity can enhance long-term value for participants.

***

#### 🌐 5. Join a Real-Use Layer 1 for DeFi & GameFi

* QIE isn’t just theoretical — it’s built for **real-world applications**.
* With a focus on **DeFi**, **GameFi**, and **interoperable infrastructure**, QIE is positioned for long-term adoption.
* Validators support a **mission-driven chain**, not just a network.

***

#### 🧩 Whether you're...

* A **builder** who wants to influence the chain’s direction
* A **validator operator** seeking a high-utility network
* An **ecosystem partner** looking to align with sustainable incentives

**QIE rewards your participation.**


# 🔄 Validator Lifecycle: Your Journey on QIE

#### 1. 🧱 Set Up Your Node

Prepare your hardware and infrastructure. Install the QIE software and configure your node to connect to the network.

#### 2. 📝 Register as a Validator

Submit your validator details on-chain, including your public key, commission rate, and self-stake.

#### 3. ✅ Start Validating Blocks

Once registered, begin proposing and validating blocks to help secure the network.

#### 4. 🤝 Receive Delegations

Attract delegators who stake their QIE coins with you, increasing your total voting power and rewards.

#### 5. 💸 Distribute Rewards

Earn block rewards, transaction fees, and commissions. Share rewards with your delegators transparently.

#### 6. 🗳️ Participate in Governance

Vote on proposals that affect the network’s future — upgrades, parameter changes, halving, and more.

#### 7. 🔚 Exit or Unbond (Optional)

If you decide to step down, you can unbond your stake after the unbonding period and cease validating.

***

#### ⚠️ Key to Success: Uptime & Trust

Maintaining **high uptime** and **good reputation** is essential to stay in the active validator set and keep earning rewards. Validators with poor performance risk jailing or slashing penalties.

***

This lifecycle reflects the ongoing commitment and opportunity of being a QIE validator — securing the network while earning rewards and influencing the blockchain’s future.


# 🚀 How to Become a Validator on QIE V3

Becoming a validator on QIE V3 is a straightforward process. This guide will walk you through the required setup, installation, wallet creation, and validator registration.

<br>


# 📦 1. System Requirements

Before starting, ensure you have the following:

| Component    | Recommended Minimum                       |
| ------------ | ----------------------------------------- |
| OS           | Ubuntu 20.04 / 22.04 LTS                  |
| CPU          | 4 Cores (modern AMD/Intel)                |
| RAM          | 4 GB                                      |
| SSD          | 200+ GB of storage                        |
| Network      | Static IP + open ports (TCP: 26656/26657) |
| Uptime       | 24/7 availability                         |
| Dependencies | Go ≥ 1.20, Git, jq, curl                  |


# 🔧 2. Install QIE Node

🛠️ Step-by-Step Node Setup

#### 🔁 Step 1: Clone the QIE Repository

```bash
cd $HOME
sudo apt-get install wget
wget https://github.com/qieadmin/qiev3-mainnet/releases/download/v3/qiemainnetv3.zip
unzip qiemainnetv3.zip
cd QIEV3Mainnet
rm -rf qied
wget https://github.com/qieadmin/qiev3-mainnet/releases/download/QIE-Mainnet-V6/qied
chmod +x qied
```

***

#### 🧭 Step 2: Add the Binary to Your PATH

In the QIEV3Mainnet directory, run:

```bash
sudo cp -r ./qied /usr/bin
cd $HOME
```

This allows you to use `qied` globally from anywhere.<br>


# 🪪 3. Initialize Your Node

#### 🧰 Step 1: Initialize the Node

```bash
qied init --chain-id="qie_1990-1" <your-name> --home "<path-to-config>"
```

**Example :**

```bash
qied init --chain-id="qie_1990-1" validator --home "$HOME/.qieMainnetNode"
```

This will generate the required structure in `~/.`qieMainnetNode, including:

* `config/` – blockchain config files
* `data/` – block data


# 🌐 4. Configure Your Node

#### 🧾 Step 1: Replace the Genesis File

Delete the auto-generated genesis file and other files as well :

```bash
rm -rf  $HOME/.qieMainnetNode/config/genesis.json
rm -rf  $HOME/.qieMainnetNode/config/config.toml
rm -rf  $HOME/.qieMainnetNode/config/client.toml
rm -rf  $HOME/.qieMainnetNode/config/app.toml
```

***

#### 🧾 Step 2: Replace the Genesis File and others.

```bash
cp -r $HOME/QIEV3Mainnet/genesis.json $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/config.toml $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/client.toml $HOME/.qieMainnetNode/config
cp -r $HOME/QIEV3Mainnet/app.toml $HOME/.qieMainnetNode/config
```

Then, copy the `genesis.json` and other Necesories files from your existing Node 1 and place it here.

***

#### &#x20;🧾 Step 3: Set a Name for Your Validator Node

To personalize and identify your validator node on the QIE Mainnet, you need to set a unique name (moniker). This name will be visible on the [QIE Validators Page](https://mainnet.qie.digital/validators).

**🔧 Edit the Configuration File**

Run the following command to open the configuration file in the terminal:

```
nano $HOME/.qieMainnetNode/config/config.toml
```

Inside the file, locate the following line :

```
moniker = "<Add_your_name>"
```

Replace `"<Add_your_name>"` with your preferred **unique** node name. This will serve as your validator identity on the network.

> 💡 **Tip:** Choose a recognizable and meaningful name, especially if you plan to become a validator.

**💾 Save and Exit**

After editing the line:

1. Press `Ctrl + X` to exit.
2. Press `Y` to confirm saving the changes.
3. Hit `Enter` to finalize and close the file.

Your node name has now been successfully updated!


# 🔁 5. Start Your Node With Screen

#### ▶️ Step 1: Config the screen(separate screen) to start the node

<pre class="language-bash"><code class="lang-bash"><strong>
</strong>sudo apt update
sudo apt install screen
screen -S node
</code></pre>

#### ▶️ Step 2: Start the Node

<pre class="language-bash"><code class="lang-bash"><strong>
</strong><strong>qied start --home "$HOME/.qieMainnetNode"
</strong></code></pre>

Your node will begin syncing with the network.

***

#### ⏳ Step 3: Wait for Full Sync

You’ll see blocks being synced in logs.

You can also verify sync status using :

```bash
curl localhost:26657/status
```

Your node will begin syncing with the network.\
\
NOTE - Once node started , To press Control +A+D at the same time to exit from screen.


# ▶️Start Your Node With Systemd Service

## ⚙️ Create Systemd Service

### Step 1: Create Service File

```bash
sudo nano /etc/systemd/system/qied.service
```

***

### Step 2: Paste Service Configuration

#### 🔐 Recommended Secure Version

```ini
[Unit]
Description=QIE Daemon (qied)
After=network-online.target
Wants=network-online.target

[Service]
User=root
Group=root
Environment=HOME=/root
WorkingDirectory=/root

ExecStart=/usr/bin/qied start --home /root/.qieMainnetNode

Restart=on-failure
RestartSec=5
StartLimitIntervalSec=600
StartLimitBurst=10

OOMScoreAdjust=-1000

Environment=GOMEMLIMIT=6GiB
Environment=GOGC=100

LimitNOFILE=65536
LimitNPROC=4096

StandardOutput=journal
StandardError=journal

TimeoutStartSec=120
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target


```

Save and exit.

## 🔄 Reload Systemd

```bash
sudo systemctl daemon-reload
```

***

## ▶️ Start the Node

```bash
sudo systemctl start qied
```

Check status:

```bash
sudo systemctl status qied
```

***

## 🔁 Enable Auto Start on Boot

```bash
sudo systemctl enable qied
```

Now the node will start automatically after server reboot.

***

## 📜 View Logs

#### Live Logs

```bash
sudo journalctl -u qied -f
```

#### Previous Logs

```bash
sudo journalctl -u qied --no-pager
```

***

## 🛑 Stop / Restart Node

#### Stop

```bash
sudo systemctl stop qied
```

#### Restart

```bash
sudo systemctl restart qied
```

***

## 🧠 Service Configuration Explanation

| Parameter            | Purpose                        |
| -------------------- | ------------------------------ |
| `ExecStart`          | Runs the QIE daemon            |
| `Restart=on-failure` | Auto-restarts if node crashes  |
| `GOMEMLIMIT=6GiB`    | Limits Go memory usage         |
| `GOGC=100`           | Controls garbage collection    |
| `LimitNOFILE=65536`  | Supports high P2P connections  |
| `OOMScoreAdjust`     | Protects from Linux OOM killer |
| `TimeoutStartSec`    | Startup timeout protection     |


# 💼 6. Create Wallet (Keypair)

### 🧰 Step 1: Create Your Wallet (Key Pair)

This will generate a new wallet address to become a validator.

```bash
qied keys add validator --home "$HOME/.qieMainnetNode"
```

This command ask for wallet password , to unlock the wallet.\
\
Output -

```
 address: qied19y2ul696lc6lz640pldete7h7jzdc0xj32wt6j
  name: validator
  pubkey: '{"@type":"/ethermint.crypto.v1.ethsecp256k1.PubKey","key":"A6ZBh5i6s/ToIdY8PhV9XRO5EKYeK1MPYolKpEJreEB3"}'
  type: local
```

📌 **What this does**:\
It creates a wallet inside the folder $HOME./qieMainnetNode . You’ll see:<br>

* An address like `qie1xyz...` (your validator wallet)
* A public key (used for staking)


# 🪙 7. Get Some QIE Coins

#### 💰 **Step 1: Check Account Balance**

```bash
qied query bank balances <your_qie_address> \
  --node tcp://localhost:26657 \
  --home "$HOME/.qieMainnetNode"

```

***

#### 🔑 Step 2: Get Your Validator Address

Bech32 address:

```bash
qied keys list --keyring-backend os --home "$HOME/.qieMainnetNode"
```

0x (EVM) form:

```bash
qied debug addr $(qied keys show validator -a --keyring-backend os --home "$HOME/.qieMainnetNode")
```

Use either address to check your balance on the explorer. If the account has insufficient funds for the amount you want to stake, send the required funds to this address.

> ⚠️ Never import the validator key into MetaMask or any browser wallet. If the browser or extension is compromised, your stake and signing account are lost.


# 🏁 8. Register Your Validator

### 🔍 Step 1: Get the Correct Public Key (for Validator)

Validators use a special **Cosmos-based public key** (not EVM key). To get it:

```bash
qied tendermint show-validator --home "$HOME/.qieMainnetNode"
```

Copy the output — it should look like this:

```json
{"@type":"/cosmos.crypto.ed25519.PubKey","key":"LaUx9x1Nlj4t9Yy5ybFJR55/7kCK8eGn8JlY/mBewuU="}
```

✅ **Keep this key safe** — you’ll need it in the next step.

### 📄 Step 2: Create a Validator Configuration File

Now create a file named `validator.json` in your terminal ( $HOME/.qieMainnetNode):

```json
{
  "pubkey": <paste here your generated public key step no 1> ,
  "amount": "10000000000000000000000aqie", 
  "moniker": "<Name your validator>",
  "identity": "<optional>",
  "website": "<your project website -if any>",
  "security": "",
  "details": "<Details about the validator>",
  "commission-rate": "0.1",
  "commission-max-rate": "0.2",
  "commission-max-change-rate": "0.01",
  "min-self-delegation": "1000"
}
```

📌 **What this means**:<br>

* **pubkey** – Your validator's consensus public key (used for block signing).
* **amount** – The amount you are staking as a validator.
* **moniker** – The name of your validator (shown in explorers).
* **identity** – (Optional) Keybase ID for validator identity verification.
* **website** – Your validator or project website (optional).
* **security** – Contact info for reporting security issues (optional).
* **details** – A short description of your validator.
* **commission-rate** – The percentage you charge delegators from their rewards.
* **commission-max-rate** – The highest commission you can ever charge.
* **commission-max-change-rate** – The max commission change allowed per day.
* **min-self-delegation** – Minimum coins you must stake to stay active.

### 🚀 Step 3: Submit the Validator Transaction

Now you’ll officially become a validator by submitting the transaction:

```bash
qied tx staking create-validator ./validator.json \
--from validator \
--chain-id qie_1990-1 \
--home "$HOME/.qieMainnetNode" \
--node "tcp://localhost:26657" \
--gas auto \
--gas-adjustment 1.5 \
--gas-prices 10000000000aqie 
```

* This transaction will prompt you for your wallet password, which you set during wallet creation.

📌 **What this does**:\
It tells the network: “I want to become a validator using this wallet and stake.”

***


# 📡 9. Verify Your Validator

### 🗳️ Step 9: Confirm You're a Validator

Now check the validator list to confirm you're in it:

```bash
qied query staking validators \
--chain-id qie_1990-1 \
--node "tcp://localhost:26657"
```

📌 Look for your `moniker` (name) or wallet address in the list.

<br>

Or visit:[ h](https://mainnet.qie.digital/validators)ttps\://mainnet.qie.digital/validators

<br>


# ✅ Congratulations!

You're now an active validator on QIE V3. From here, make sure to:<br>

* Maintain high uptime
* Participate in governance
* Communicate with the QIE validator community
* Optimize your commission settings\ <br>


# 💸 Validator Rewards

**QIE V3** is built to reward good behavior and penalize bad actors — ensuring fairness and network health.

* ✅ **Daily, transparent rewards** are provided to active and honest validators for their role in securing the network.
* ⚠️ **Penalties**, such as slashing and jailing, are enforced for downtime or protocol violations.

This balanced system ensures the QIE network remains **secure**, **reliable**, and **decentralized**, with clear incentives for consistent validator performance.


# 🎁 Validator Reward System

In the QIE network, validators play a crucial role in maintaining the blockchain — and are rewarded accordingly. Validators earn income from **three primary sources**:

***

#### 1. 🧱 Block Rewards

* Validators earn **block rewards** each time they **successfully propose and validate a block**.
* This reward incentivizes validators to stay online, follow protocol rules, and help maintain consensus.

***

#### 2. 💸 Transaction Fees

Transaction fees in QIE are split into two parts:

* 🔥 **Base Fees** — These are **burned**, permanently removed from circulation.\
  This helps reduce total coin supply over time (deflationary effect).
* 🏅 **Priority Fees (Tips)** — These are awarded to the **validator who validates the block**.\
  It serves as an extra incentive for validators to include and prioritize user transactions.

***

#### 3. 🤝 Delegation Commissions

* Validators earn a **commission** on the staking rewards generated by their **delegators**.
* Each validator can set their own commission rate.

> ⚠️ **Delegators** receive the **remaining portion** of the staking rewards **after the validator's commission is applied**.

***

#### 📌 Summary Table

| Source                 | Earned By                  | Notes                                                 |
| ---------------------- | -------------------------- | ----------------------------------------------------- |
| Block Rewards          | Block proposer & validator | For proposing and validating blocks                   |
| Priority Fees          | Block validator            | Tips from transactions included in the block          |
| Delegation Commissions | Validator                  | A percentage cut from rewards generated by delegators |


# 🕒 Frequency of Rewards

#### ✅ Rewards Distributed Daily

All staking rewards — including **block rewards**, **transaction fees**, and **delegation rewards** — are:

* **Automatically distributed every 24 hours**
* With **no long waiting periods or epochs**
* Ensuring **regular and predictable income** for validators and delegators

***

#### 🧾 Why This Matters

* 💰 **Better cash flow** for validators
* 🔍 **Greater transparency** for delegators
* ⚡ **Faster access** to earned rewards without unnecessary delays

This daily distribution model keeps the staking experience smooth, efficient, and rewarding.


# 🧮 Reward Calculation Formula (Simplified)

Validator rewards in QIE are based on a combination of stake share, performance, and commission. Here's how they are calculated:

🧮 **Reward Formula**

```
Validator Reward = 
  (Validator Stake / Total Active Stake) × Daily Emission  
  + Validator Commission × Delegator Rewards  
  + Block Proposal Rewards

```

\
🔍 Breakdown:

1. **Proportional Emission Share**
   * The validator earns a share of the daily coin emission based on their **stake weight** relative to the total active stake.
2. **Delegation Commission**
   * Validators apply a **commission** on the rewards generated by their delegators.
   * This is an additional income stream, defined by each validator’s chosen commission rate.
3. **Block Proposal Rewards**
   * Validators who **propose blocks** receive extra rewards as an incentive for block production.

***

This formula ensures validators are rewarded fairly based on their contribution to network security, participation, and delegation support.


# 💼 Tips to Maximize Validator Profitability

Running a validator is not just about staying online — it’s about building trust, optimizing performance, and engaging with the community. Here are key strategies to increase your earnings as a QIE validator:

***

#### 🧩 1. Maintain High Uptime and Performance

* Keep your node **online 24/7** with low latency and consistent connectivity.
* Downtime reduces rewards and increases the risk of **jailing or slashing**.

✅ Use monitoring tools and alerts to stay proactive.

***

#### 🔄 2. Set a Competitive Commission Rate

* Choose a **commission rate** that reflects your performance and effort while staying competitive with other validators.
* Too high may drive away delegators; too low may not cover your operational costs.

💡 Review and adjust rates periodically to stay relevant in the validator ecosystem.

***

#### 📢 3. Engage Your Delegator Community

* Build trust by being **transparent**, sharing updates, and **communicating regularly**.
* Help delegators understand how rewards work and why you’re a reliable validator.

🤝 A strong relationship with delegators encourages loyalty and more stake delegation.

***

#### 🛡 4. Follow Security Best Practices

* Protect your validator infrastructure with:
  * 🔐 **2FA (Two-Factor Authentication)**
  * 🔥 **Firewalls & regular updates**
  * 🗂 **Secure backups of keys and configs**

🛠 A secure setup prevents costly slashing and ensures uninterrupted operations.

***

#### 🗳 5. Participate in On-Chain Governance

* Vote on governance proposals to stay active in shaping the network.
* Validators who engage in governance gain **more visibility** and build **community trust**.

📈 This can attract more delegators who want to support responsible and involved validators.

***

By following these best practices, validators can **maximize rewards**, minimize risks, and grow their influence within the QIE ecosystem.


# 🔁 Manage Your Validator

If you're running a validator on the QIE blockchain, you’re eligible to earn rewards and commissions. This page explains—step by step—how you can:

* ✅ Check and claim your **staking rewards**
* ✅ Check and claim your **commission**
* 🔓 **Unstake** your QIE  coins
* 🔁 **Restake** or **increase your staking** as a validator

This guide is designed to be beginner-friendly. You don’t need to be highly technical—just follow along carefully.

***

### ✅ How to Check and Claim Your Rewards

When you stake QIE coins, you earn **staking rewards**. These build up over time, and you can claim them whenever you like.

#### 🔍 Step 1: Check Your Rewards

1. Visit the official validator explorer:\
   <https://mainnet.qie.digital/validators>
2. Find your validator and click on its name.
3. On the validator detail page, you’ll see information like:
   * Rank
   * Description
   * Commission
   * Voting power
   * **Rewards received**
   * **Commission received**

If the "Rewards received" section shows a number greater than 0 — congratulations! You have rewards to claim.

***

#### 💰 Step 2: Claim Your Rewards

On the machine where your node is running, run the following command:

```
qied tx distribution withdraw-rewards <your-validator-address> \
  --from validator \
  --chain-id qie_1990-1 \
  --gas auto \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --home "$HOME/.qieMainnetNode/" \
  --yes

```

> 📝 **Note**: You’ll be asked for your wallet password. Enter the one you created when you set up the wallet.

**🔎 How to find your validator address:**

Go to <https://mainnet.qie.digital/validators>, find your validator, and click on its name. Your validator address will be shown at the top of the page.

**✅ Confirm your rewards are claimed:**

Check the "Rewards received" again. If the value is now 0 (or very close), you’ve successfully claimed your rewards. You can also check your Metamask wallet to confirm the reward coins have arrived.

### 💼 How to Claim Commission from Delegators

As a validator, you also earn **commission** from delegators. Here’s how to claim it.

#### 🔍 Step 1: Check Commission

1. Visit: <https://mainnet.qie.digital/validators>
2. Click on your validator’s name.
3. Look for the **Commission received** section. If there's a value greater than 0, you can claim it.

***

#### 💰 Step 2: Claim Commission

Use the command below from your validator machine:

```
qied tx distribution withdraw-rewards <your-validator-address> \
  --commission \
  --from validator \
  --chain-id qie_1990-1 \
  --gas auto \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --home "$HOME/.qieMainnetNode/" \
  --yes

```

Again, enter your wallet password when prompted.

**✅ Confirm it worked:**

Revisit the validator page and check the **"Commission received"** section. If it’s now 0 or a small amount, the commission has been claimed. You should also see the commission in your Metamask wallet.

***

### 🔓 How to Unstake Your QIE Coins

> <https://docs.qie.digital/delegators-in-qie-v3/manage-your-delegation#how-to-unstake-undelegate-your-qie-coins>

***

### 🔁 How to Restake or Increase Your Staking as a Validator

If you want to add more QIE coins to your current stake (or restake previously claimed rewards), follow these steps.

#### 🔁 Step-by-Step: Increase Your Stake

Use this command on the machine where your validator is running:

```
qied tx staking delegate <your-validator-address> 10000000000000000000000aqie \
  --from validator \
  --chain-id qie_1990-1 \
  --gas auto \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --home "$HOME/.qieMainnetNode/" \
  --yes

```

#### ℹ️ Important Notes:

* **Validator Address**: Find it by visiting\
  <https://mainnet.qie.digital/validators>, clicking on your validator, and copying the address from the top.
* **Amount in wei**:\
  QIE uses **18 decimal places**, just like Ethereum.

  * Example:
    * 1 QIE = `1000000000000000000` aqie (in wei)
    * 10,000 QIE = `10000000000000000000000` aqie

  Use this converter to make it easier:\
  <https://eth-converter.com/>

#### ✅ After the Transaction

Once the transaction is successful:

* The staked amount + gas fee will be deducted from your wallet
* Visit the validator page again to confirm the updated **staked amount**
* You can also check your wallet to verify the transaction and balance changes

***

### 🎉 You're All Set!

Managing your validator on QIE doesn’t have to be complex. With these commands and checks, you can keep your validator running smoothly, maximize your earnings, and stay in control of your funds.

If you get stuck or need help, don't hesitate to reach out to the QIE community.

***


# 💥 Slashing & Jailing in QIE V3

In QIE V3, **validator performance and honesty** are essential for maintaining a secure and healthy network. To uphold accountability, the protocol enforces **penalties** known as **slashing** and **jailing** against validators who violate rules or fail in their duties.

This section covers:

* What **slashing** and **jailing** mean
* Which validator behaviors trigger these penalties
* How validators and delegators can **avoid** penalties
* Steps to take if a validator is **slashed or jailed**


# ❌ What is Slashing?

### ⚠️ What Is Slashing?

**Slashing** is an automatic penalty mechanism that removes a portion of a validator’s staked QIE coins — including both their own stake and their delegators’ stakes.

This penalty is enforced when a validator violates protocol rules or behaves in a way that harms the network.

***

#### Why Does Slashing Exist?

Slashing helps to:

* **Discourage harmful or careless behavior**
* **Protect the security and integrity of the network**
* **Align incentives so validators remain honest and active**

***

#### Common Reasons for Slashing

Validators can be slashed for:

* 💤 **Downtime:** Being offline or missing block validations
* ⚔️ **Double Signing:** Signing two conflicting blocks at the same height (a serious fault)
* 🧊 **Inactivity in Governance:** (Optional) Failing to participate in on-chain governance votes if configured
* 🔒 **Not Maintaining Minimum Self-Delegation:** Validators must keep a minimum amount of their own coins staked to remain active

***

#### How Slashing Affects Delegators

* When a validator is slashed, **delegators’ stakes with that validator are also partially penalized**
* This creates a strong incentive to choose reliable and trustworthy validators

***

#### Summary

Slashing is a crucial security feature that:

* Protects the network from bad actors
* Encourages validators to perform their duties responsibly
* Ensures delegators’ stakes are backed by honest participation


# 🪤 What is Jailing?

### 🚫 What Is Jailing?

**Jailing** is a temporary suspension that removes a validator from the active validator set. When a validator is jailed:

* They **stop producing blocks**
* They **do not receive any rewards**
* Delegators **stop earning staking rewards** from that validator

***

#### Why Does Jailing Happen?

Validators can be jailed due to:

* ⏳ **Prolonged downtime** — being offline for too long
* ⚠️ **Slashing offenses** — committing serious protocol violations
* ⚙️ **Software misconfiguration** — such as using the wrong chain ID or incorrect genesis file

***

#### What Happens After Jailing?

* The validator remains jailed until they **fix the issue and submit an unjail transaction**
* Once unjailed, the validator can **resume participation** and **earn rewards again**

***

#### Summary

Jailing protects the network by:

* Temporarily removing validators who are misbehaving or offline
* Ensuring only active, well-behaved validators secure the blockchain
* Encouraging validators to maintain proper configuration and uptime


# 📉 Slashing Conditions & Penalties

### ⚠️ Double Signing: A Serious Offense

**Double signing** occurs when a validator signs two conflicting blocks at the same block height. This is considered the most severe violation in the network.

#### Consequences of Double Signing:

* 🚫 **Permanent loss of validator reputation** — trust from the community is severely damaged
* 💸 **Loss of stake** — both the validator’s and their delegators’ coins are slashed as a penalty
* ⚠️ **Community distrust** — undermines confidence in the validator and the network’s security

***

Double signing is treated very seriously to protect the network’s integrity and maintain trust in its validators.


# 🩺 How to Check Your Validator's Health and Unjail It (If Needed)

If you are running a QIE validator, it's important to regularly check its health status. Validators can sometimes get **jailed** for issues like being offline (downtime) or double-signing. This guide explains how to check your validator's status and what to do if it gets jailed.

## ✅ How to Check If Your Validator Is Jailed or Active

* Open this page in your browser:\
  👉 <https://mainnet.qie.digital/validators>
* Scroll through the list to **find your validator**.&#x20;
* Click on your validator’s name to view details.
* On the validator's page, you’ll see information such as:
  * **Rank**
  * **Description**
  * **Commission Rate**
  * **Max Commission**
  * **Validator Address**
  * **Website**
  * **Status** (in the top-right corner)
* Look at the **Status**:
  * If it says **Active** – ✅ your validator is healthy and participating in consensus.
  * If it says **Jailed** – ⚠️ your validator has been jailed and is not currently active.

## Why a Validator Might Be Jailed

### A validator can be jailed for the following reasons:

* **Downtime** (most common):\
  This happens if your validator doesn't sign enough blocks (i.e., it's offline too often).
  * **Penalty**: 0.01% of your total staked amount
  * **Jail Duration**: 1 hour
* **Double Signing** (rare, but serious):\
  This means your validator signed two different blocks at the same height, which is considered malicious.
  * **Penalty**: 5% of your total staked amount
  * **You may not be able to unjail** if double-signing is detected.

> ℹ️ **In most cases**, validators are jailed due to downtime — often caused by network or server issues.

***

## 🔓 How to Unjail Your Validator (After Downtime)

If your validator was jailed due to downtime and the 1-hour jail period has passed, you can manually unjail it by following these steps:

**1. Run the unjail command:**

```
qied tx slashing unjail \
--from validator \
--chain-id qie_1990-1 \
--home "$HOME/.qieMainnetNode" \
--gas auto \
--gas-adjustment 1.5 \
--gas-prices 10000000000aqie \
--yes
```

📌 Make sure to replace `validator` with your **wallet name or key name** associated with the validator.

**2. Wait for Transaction Confirmation**

* After running the command, you'll receive a **transaction hash (tx hash)**.
* Wait **5–10 minutes** for the network to process it.

**3. Verify Your Validator Status Again**

* Go back to <https://mainnet.qie.digital/validators>
* Search for your validator again.
* Confirm that the **status has changed from "Jailed" to "Active"**.

## 🛡️ Final Tips

* Always monitor your validator to avoid getting jailed.
* Set up alerts or monitoring tools if possible.
* Keep your node software and infrastructure stable and up to date.


# 🧠 Best Practices to Avoid Slashing

Slashing penalties can lead to loss of coins for both validators and delegators. To protect your stake and help maintain a secure network, follow these best practices:

***

#### 1. Choose Reliable Validators

* Delegate to validators with a strong track record of **uptime** and **good performance**.
* Check validator histories on explorers to avoid those frequently jailed or penalized.

***

#### 2. Keep Validator Nodes Online and Updated (For Validators)

* Run validator nodes on reliable hardware with stable internet connections.
* Regularly update your node software to the latest stable versions to avoid configuration issues.

***

#### 3. Monitor Validator Status Regularly

* Use blockchain explorers and monitoring tools to keep an eye on your validator’s health and status.
* Set up alerts to be notified immediately of any downtime or slashing events.

***

#### 4. Maintain Minimum Self-Delegation (Validators)

* Ensure you keep the required minimum amount of your own coins staked to avoid being jailed for insufficient self-delegation.

***

#### 5. Act Quickly if Jailed

* If your validator gets jailed, submit the **unjail transaction promptly** after fixing the issue to minimize downtime and lost rewards.

***

#### 6. Stay Informed on Network Updates

* Follow official announcements and upgrade guides to remain compliant with protocol changes and avoid unintentional slashing due to outdated software.

***

#### 7. Delegate Responsibly (For Delegators)

* Diversify your delegation to multiple trustworthy validators to reduce risk.
* Regularly review validator performance and redelegate if needed.


# 🧾 Slashing FAQs

### ❓ Slashing FAQ

#### Will my delegators lose their coins too?

**Yes.**\
Slashing penalties apply to the entire bonded stake — this includes both the validator’s own coins and the coins delegated by their delegators.\
That’s why it’s essential to choose validators with **high transparency**, **excellent uptime**, and a strong reputation for reliable operation.

***

#### How many missed blocks cause jailing?

The exact threshold depends on the network’s parameters. For example:

* Missing **5% of blocks within a recent window of 10,000 blocks** can trigger downtime slashing and jailing.

***

#### Can I rejoin after being jailed?

**Yes, but only if the jailing was not due to double signing.**

* Fix the issue that caused the jailing (e.g., resolve downtime or configuration problems).
* Ensure your validator account has sufficient funds to pay transaction fees.
* Submit the unjail transaction to reactivate your validator.

***

#### What happens if a validator double signs?

Double signing is a **severe offense** that usually results in:

* Permanent slashing of a significant portion of stake
* Immediate and often permanent jailing
* Loss of reputation and trust in the community

Double signing penalties cannot be reversed, so it is critical to prevent this behavior.

***

#### How can I protect myself as a delegator?

* Always delegate to validators with a **good track record** and **transparent operations**.
* Monitor validator performance regularly using explorers and alert systems.
* Consider spreading your delegation across multiple validators to reduce risk.

***

#### Is there a way to recover slashed coins?

No, coins lost due to slashing are permanently removed from the validator and delegator stakes as part of the protocol’s security measures. This ensures malicious or negligent behavior is discouraged.

***

#### What tools can help monitor validator health?

* Use blockchain explorers like [QIE Explorer](https://mainnet.qie.digital/validators) to check validator uptime and status.
* Set up monitoring alerts for downtime, slashing events, and jailing to react quickly if problems occur.

***

Being informed about slashing helps you make smarter delegation choices and protect your investment in the QIE network.


# 👥 Delegators in QIE V3

#### Stake, Earn, and Support the Network

Delegators are the foundation of QIE’s Proof-of-Stake security model. They help secure the blockchain by staking their QIE coins with validators — and in return, they earn a share of the rewards.

<br>


# 🧾 What is a Delegator?

### 🙋‍♂️ What Is a Delegator?

A **delegator** is a QIE coin holder who chooses to **stake their coins with a validator** — instead of running a validator node themselves.

This allows regular users to actively participate in the network without needing to manage any server or infrastructure.

***

#### ✅ What Happens When You Delegate?

By  delegating your QIE coins to a validator, you:

* 🛡️ **Support network security and decentralization**\
  Your coins help strengthen and secure the QIE blockchain.
* 💰 **Earn daily staking rewards**\
  You receive a share of the validator’s rewards, based on your delegated amount (minus their commission).
* 🗳️ **Help determine validator rankings**\
  The more stake a validator has (including delegations), the more likely they are to stay active and participate in block production.

***

#### 📢 Why Delegators Matter

Delegators play a **critical role** in the QIE ecosystem. While validators maintain the blockchain infrastructure, delegators:

* **Help secure the network**
* **Influence which validators remain in the active set**
* **Receive rewards for their participation**

***

#### 🧠 You Don’t Lose Control of Your Coins

When you delegate:

* You still **own your coins**
* You can **unstake (undelegate)** at any time (after a short unbonding period)
* Your coins are **never transferred to the validator** — they are just locked temporarily for staking

***

#### 🚀 Get Started as a Delegator

If you hold QIE and want to contribute to the network **without running a node**, delegating is the simplest and most effective way.


# 💸 Why Delegate?

### 🤔 Why Become a Delegator?

Delegating your QIE coins comes with several important benefits that make it an attractive option for coin holders who want to participate in securing the network **without the complexity of running a validator node**.

#### Key Benefits of Delegating:

* ✅ **Earn Passive Income**\
  Receive a share of the validator’s rewards simply by staking your coins. This is a way to earn regular income while holding QIE.
* ✅ **Support Network Security**\
  Help maintain and secure the QIE blockchain without the need to run your own hardware or manage technical infrastructure.
* ✅ **Choose Your Validator**\
  Select a validator you trust based on factors like their commission rate, reliability, and performance. You have full control over where your stake goes.
* ✅ **Stay Flexible**\
  You can redelegate your coins to a different validator or unbond (unstake) your coins whenever you want, subject to the network’s unbonding period.
* 🔐 **Keep Full Ownership**\
  Your coins remain in your wallet and are never controlled or accessed by the validator — preventing any risk of theft.

***

Delegating is a simple, secure, and rewarding way to actively participate in the QIE network while maintaining control over your assets.


# 🔄 How Delegation Works

### ⚙️ How Delegating Works

#### Step-by-Step Overview

1. **You Stake Your QIE Coins**\
   When you delegate, you lock your QIE coins by assigning them to a validator of your choice.
2. **Validator Includes Your Stake**\
   The validator adds your coins to their total stake, increasing their voting power and influence in the network.
3. **You Earn Daily Rewards**\
   Validators earn rewards from multiple sources and share a portion of those rewards with their delegators every day.

***

#### Where Do Validator Rewards Come From?

Validators collect rewards from three main sources:

* **Block Rewards:**\
  Coins newly minted as rewards for producing blocks.
* **Transaction Fees:**\
  Fees paid by users for processing their transactions on the network.
* **Commission from Delegators:**\
  A small percentage fee charged by validators on the rewards they distribute.

***

#### How Rewards Are Distributed

* Validators **take their commission fee** from the total rewards they earn.
* The **remaining rewards are shared daily with all delegators**, proportional to the amount they have staked.

***

#### Summary Flow

```
You stake QIE coins
       ↓
Validator includes your stake in their total
       ↓
Validator earns rewards (block rewards + fees)
       ↓
Validator takes commission fee
       ↓
Remaining rewards distributed to you daily

```

Delegating is a simple way to participate in network security and earn rewards, without running a validator node yourself.


# 🚀 How to Delegate QIE Coins and Earn Rewards

### ✅ Step 1: Choose a Validator&#x20;

1. Visit the [QIE Validators List](https://mainnet.qie.digital/validators).
2. Browse through the validators and **copy the validator operator address** you want to delegate your QIE coins to.

### 💻 Step 2: Clone the QIE Repository

Open your terminal and run the following commands:

```
cd $HOME
sudo apt-get install wget
wget https://github.com/qieadmin/qiev3-mainnet/releases/download/v3/qiemainnetv3.zip
unzip qiemainnetv3.zip
cd QIEV3Mainnet
```

#### Step 3: Add the Binary to Your PATH

### 🔧 Step 3: Add the Binary to Your PATH

To use the QIEV3Mainnet CLI tool globally:

```
sudo cp -r ./qied /usr/bin
cd $HOME
```

### 🔐 Step 4: Import Your Wallet

To delegate coins, you need a wallet with QIE funds. Use the following command to import it:

```
qied keys add <wallet_name> --recover
```

* Replace `<wallet_name>` with any name you choose for your wallet.
* Enter your **wallet mnemonic phrase** when prompted.
* Set a **password** to secure access.

> ⚠️ **Important:** Copy and save your wallet address. It will be needed for claiming rewards, checking balances, and more.

💰 Step 5: Delegate QIE to a Validator

> ⚠️ Ensure your wallet has enough QIE coins before proceeding.

In QIE, 1 QIE = `1,000,000,000,000,000,000 aqie`.\
So, when specifying the delegation amount, use `aqie` units.

**Examples:**

| QIE (Human-Readable) | aqie (Used in CLI)     |
| -------------------- | ---------------------- |
| 10 QIE               | 10000000000000000000   |
| 100 QIE              | 100000000000000000000  |
| 1000 QIE             | 1000000000000000000000 |

Run this command to delegate:

```
qied tx staking delegate <validator_operator_address> 1000000000000000000000aqie \
  --from <wallet_name> \
  --chain-id qie_1990-1 \
  --gas auto \
  --gas-adjustment 1.5 \
  --gas-prices 10000000000aqie \
  --home "$HOME/.qieMainnetNode" \
  --node "tcp://127.0.0.1:26657"

```

* Replace `<validator_operator_address>` with the validator's address.
* Replace `<amount>` with the amount of QIE you want to delegate (e.g., `100`).
* Replace `<wallet_name>` with your wallet's name.

🔍 Step 6: Confirm Your Delegation

To verify that your delegation was successful, open the following URL in your browser:

```
https://validators.qie.digital/cosmos/staking/v1beta1/delegations/<your_wallet_address>
```

Replace `<your_wallet_address>` with the address from **Step 4**.

If the response includes your validator and delegation amount, congratulations — you’ve successfully delegated QIE coins and started earning rewards!

### ✅ You're Done!

You're now officially staking and helping to secure the QIE network. 🎉\
Don’t forget to monitor your rewards and keep your keys safe.


# 🔁 Manage Your Delegation

## 🌟 How to Check, Claim, and Unstake (Undelegate) Your QIE Delegation and Rewards

If you’ve staked (delegated) your QIE coins, you can earn rewards over time. This guide will walk you through how to:

* ✅ Check if you have any staking rewards
* 💰 Claim those rewards to your wallet
* 🔓 How to Unstake (Undelegate) Your QIE Coins

Each section below explains what to do, step by step, in a simple and beginner-friendly way — no technical knowledge required.

## ✅ Check if you have any staking rewards:

Before claiming, let’s first check if you have any rewards.

1. Open the link below in your browser:

   ```
   https://validators.qie.digital/cosmos/distribution/v1beta1/delegators/<your_wallet_address>/rewards

   ```

* Replace `<your_wallet_address>` with your actual wallet address that you used for delegation.
* If you see any reward amounts listed — great! That means you can claim them.

## 💰 Claim those rewards to your wallet

Now, to actually claim your rewards, you’ll need to run a command.

> 💡 This step requires using the terminal/command line and having your QIE wallet set up.

Replace the placeholders in the command below with your actual details:

```
qied tx distribution withdraw-rewards <validator_address> \
--from <your_wallet_address> \
--chain-id qie_1990-1 \
--gas auto \
--gas-adjustment 1.5 \
--gas-prices 10000000000aqie \
--node "tcp://127.0.0.1:26657" \
--yes

```

* `<validator_address>`: The validator you delegated to.
* `<your_wallet_address>`: The same wallet you used when you staked your coins.

#### 🔍 Confirm That It Worked

You can check if the rewards were claimed successfully:

**Option 1** – Go back to the same link from Step 1 and refresh the page. If your rewards now show as zero, they’ve been claimed.

**Option 2** – Open your wallet and check the balance. You should see the claimed rewards added to your wallet.

## 🔓 How to Unstake (Undelegate) Your QIE Coins

If you want to stop staking your QIE coins, follow these simple steps to undelegate them.

**🧭 Step 1: Run the Unstake (Undelegate) Command**

Open your terminal and run the following command:

```
qied tx staking unbond qievaloper1r4deped62qxzja78892qqxcm7rwkav7jn64qx9 100000000000000000000aqie \
--from <your_wallet_name> \
--chain-id qie_1990-1 \
--gas auto \
--gas-adjustment 1.5 \
--gas-prices 10000000000aqie \
--node "tcp://127.0.0.1:26657" \
--yes

```

```
🔁 Replace the amount (100000000000000000000aqie) if you want to unstake a different amount.
🔁 Make sure your_wallet_name is your actual wallet name (as configured in your local CLI).
```

**🔄 Step 3: Confirm the Delegated Amount Has Decreased**

After confirming the transaction, go back to **Step 1** above (where you check your rewards or delegation info).

* Check if your **delegated amount has gone down**.
* If yes, this means the **unstake (undelegation) request was successful**.

**⏳ Step 4: Wait for the Unbonding Period (12-14 days)**

Even though your coins are undelegated, they **will not be available immediately**.

* There is an **unbonding period** (a waiting time) before the coins return to your wallet.
* Just wait — once the time is over, the coins will appear back in your wallet automatically.


# 🛡️ Risks for Delegators

### ⚠️ Risks for Delegators

While delegating QIE coins is generally safe and rewarding, it’s important to be aware of potential risks involved. Understanding these risks helps you make informed decisions and protect your assets.

***

#### 1. **Slashing Risk**

* Validators can get **slashed** (penalized) if they misbehave or fail to perform properly, such as:
  * **Downtime:** Being offline or missing block validations
  * **Double-signing:** Signing conflicting blocks (considered malicious)
* When a validator is slashed, a **portion of their stake — including delegators’ stakes — is lost** as a penalty.

> 🔔 **Mitigation:**\
> Choose reputable validators with strong uptime and good performance records to minimize slashing risk.

***

#### 2. **Validator Misconduct or Mismanagement**

* Validators control the node infrastructure and are responsible for signing blocks and maintaining uptime.
* Poorly managed validators may:
  * Fail to earn rewards efficiently
  * Get jailed due to downtime
  * Cause delays in your rewards distribution

> 🔔 **Mitigation:**\
> Research validators before delegating — check their commission, uptime, community reputation, and performance history.

***

#### 3. **Unbonding Period**

* When you decide to undelegate (unbond) your coins, there is a **waiting period before you can access them** again (usually several days).
* During this unbonding period:
  * Your coins are still at risk if the validator gets slashed
  * You cannot use or transfer your coins

> 🔔 **Mitigation:**\
> Plan your unbonding carefully and be aware of the lock-up period to avoid surprises.

***

#### 4. **No Absolute Guarantee of Rewards**

* Rewards depend on network conditions, validator performance, and overall staking participation.
* Changes in inflation rates, halving events, or network activity can affect the amount of rewards you earn.

***

#### 5. **External Risks**

* Risks such as wallet security breaches, phishing attacks, or loss of private keys are always a concern when managing crypto assets.

> 🔔 **Mitigation:**\
> Use secure wallets, enable two-factor authentication, and follow best security practices.

***

### 📝 Summary

Delegating QIE coins is a powerful way to earn rewards and support the network, but it’s not without risks. Always:

* **Choose validators carefully**
* **Understand the unbonding period**
* **Keep your wallet secure**

Being informed helps you stake confidently and safely.


# 🤝 Tips for New Delegators

### 💡 Tips for New Delegators

Starting as a delegator can feel overwhelming, but following these tips will help you delegate smartly and safely:

***

#### 🧠 Start Small

* Begin by staking a small amount of QIE coins
* Test the delegation process and get comfortable before committing larger funds

***

#### 📊 Monitor Validator Performance

* Use blockchain explorers to **track your validator’s uptime, rewards, and overall reliability**
* Regular monitoring helps you avoid poor-performing or risky validators

***

#### 🗳️ Support Active Validators

* Choose validators who **actively participate in on-chain governance** and community decisions
* This ensures your stake supports validators committed to the network’s success

***

#### 🚨 Set Alerts for Validator Status

* Stay informed by setting up notifications for **validator slashing, downtime, or jailing events**
* Early alerts allow you to take action, like redelegating your stake if necessary

***

#### 🧭 Rebalance Periodically

* Review your delegation regularly
* If a validator’s performance drops, or if you want to optimize rewards, **redelegate your coins to a better validator**

***

By following these simple tips, you’ll protect your stake and maximize your rewards while contributing to a strong and secure QIE network.


# 📦 QIE V3 Tokenomics

#### Sustainable Rewards. Predictable Supply.

QIE V3 is designed with a long-term, deflation-aware coin model that balances validator incentives with sustainable emissions. Unlike inflation-heavy chains, QIE V3 has a fixed supply and a daily emission structure that gradually reduces over time.

<br>


# 💰 Total Supply

### 🔐 Tokenomics & Supply Design

QIE is built with a transparent and fair supply model, designed for long-term sustainability and community trust.

#### 💎 Fixed Maximum Supply

* **Total Max Supply**: `150,000,565 QIE`\
  *(One hundred fifty million, five hundred sixty-five QIE)*

There will never be more than this amount. The supply is hard-capped — meaning **no additional QIE coins will ever be minted**.

***

#### 🏁 No ICO — Fair Distribution

* ❌ **No ICO or Private Sale**: QIE did **not** conduct an initial coin offering (ICO), token pre-sale, or private funding rounds
* ✅ **Fair Mining**: All coins in circulation were **fairly mined** during the early stages of the network
* 👥 **Community First**: This ensures no early investors received preferential pricing or allocations

> The supply model is built on **fairness and transparency**, giving every participant an equal opportunity from day one.

***

#### 🎁 Rewards Allocation

* **Total Rewards for Validators and Delegators**: `66,000,000 QIE`\
  *(Sixty-six million QIE)*
  * Distributed over a span of over next 100 years
  * Rewards are drawn **only from this fixed allocation**

***

#### 🚫 No Unlimited Minting or Inflation

* There is **no mechanism for unlimited minting**
* **No artificial inflation**
* All rewards come **exclusively from the fixed cap**

***

#### 🔥 Deflationary by Design

As network usage grows and more transactions are processed:

* A portion of transaction fees is **burned**
* This creates **deflationary pressure** over time
* The result: **reduced supply**, increased scarcity, and long-term value sustainability

***


# 📤 Emission Schedule

### 📈 QIE Coin Emission Model

#### 🔄 Daily Emission Rate

* **QIE coins enter circulation at a rate of 1,808 QIE per day**
* This equals approximately **660,000 QIE per year**
* This initial emission rate continues for the **first 2 years**

These daily rewards are distributed to **validators and delegators** as part of the network’s staking and block production incentives.

***

#### 🎯 Fixed Reward Cap

* Rewards are distributed from a **fixed allocation of 66,000,000 QIE**
* Emissions will **stop completely** once this cap is fully distributed
* No new QIE coins will be minted beyond this cap

This ensures a **predictable and limited reward structure**, supporting long-term sustainability.

***

#### 🪙 Emission Halving Model

The QIE network may adopt a **halving model**, meaning the reward emission rate can be reduced (halved) over time.

**Key Points:**

* Halvings are **automatic happen in 2 years.**

***

#### 🔒 Why This Matters

* Helps prevent **rapid coin dilution**
* Encourages **responsible tokenomics** and **community participation**
* Balances network security, validator incentives, and long-term scarcity


# 🧮 Daily Reward Model

### 🎁 QIE Rewards Distribution

#### ⏱️ Daily Reward Cycle

* Rewards are calculated and distributed every 24 hours
* To claim the reward, you must participate for 24 hours.
* This cycle ensures that **validators and delegators receive rewards consistently and without delay**

***

#### 💸 Sources of Rewards

The daily rewards come from **two main sources**:

1. **Block Rewards**
   * Issued from the fixed **emission pool (66 million QIE)**
   * These are rewards for validating and producing new blocks on the QIE blockchain
2. **Transaction Fees**
   * Collected from user transactions on the network
   * These are split between validators and a burn mechanism

***

#### 🔁 Automatic Daily Refresh

* The reward system **refreshes automatically every 24 hours**
* No manual claiming is required by validators; rewards accumulate and are distributed as part of the protocol

***

#### 🔒 Why This Matters

* Encourages consistent validator participation
* Creates **deflationary pressure** as transaction volume increases
* Aligns long-term incentives for both validators and coin holders

***


# 🔥 Deflation Mechanism

### 🔥 Deflationary Mechanism of QIE

#### 📉 QIE Becomes Deflationary Over Time

QIE is designed with a built-in deflationary model, meaning the total circulating supply **gradually decreases** over time. Unlike inflationary tokens that continuously increase in supply and lose value, QIE becomes scarcer as adoption grows.

***

#### 🔒 Fixed Supply, No Minting

* **Maximum Supply**: Capped at **150,000,565 QIE**
* **No Minting After Cap**: No new QIE can be minted once this cap is reached
* **Reward Reserve**: 66 million QIE are reserved for validator and delegator rewards over a span of over next **100 years**

> This ensures a **predictable and finite total supply**, removing inflation risk.

***

#### 🔥 Burn Mechanism

QIE uses a **fee burn mechanism**, designed to automatically reduce supply based on network usage.

**How It Works:**

* Every transaction includes a **Base Fee** (mandatory), which:
  * Is dynamically adjusted based on **network congestion**
  * Is **permanently burned** (removed from circulation)<br>

**🔢 Burn Fee Formula**

Burned Fee=Base Fee×Gas Used

* **Base Fee**: Automatically adjusted per block
* **Gas Used**: Gas consumed by the transaction
* **Burned Fee**: QIE removed from the total supply forever

**Example**:\
If the base fee is `0.0005 QIE` and the transaction uses `21,000 gas`:

Burned Fee=0.0005×21,000=10.5 QIE

> This 10.5 QIE is permanently burned, contributing to supply reduction.

***

#### 🔁 Daily Emission with Built-In Burn

Each day, QIE manages rewards and burns through the following process:

* Validator/delegator rewards are distributed from the **emission pool**
* **Base fees from all transactions are burned**
* The **net effect**: supply grows more slowly, while burn increases with network activity

***

#### 🧮 What This Means for You

As QIE adoption increases:

* ✅ **More transactions** = more base fees burned
* ✅ **Halvings** reduce the speed of new coin emissions
* ✅ **Total supply** shrinks while demand grows

> The result is a long-term deflationary model designed to support **scarcity and value appreciation**.


# 🧩 Developer Docs

Welcome to the official developer documentation for QIE , an **EVM-compatible blockchain** built for speed, scalability, and seamless Ethereum tooling support.

### 🚀 Why QIE best for developers?

* **EVM-Compatible:** Use the same tools, languages (Solidity), and smart contracts you already know from Ethereum.
* **High Throughput:** Achieve up to **30,000 transactions per second** with sub-second finality.
* **Low Fees:** Optimize dApp performance without worrying about gas costs.
* **Secure and Scalable:** Built with a modern consensus and modular architecture designed for global adoption.


# 🧾 Smart Contract Deployment

This guide will walk you through the steps to deploy smart contracts on QIE, using familiar Ethereum-based tools like **Remix**, **Hardhat**, and **Truffle**.

Since our chain is **EVM-compatible**, deploying contracts is nearly identical to deploying on Ethereum — with the added benefits of **faster transaction finality**, **higher throughput**, and **lower gas fees**.

### 🔧 Prerequisites

Before you start, make sure you have :

* MetaMask installed and connected to QIE network
* A funded wallet (get test coins from our faucet)
* Basic knowledge of Solidity (or access to a sample contract)


# 🚀 Deploy Using Remix

1. Open Remix IDE
2. Paste or write your Solidity smart contract.
3. Compile the contract using the Solidity compiler.
4. In the **Deploy & Run Transactions** tab:
   * Set **Environment** to `Injected Web3`
   * Connect to MetaMask (ensure you are on QIE network)
   * Click **Deploy**

Once deployed, the contract address will be visible in Remix.


# 🧪 Deploy Using Hardhat

1. **Install Hardhat** (if not already installed):

```
npm install --save-dev hardhat
```

2. **Create a Hardhat project**:

```
npx hardhat init
```

3. **Add your network configuration** in `hardhat.config.js`:

```
module.exports = {
  solidity: "0.8.20",
  networks: {
    yourChain: {
      url: "https://rpc1mainnet.qie.digital/",
      accounts: ["YOUR_PRIVATE_KEY"]
    }
  }
};

```

4. **Write your contract** in `contracts/` and deploy script in `scripts/deploy.js`:

```
const hre = require("hardhat");

async function main() {
  const Contract = await hre.ethers.getContractFactory("MyContract");
  const contract = await Contract.deploy();
  await contract.deployed();
  console.log("Deployed to:", contract.address);
}

main();

```

5. **Run deployment**:<br>

   ```
   npx hardhat run scripts/deploy.js --network yourChain
   ```


# 🛠 Using Truffle (Optional)

Truffle is also supported. Configure the network in `truffle-config.js`, and follow the standard deployment process. You can reuse most of your Ethereum setup.


# ✅ Post Deployment

After deployment, you can:

* Verify your contract (if using our block explorer)
* Interact via Remix, Hardhat console, or Web3.js/Ethers.js
* Use front-end frameworks like React + Web3/Ethers to build your dApp


# 📚 Core Concepts

Welcome to the foundational layer of **QIE** — an EVM-compatible blockchain. This page explains the key ideas that power our network and help you build efficient, scalable, and secure dApps that benefit from both Ethereum and Cosmos ecosystems.

***

### 🧱 1. EVM Compatibility

QIE is fully compatible with the **Ethereum Virtual Machine (EVM)**, meaning:

* You can write smart contracts in **Solidity** or **Vyper**.
* Ethereum tools like **MetaMask**, **Hardhat**, **Truffle**, and **Remix** work seamlessly.
* You can deploy contracts, use Ethereum libraries, and migrate dApps with minimal changes.

> ✅ If it works on Ethereum, it works on QIE — with cross-chain capabilities.

***

### ⚡ 2. High Throughput via Cosmos Stack

QIE leverages the **Cosmos SDK** and **Tendermint Core (CometBFT)** consensus for high performance:

* Fast block times (\~2 seconds)
* Finality on each block (no probabilistic finality)
* Designed to support high-volume dApps like DeFi, games, and on-chain identity

> Achieving thousands of TPS through modular design and parallel transaction execution.

***

### 💰 3. Low Transaction Fees

Thanks to our efficient architecture and Cosmos-based fee model:

* Fees are predictable and **much lower than Ethereum**.
* Ideal for microtransactions, NFTs, and other cost-sensitive operations.
* Developers can subsidize gas for users or use fee abstraction models.

***

### 🔄 4. Tendermint-Based Consensus

QIE uses **Tendermint Core** (BFT-based consensus), offering:

* **Fast finality** (no waiting for confirmations)
* High throughput and network stability
* **Validator-based governance** for upgrades and economic changes

> Want to become a validator or delegator? Explore our Validator Setup Guide

***

### 🧩 5. Modular Architecture

QIE offers a highly modular design:

* Add or modify modules without hard forks
* Customize features like staking, governance, and fee handling
* Future-proof architecture supporting upgrades and innovation

***

### 🔗 6. Interoperability via IBC & Bridges

QIE is **interoperable by design**, thanks to:

* **IBC (Inter-Blockchain Communication)** for direct messaging between Cosmos chains
* Bridges to Ethereum and other major ecosystems
* Support for ERC-20, ERC-721, ERC-1155 standards

> Build multi-chain dApps and access liquidity across chains.

***

### 🧠 7. Smart Contracts & Storage

On QIE, smart contracts:

* Run on the **EVM-compatible execution layer**
* Maintain state across blocks with native on-chain storage
* Can access external data via oracles and cross-chain interfaces

Smart contracts deployed on Ethereum can be migrated with minimal changes.

***

### 📊 8. Native Coin

* **Coin Symbol:** QIE
* **Utility:** Paying gas fees, staking, validator rewards, governance
* Can be transferred across Cosmos chains via IBC and bridged to EVM chains

> Designed for real utility, governance, and ecosystem incentives.

***


# 🔮QIE-Oracle


# 📖 Introduction

Welcome to the official documentation for **QIE Oracle** — a decentralized, secure, and efficient price feed system built for the **QIE Layer 1 blockchain**.

QIE Oracle bridges the gap between **off-chain data** (such as asset prices) and **on-chain smart contracts**, enabling developers to build powerful decentralized applications (dApps) that rely on **accurate, real-time market data**.

<br>


# ❓ What is QIE Oracle?

**QIE Oracle** is a decentralized data feed system designed to bring real-world asset prices onto the **QIE Layer 1 blockchain**.

Blockchains are inherently closed systems—they cannot directly access external data. Oracles solve this limitation by acting as a secure bridge between off-chain data and on-chain smart contracts.

QIE Oracle enables developers to access **secure, reliable, and tamper-resistant price feeds** for a wide range of assets. This foundational infrastructure supports powerful on-chain applications, including:

* **DeFi protocols** (e.g., lending, borrowing, synthetic assets)
* **Gaming platforms**
* **Decentralized trading**
* **Stablecoins**
* **Tokenized real-world assets (RWA)**

By leveraging QIE Oracle, developers can build applications that interact safely with real-world data—ensuring accuracy, trust, and transparency across the QIE ecosystem.


# ❓ Why Do We Need Oracles?

Smart contracts, by design, **cannot access live market data** on their own. This creates a critical limitation for many decentralized applications.

For example, a **lending protocol** built on QIE may need the **current price of BTC or ETH** to calculate collateral ratios. Without an oracle, this data is simply **not available on-chain**, making it impossible to execute accurate or safe logic.

**How QIE Oracle Solves This**

QIE Oracle addresses this limitation by:

* **Fetching real-time price data** from trusted and verifiable off-chain sources.
* **Publishing price feeds on-chain** via verified Oracle contracts.
* **Providing a unified standard** for smart contracts to query asset prices with minimal integration effort.

This ensures that decentralized financial products on QIE are:

* ✅ **Accurate** — reflecting real-world asset values
* ✅ **Transparent** — data sources and update mechanisms are publicly auditable
* ✅ **Secure** — tamper-resistant infrastructure prevents manipulation, even in volatile markets

By bridging off-chain data to on-chain logic, QIE Oracle plays a critical role in enabling safe, scalable, and reliable applications across the QIE ecosystem.


# 📦 Supported Assets & Scope

QIE Oracle currently supports **seven key assets** through deployed smart contracts on the **QIE Layer 1 blockchain**.

These Oracle contracts serve as the **official price reference** for their respective assets on the QIE network.\
\
SearchAssetSymbolContract Address

Bitcoin

BTC

`0x9E596d809a20A272c788726f592c0d1629755440`

Ethereum

ETH

`0x4bb7012Fbc79fE4Ae9B664228977b442b385500d`

Ripple

XRP

`0x804582B1f8Fea73919e7c737115009f668f97528`

Solana

SOL

`0xe86999c8e6C8eeF71bebd35286bCa674E0AD7b21`

QIE Native

QIE

`0x3Bc617cF3A4Bb77003e4c556B87b13D556903D17`

Tether Gold

XAUt

`0x9aD0199a67588ee293187d26bA1BE61cb07A214c`

Binance Coin

BNB

`0x775A56117Fdb8b31877E75Ceeb68C96765b031e6`

**🔹 Developer Access**

Developers can **directly call these contracts** to retrieve **live, on-chain price data** for supported assets—enabling real-time interaction in DeFi protocols, trading platforms, and more.

#### 🚀 Future Scope <a href="#future-scope" id="future-scope"></a>

QIE Oracle is continuously evolving to support a wider range of data sources and assets. Upcoming enhancements include:

* **More cryptocurrencies** → *LTC, DOT, MATIC, and others*
* **Real-world assets** → *Stocks, commodities (e.g., gold, oil), and FX pairs*
* **Cross-chain data integration** → *Support for fetching and verifying data across multiple blockchain networks*

These planned upgrades will expand the capabilities of the QIE ecosystem, making it a robust platform for building advanced, data-driven decentralized applications.


# ⚙️ How QIE Oracle Works

QIE Oracle is designed to deliver **accurate and reliable price data** from the real world onto the QIE blockchain. This section explains how the Oracle works internally — from **fetching off-chain data** to making it accessible for smart contracts.


# 📡 Data Sourcing (Off-Chain Price Feeds → On-Chain)

The first step in the QIE Oracle system is **data collection from external sources**. To ensure accuracy and reliability, QIE Oracle sources price data from **trusted and reputable providers**, including:

* **Cryptocurrency exchanges** → *e.g., Binance, Coinbase, Kraken*
* **Financial market data providers** → *e.g., XAUt (Tether Gold) and other real-world asset feeds*

***

**🔄 Data Flow Overview**

The Oracle follows a standardized process to collect, process, and publish asset prices:

1. **Fetch price data** A backend service regularly queries external APIs to retrieve the latest price information.
2. **Transform data** The raw data is normalized to match the required precision and format used by the blockchain (e.g., converting float values to fixed-point integers).
3. **Submit to Oracle contract** The processed data is submitted to QIE Oracle smart contracts via **signed transactions**, ensuring authenticity and data integrity.

***

**✅ Key Benefits**

* **Structured** — Data is consistently formatted for easy consumption by smart contracts
* **Accurate** — Pulled from trusted, high-liquidity sources
* **Tamper-proof** — Signed and verified before being published on-chain

This system ensures that all on-chain price feeds are reliable, secure, and compatible with QIE-based applications.


# 🧮 Aggregation and Validation

To ensure **reliability**, **accuracy**, and **resistance to manipulation**, QIE Oracle implements a robust **data aggregation mechanism**.

**🔗 Aggregation Process**

1. **Multi-source data collection** Price data is fetched simultaneously from multiple trusted sources.
2. **Aggregation logic** A **median** or **weighted average** is calculated to determine the final price value.
3. **Outlier detection & filtering** Anomalous or outlier values are automatically identified and excluded from the final calculation.

***

**✅ Why This Matters**

This aggregation mechanism ensures that:

* A single faulty or malicious data source **cannot compromise** the overall system.
* The Oracle publishes a **consensus-based price** that accurately reflects real market conditions.
* The resulting data is **more stable**, **trustworthy**, and **manipulation-resistant**, especially during high volatility.

<br>


# 📦 Smart Contract Integration

This section explains how developers can integrate the `AggregatorV3` oracle contract into their own decentralized applications (dApps) to access off-chain or externally-fed data within smart contracts.

Your dApp can consume reliable, on-chain data using our `AggregatorV3` oracle, which is compatible with the standard Chainlink AggregatorV3 interface — making integration simple and familiar for many Web3 developers.

***

#### 🔗 Integration Overview <a href="#integration-overview" id="integration-overview"></a>

To use the oracle in your dApp:

1. **Import the AggregatorV3Interface**
2. **Set the oracle contract address**
3. **Call the oracle’s functions (`latestRoundData`, `getRoundData`, etc.)**
4. **Handle data appropriately in your business logic**

***

#### 🛠️ Step-by-Step Guide <a href="#step-by-step-guide" id="step-by-step-guide"></a>

**1. Import the AggregatorV3Interface**

If you're using Solidity:

<a class="button secondary">Copy</a>

```
import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";
```

Note: This works because our oracle implements the same interface as Chainlink, so it's fully compatible.

***

**2. Declare the Oracle Interface**

Declare a reference to the oracle in your consuming contract:

<a class="button secondary">Copy</a>

```
AggregatorV3Interface public priceFeed;
```

You’ll initialize this reference in the constructor or a setup function.

***

**3. Initialize with the Oracle Address**

<a class="button secondary">Copy</a>

```
constructor(address _oracleAddress) {
    priceFeed = AggregatorV3Interface(_oracleAddress);
}
```

> Replace `_oracleAddress` with the actual deployed address of the `AggregatorV3` oracle contract.

***

**4. Read the Latest Data**

To get the most recent answer:

<a class="button secondary">Copy</a>

```
function getLatestAnswer() public view returns (int256) {
    (
        , 
        int256 answer,
        , 
        , 
    ) = priceFeed.latestRoundData();
    return answer;
}
```

You can also access timestamps and round information if needed:

<a class="button secondary">Copy</a>

```
function getLatestData() public view returns (
    uint80 roundId,
    int256 answer,
    uint256 startedAt,
    uint256 updatedAt,
    uint80 answeredInRound
) {
    return priceFeed.latestRoundData();
}
```

***

**5. Read Specific Round Data (Optional)**

If your use case requires historical data, you can retrieve data from a specific round:

<a class="button secondary">Copy</a>

```
function getHistoricalAnswer(uint80 roundId) public view returns (int256) {
    (
        , 
        int256 answer,
        , 
        , 
    ) = priceFeed.getRoundData(roundId);
    return answer;
}
```

> ⚠️ Ensure the round exists — otherwise, the call will revert.

***

#### 🧠 Use Cases <a href="#use-cases" id="use-cases"></a>

Here are a few example use cases where your dApp might benefit from this oracle:

* **Price Feeds:** Display the current price of a token or asset.
* **Stablecoin Collateralization:** Check price before minting/burning.
* **Betting & Prediction Markets:** Resolve outcomes based on real-world values.
* **Rebasing Tokens:** Use oracle data for supply adjustments.

***

#### ⚠️ Best Practices <a href="#best-practices" id="best-practices"></a>

* **Validate Oracle Output:** Ensure the returned data is not stale or zero.
* **Handle Errors:** If no data is available, `latestRoundData()` will revert. Use `try/catch` in higher-level frameworks or check availability on-chain.
* **Secure the Oracle Address:** Set the oracle address only once or via a governance mechanism to avoid manipulation.

***

#### 🧪 Testing Integration <a href="#testing-integration" id="testing-integration"></a>

When testing locally or in staging:

* You can deploy a mock oracle using the same interface (`AggregatorV3Interface`) and manually update values using the `updateAnswer(int256)` function.
* This is useful for simulating real-world scenarios and testing dApp logic against different oracle values.

<a class="button secondary">Copy</a>

```
// Call this in your tests from the oracle owner's account
mockOracle.updateAnswer(12345); // sets new answer
```

#### ✅ Summary <a href="#summary" id="summary"></a>

By following the standard `AggregatorV3Interface`, our oracle contract allows seamless integration into any dApp that supports Chainlink-style data feeds.

Integration steps are straightforward:

1. Import the interface
2. Set the oracle address
3. Call `latestRoundData()` or `getRoundData()`
4. Use the result in your business logic

With this, your smart contracts can interact with externally-fed data reliably and efficiently.


# 🔒 Security Measures

#### 🔐 Oracle Security <a href="#oracle-security" id="oracle-security"></a>

Security is a critical component of any oracle system, as it acts as the bridge between off-chain data and on-chain smart contracts. The **QIE Oracle** is designed with multiple layers of protection to ensure the accuracy, integrity, and reliability of the data it delivers.

***

**✅ Security Features**

**🔏 Signed Transactions**

Only **authorized nodes** are permitted to update the QIE Oracle contracts. All updates are executed via **signed transactions**, ensuring that only trusted entities can push data on-chain.

**🔁 Redundant Data Sources**

QIE Oracle aggregates data from **multiple independent exchanges**. This redundancy helps:

* Prevent manipulation from a single source
* Increase data reliability
* Smooth out anomalies from low-liquidity markets

**⏱️ Timely Updates**

Price feeds are refreshed at **regular intervals**, ensuring that on-chain consumers always access **up-to-date information**. This reduces the risk of using stale data in critical financial applications.

**🧠 On-Chain Sanity Checks**

Smart contracts integrating with QIE Oracle can implement **custom validation logic**, such as:

* Maximum deviation thresholds from the last known price
* Time-based freshness checks
* Reversion on abnormal spikes or gaps

These **on-chain safeguards** allow dApps to reject suspicious or potentially manipulated updates proactively.

***

**🛡️ Why This Matters**

With these security mechanisms in place, QIE Oracle offers:

* **Robust protection** against malicious actors
* **High availability** and **accuracy** of external data
* **Trustworthy integration** for financial, DeFi, and data-driven smart contracts

***

QIE Oracle is built with security and resilience in mind — ensuring developers can confidently rely on it for mission-critical on-chain applications.


# 📄 Deployed Contracts

QIE Oracle publishes **live price data on-chain** via dedicated smart contracts for each supported asset. These contracts serve as the **official reference points** for dApps, DeFi protocols, and other smart contracts across the QIE blockchain.


# 📊 Table of Assets → Contract Mapping

AssetSymbolOracle Contract Address

Bitcoin

BTC

`0x9E596d809a20A272c788726f592c0d1629755440`

Ethereum

ETH

`0x4bb7012Fbc79fE4Ae9B664228977b442b385500d`

Ripple

XRP

`0x804582B1f8Fea73919e7c737115009f668f97528`

Solana

SOL

`0xe86999c8e6C8eeF71bebd35286bCa674E0AD7b21`

QIE Native

QIE

`0x3Bc617cF3A4Bb77003e4c556B87b13D556903D17`

Tether Gold

XAUt

`0x9aD0199a67588ee293187d26bA1BE61cb07A214c`

Binance Coin

BNB

`0x775A56117Fdb8b31877E75Ceeb68C96765b031e6`

> ⚡ Note: These are the **official Oracle contracts** on QIE Layer 1. Always reference these addresses when fetching price data in your smart contracts.


# 📥 Query Examples

This section provides practical examples of how to query the **QIE Oracle** from both JavaScript (frontend/backend using `ethers.js`) and Solidity (on-chain smart contracts). These examples help developers easily integrate the oracle into dApps and smart contracts.

***

**🟨 Solidity Example**

Use this example to read the latest price from the oracle **inside a smart contract**.

<a class="button secondary">Copy</a>

```
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";

contract PriceConsumer {
    AggregatorV3Interface public priceFeed;

    constructor(address oracleAddress) {
        priceFeed = AggregatorV3Interface(oracleAddress);
    }

    function getLatestPrice() public view returns (int256) {
        (
            , // roundId
            int256 price,
            , // startedAt
            , // updatedAt
            // answeredInRound
        ) = priceFeed.latestRoundData();

        return price;
    }
}
```

> Replace `oracleAddress` with the deployed address of the QIE Oracle contract on your network.

***

**🟦 JavaScript Example (ethers.js)**

Use this example in your frontend or backend to query the oracle using **ethers.js**.

<a class="button secondary">Copy</a>

```
const { ethers } = require("ethers");

const provider = new ethers.JsonRpcProvider("<rpc_url>");

//  Price Feed contract address (example: BNB/USD on QIE Mainnet)
const priceFeedAddress = "0xYourOracleAddress"; // BNB/USD (8 decimals)

// ABI fragment to read latestRoundData
const aggregatorV3InterfaceABI = [
  {
    "inputs": [],
    "name": "latestRoundData",
    "outputs": [
      { "internalType": "uint80", "name": "roundId", "type": "uint80" },
      { "internalType": "int256", "name": "answer", "type": "int256" },
      { "internalType": "uint256", "name": "startedAt", "type": "uint256" },
      { "internalType": "uint256", "name": "updatedAt", "type": "uint256" },
      { "internalType": "uint80", "name": "answeredInRound", "type": "uint80" }
    ],
    "stateMutability": "view",
    "type": "function"
  }
];

async function getPrice() {
  const priceFeed = new ethers.Contract(priceFeedAddress, aggregatorV3InterfaceABI, provider);
  
  const roundData = await priceFeed.latestRoundData();
  const price = roundData.answer;

  // Normalize 8 decimals
  const normalizedPrice = Number(price) / 1e8;

  console.log(`BNB/USD Price: $${normalizedPrice}`);
}

getPrice().catch(console.error);
```

> ⚠️ Don’t forget to replace `0xYourOracleAddress` and `your_rpc_url` with the correct values for your deployment.

***

**📌 Additional Query: Get Historical Data**

You can also query a specific round by ID to fetch past data.

**Solidity:**

<a class="button secondary">Copy</a>

```
function getHistoricalPrice(uint80 roundId) public view returns (int256) {
    (
        , 
        int256 price,
        , 
        , 
    ) = priceFeed.getRoundData(roundId);
    return price;
}
```

JavaScript:

<a class="button secondary">Copy</a>

```
async function fetchHistoricalPrice(roundId) {
  const [ , price ] = await priceFeed.getRoundData(roundId);
  const decimals = await priceFeed.decimals();

  const normalizedPrice = Number(price) / (10 ** decimals);
  console.log(`Price at round ${roundId}: ${normalizedPrice}`);
}
```

**🧪 Tip: Mocking in Local Development**

For local testing, you can deploy your own instance of the `AggregatorV3` contract and call `updateAnswer(int256)` to simulate real-world updates.


# 🚀 Getting Started

This section will guide you through the **initial setup** needed to interact with QIE Oracle, connect to the QIE blockchain, and fetch live asset prices.

<br>


# 🚀 Prerequisites

Before you begin integrating the QIE Oracle, make sure you have the following tools and knowledge in place:

***

**👛 QIE Wallet or MetaMask**

You will need a wallet that supports **QIE Layer 1** in order to:

* Sign transactions
* Interact with Oracle contracts

✅ **MetaMask is supported** and can be configured to connect to QIE using a custom RPC.

***

**🌐 QIE RPC URL**

This is the endpoint your application uses to connect to the QIE blockchain network.

* **RPC URL:** `https://rpc5mainnet.qie.digital`

📌 Use this URL in MetaMask, Ethers.js, Hardhat, or any Web3-compatible tool to connect to the QIE mainnet.

***

**🟦 Node.js & Ethers.js (For JavaScript Developers)**

To interact with Oracle contracts programmatically via JavaScript:

1. **Install Node.js:** Download from <https://nodejs.org>

<a class="button secondary">Copy</a>

```
npm install ethers
```

This setup allows you to fetch oracle data and interact with smart contracts using JavaScript.

***

**🧠 Basic Solidity Knowledge (For Smart Contract Developers)**

To integrate the oracle in your smart contracts, you should be familiar with:

* Solidity interfaces
* External contract calls
* Reading data from oracle feeds

If you're new to this, refer to the Query Examples


# 🔗 Connecting to the QIE Blockchain

To interact with QIE Oracle contracts, your wallet or application must first connect to the **QIE Layer 1 blockchain**. Below are the steps for connecting using **MetaMask** and **JavaScript (ethers.js)**.

***

**🦊 Using MetaMask**

You can manually add the QIE network to MetaMask:

1. Open MetaMask
2. Click **"Add Network"**
3. Enter the following network details:

<a class="button secondary">Copy</a>

```
Network Name:       QIE Mainnet
RPC URL:            https://rpc5mainnet.qie.digital
Chain ID:           1990       
Currency Symbol:    QIE
Block Explorer URL: https://mainnet.qie.digital
```

1. Click **Save**, then switch your wallet to the newly added QIE Mainnet.

> ✅ Once added, you’ll be able to sign transactions and interact with the QIE Oracle contracts directly from MetaMask.

***

**📦 Using JavaScript (ethers.js)**

To connect your JavaScript or Node.js application to the QIE blockchain using `ethers.js`:

<a class="button secondary">Copy</a>

```
const { ethers } = require("ethers");

// Connect to the QIE blockchain via RPC
const provider = new ethers.JsonRpcProvider("https://rpc5mainnet.qie.digital");

console.log("Connected to QIE blockchain:", provider);
```

> ✅ You can now use the `provider` to interact with smart contracts, read oracle data, send transactions, and more.


# 📡 Reading Data from Oracle

Once connected, you can query Oracle contracts to fetch live prices.

**Example: Fetch BTC Price**

<a class="button secondary">Copy</a>

```
interface IQIEOracle {
    function getPrice(string calldata asset) external view returns (uint256);
}

contract FetchPriceExample {
    IQIEOracle oracle = IQIEOracle(0x9E596d809a20A272c788726f592c0d1629755440); // BTC Oracle

    function getBTCPrice() public view returns (uint256) {
        return oracle.getPrice("BTC"); // Returns BTC price in smallest unit
    }
}
```

**JavaScript Example (ethers.js)**

<a class="button secondary">Copy</a>

```
const { ethers } = require("ethers");
const provider = new ethers.JsonRpcProvider("https://rpc.qiechain.io");

const oracleAddress = "0x9E596d809a20A272c788726f592c0d1629755440";
const oracleAbi = ["function getPrice(string asset) view returns (uint256)"];

const oracleContract = new ethers.Contract(oracleAddress, oracleAbi, provider);

async function fetchBTCPrice() {
    const price = await oracleContract.getPrice("BTC");
    console.log("BTC Price:", price.toString());
}

fetchBTCPrice();
```

> ⚡ Tip: Replace `"BTC"` with `"ETH"`, `"XRP"`, or any supported asset symbol to fetch other prices.

This section provides the **foundation for developers** to start interacting with QIE Oracle immediately, whether through smart contracts or scripts.


# 📙 Developer Guide

This section offers **practical guidance** for developers to integrate QIE Oracle into smart contracts, fetch live asset prices, handle errors, and follow best practices for building **secure and reliable** applications.

<br>


# ⚙️ How to Integrate QIE Oracle in Smart Contracts

Integrating QIE Oracle into your smart contract is simple and gas-efficient. The oracle contracts are **read-only**, meaning fetching data does not consume significant gas.

***

**✅ Integration Steps**

**1. Import the Oracle Interface**

Use the standard `AggregatorV3Interface`, which is compatible with the QIE Oracle:

<a class="button secondary">Copy</a>

```
import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";
```

> This interface is supported because QIE Oracle follows the Chainlink AggregatorV3 standard.

***

**2. Instantiate the Oracle**

Set the oracle contract address in your constructor or initializer:

<a class="button secondary">Copy</a>

```
AggregatorV3Interface public priceFeed;

constructor(address oracleAddress) {
    priceFeed = AggregatorV3Interface(oracleAddress);
}
```

> Replace `oracleAddress` with the deployed address of the specific QIE Oracle for your asset (e.g., QIE/USD).

***

**3. Call `latestRoundData()` to Get the Price**

Fetch the latest price in your contract logic:

<a class="button secondary">Copy</a>

```
function getLatestPrice() public view returns (int256) {
    (
        , 
        int256 price,
        , 
        , 
    ) = priceFeed.latestRoundData();

    return price;
}
```

> This function is read-only (`view`) and consumes minimal gas when called externally or from another contract.

***

**⚡️ Gas Efficiency**

All price-fetching functions on the QIE Oracle are **non-state-changing** (read-only). This means:

* No transaction needs to be sent
* No gas is spent reading data (unless used inside a transaction)
* Safe to use in frequent or lightweight calls


# 🧾 Example: Fetching BTC & ETH Prices (Solidity)

Here’s a sample Solidity snippet showing how to fetch real-time prices for **BTC** and **ETH** using QIE Oracle contracts. These oracles are based on your custom implementation of `AggregatorV3`.

***

**🔍 Assumptions**

* You have deployed two oracle contracts using your custom `AggregatorV3` contract:
  * One for BTC (e.g., BTC/USD)
  * One for ETH (e.g., ETH/USD)
* Both contracts implement `AggregatorV3Interface`
* The contract addresses are known and passed during deployment

***

**🧱 Sample Solidity Code**

<a class="button secondary">Copy</a>

```
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";

contract AssetPriceConsumer {
    AggregatorV3Interface public btcOracle;
    AggregatorV3Interface public ethOracle;

    constructor(address _btcOracle, address _ethOracle) {
        btcOracle = AggregatorV3Interface(_btcOracle);
        ethOracle = AggregatorV3Interface(_ethOracle);
    }

    function getLatestBTCPrice() public view returns (int256) {
        (
            , 
            int256 price,
            , 
            , 
        ) = btcOracle.latestRoundData();
        return price;
    }

    function getLatestETHPrice() public view returns (int256) {
        (
            , 
            int256 price,
            , 
            , 
        ) = ethOracle.latestRoundData();
        return price;
    }
}
```

**🧪 Usage**

This contract allows you to:

* Fetch the latest BTC/USD and ETH/USD prices
* Use the prices in further contract logic (e.g., swaps, comparisons, liquidations)

You can call:

<a class="button secondary">Copy</a>

```
getLatestBTCPrice(); // Returns the latest BTC price (int256)
getLatestETHPrice(); // Returns the latest ETH price (int256)
```

**⚠️ Notes**

* Ensure that the oracle contracts are properly updated by the owner before use.
* The returned price is an `int256` and may include decimals (check `decimals()` from the oracle).
* If the oracle has not been updated yet, `latestRoundData()` will revert.

***

**📘 Bonus: Get Oracle Metadata**

You can also fetch metadata like description and decimals:

<a class="button secondary">Copy</a>

```
function getBTCMetadata() public view returns (string memory, uint8) {
    return (btcOracle.description(), btcOracle.decimals());
}
```


# ⚠️ Handling Edge Cases & Best Practices

While the **QIE Oracle** is designed for reliability and consistency, developers should account for potential edge cases and follow recommended best practices to ensure safe integration into smart contracts and dApps.

***

**🚫 Handling Common Edge Cases**

**🔤 Invalid Asset Symbol**

If your oracle implementation supports asset symbols (e.g., `getPrice("BTC")`), calling the function with an **unsupported or misspelled symbol** will **revert** the transaction.

> ✅ **Tip:** Always validate or whitelist symbols before calling the oracle.

***

**📉 Unexpected Price Values**

Due to market volatility or delayed updates, prices may temporarily **spike** or **crash**. Implement **on-chain sanity checks** to prevent incorrect logic execution.

<a class="button secondary">Copy</a>

```
function safeFetchBTCPrice() public view returns (uint256) {
    uint256 price = btcOracle.getPrice("BTC");
    require(price > 0, "Invalid BTC price");
    require(price < 1_000_000_000 ether, "BTC price too high");
    return price;
}
```

> ✅ Set upper and lower bounds for acceptable price ranges.

***

**🕒 Oracle Update Delays**

QIE Oracle updates prices at **regular intervals**, but **not every block**.

> ⚠️ Do not assume price data is real-time within the same block. For sensitive use cases (like flash loans or arbitrage), verify `updatedAt` timestamp from `latestRoundData()`.

***

#### ✅ Best Practices <a href="#best-practices" id="best-practices"></a>

**🪙 Use Multiple Assets**

If your dApp supports multiple tokens (e.g., DeFi lending or trading), consider fetching **multiple asset prices** to reduce reliance on a single price feed.

***

**🧠 Implement Rate Limiting / Caching**

Avoid repeatedly calling the oracle in the same transaction or within tight loops.

* **Cache prices on-chain** for a few blocks
* **Store recent price in state**, and refresh only when needed

> This helps **reduce gas costs** and improves efficiency.

***

**🧾 Validate External Data**

Always include **sanity checks** in your contract logic for:

* Price magnitude
* Max allowed percentage change
* Timestamp freshness

Example:

<a class="button secondary">Copy</a>

```
require(block.timestamp - lastUpdated < 300, "Price is outdated");
```

***

**🛡️ Do Not Overwrite Oracle Data**

Oracle contracts are maintained by the QIE system. Never attempt to manually modify oracle state or push updates.

> 🛑 Direct writes to oracle contracts are restricted to authorized updaters only.

***

**🧪 Test on Testnet First**

Before deploying to QIE Mainnet:

* Use **QIE Testnet RPC**
* Deploy your contracts
* Connect to deployed **testnet oracle contracts**
* Simulate edge cases and validate behavior

***

#### 🔚 Conclusion <a href="#conclusion" id="conclusion"></a>

By following these practices, developers can:

* Safely consume oracle data
* Protect their dApps from abnormal price behavior
* Ensure secure and efficient usage of QIE Oracle in DeFi and other use cases

> ✅ Good oracle hygiene is critical for building trustworthy, secure Web3 applications.


# 💡 Use Cases

QIE Oracle delivers **secure, reliable, and real-time price data**, empowering developers to build a diverse range of decentralized applications on the QIE blockchain. This section highlights some of the key use cases.

<br>


# 🔑 Use Cases for QIE Oracle in DeFi

The **QIE Oracle** plays a crucial role in powering decentralized finance (DeFi) applications by providing **accurate and reliable on-chain asset prices**. Here are some primary use cases where the oracle is essential:

***

**🏦 Lending & Borrowing Platforms**

* **Purpose:** Determine the value of collateral assets to calculate safe loan-to-value (LTV) ratios.
* **Example:** When a user deposits BTC as collateral, the oracle supplies the current BTC price to accurately compute borrowing limits and liquidation thresholds.

***

**🔄 Decentralized Exchanges (DEXs)**

* **Purpose:** Facilitate token swaps, liquidity provisioning, and automated market maker (AMM) price calculations using live market data.
* **Example:** Swap ETH for QIE tokens at the current exchange rate fetched from the oracle, ensuring fair and up-to-date pricing for traders.

***

**💰 Stablecoins & Synthetic Assets**

* **Purpose:** Peg tokens to real-world assets like gold-backed tokens (e.g., XAUt by Tether) or cryptocurrencies.
* **Role of Oracle:** Ensures the peg’s accuracy by providing timely and trustworthy price feeds, maintaining stable and reliable valuations.

***

QIE Oracle’s reliable pricing infrastructure empowers these DeFi building blocks, enabling secure, transparent, and efficient financial products on-chain.


# 🎮 Blockchain Gaming & Play-to-Earn (P2E) Integration

Blockchain-based games can harness **real-time asset prices** from QIE Oracle to enable dynamic, tokenized economies and rewarding gameplay experiences.

***

**💎 Key Use Cases**

* **In-Game Rewards:** Tie rewards, such as tokens or points, to the current value of cryptocurrencies, allowing players to earn assets with real-world value.
* **Tokenized Assets & NFTs:** Enable trading of in-game assets or NFTs whose prices are dynamically adjusted based on real-world market prices provided by the oracle.

***

**🎲 Example**

A play-to-earn game could award players with **QIE tokens** whose value corresponds to a fixed USD or BTC amount. The oracle feed continuously updates this value, ensuring fair and transparent rewards aligned with the market.

***

By integrating QIE Oracle price data, game developers can create immersive economies where player rewards and asset valuations reflect real-world market conditions.


# 🏷️ Tokenization of Real-World Assets with QIE Oracle

QIE Oracle empowers secure and reliable **tokenization of real-world assets**, enabling their seamless representation and trading on the blockchain.

***

**🥇 Gold & Commodities (e.g., XAUt)**

* Provides verified and tamper-resistant price feeds for tokenized gold and other commodities.
* Users can confidently **buy, sell, or trade** tokenized commodities backed by real market data.

***

**💵 Fiat-backed Tokens & Real-World Assets (RWA)**

* Facilitates tokenization of fiat currencies, bonds, and other financial instruments.
* Ensures **accurate and transparent on-chain valuations** through trusted oracle price feeds.

***

By integrating QIE Oracle, projects can bridge traditional assets and blockchain ecosystems with integrity and precision.


# 🔗 Combining Multiple Use Cases in One Application

Developers can build powerful, multi-functional dApps by integrating several QIE Oracle-powered features into a single platform.

***

**🎯 Example**

Imagine a DeFi platform where users can:

* **Stake tokenized gold (XAUt)** in lending pools
* **Trade synthetic assets** backed by real-world prices
* **Participate in blockchain gaming rewards**

All these features rely on **QIE Oracle’s reliable price feeds** to ensure accurate and up-to-date asset data.

***

#### 📋 Summary <a href="#summary" id="summary"></a>

**QIE Oracle** serves as the backbone for all applications that require **accurate, real-time asset prices**. Whether it’s DeFi, gaming, or tokenization, QIE Oracle guarantees data integrity, enabling developers to create **robust, secure, and reliable** applications on **QIE Layer 1**.


# 🔒 Security & Reliability

QIE Oracle guarantees the **accuracy, integrity, and trustworthiness** of on-chain price data through multiple robust mechanisms.

<br>


# 🔄 Data Aggregation and Reliability

QIE Oracle aggregates price data from **multiple trusted sources** for each supported asset.

* Outliers and anomalous values are automatically detected and **filtered out**.
* This **redundancy** minimizes the risk of incorrect or manipulated data from any single source affecting on-chain price feeds.

By combining data streams, QIE Oracle ensures **robustness and accuracy** for all consumers of its price feeds.


# 🔐 Security and Data Integrity

* Only **authorized nodes** are permitted to submit updates to the Oracle contracts.
* Each update is **cryptographically signed** to guarantee authenticity and prevent tampering.
* Smart contracts consuming oracle data can implement **sanity checks**, such as limiting the maximum allowed price deviation per update, to reject suspicious or erroneous values.

These measures together ensure the **security, reliability, and trustworthiness** of QIE Oracle price feeds.


# ⏱️ Timely Updates and Transparency

* Prices are updated at **regular intervals** to maintain data freshness.
* Every update is **recorded on-chain** and is publicly verifiable by anyone.
* This transparency allows developers and users to **audit all Oracle updates**, fostering trust in the data feed.

**✅ Summary**

By combining **redundant data sources**, **strict access controls**, and **transparent update mechanisms**, QIE Oracle delivers a **robust, secure, and reliable** price feed for all on-chain applications.


# ❓ FAQs

This section addresses the most common questions about QIE Oracle, helping developers and users gain a clearer understanding of its functionality.

<br>


# ⏳ How Often Does QIE Oracle Update Prices?

QIE Oracle updates asset prices at **regular, configurable intervals**, tailored to the nature of each asset:

* **Cryptocurrencies** (e.g., BTC, ETH, BNB) are updated **every few minutes** to accurately reflect rapid market changes.
* **Real-world assets** (e.g., XAUt – Tether Gold) are updated **every few minutes** or according to the schedule of trusted external data providers.

***

**🔍 Ensuring Freshness**

Developers can always verify the **timestamp** of the latest price by querying the Oracle contract’s data. This helps confirm the price feed is **up-to-date** before relying on it in smart contract logic.


# ❓ Can Developers Request New Assets?

Yes, developers can request support for additional assets on QIE Oracle.

**How It Works:**

* Requests are **reviewed** based on data source reliability, user demand, and technical feasibility.
* Once approved, a new Oracle contract for the requested asset will be **deployed**, providing secure and reliable on-chain price feeds.

***

**🔜 Currently Supported Assets**

QIE Oracle currently supports:

* BTC, ETH, XRP, SOL, QIE, XAUt (Tether Gold), and BNB

More assets are planned and will be added according to the project roadmap.

<br>


# ⛽ What’s the Gas Cost for Fetching Data?

* Fetching prices from QIE Oracle contracts is **read-only** and uses Solidity’s `view` functions.
* When called externally (e.g., via `eth_call`), **no gas** is consumed to read data on-chain.
* Gas is only required if the price data is used inside a **state-changing transaction** (for example, a function that modifies contract storage).

**💡 Tips for Gas Optimization**

* Use **caching** strategies to minimize repeated oracle calls within the same transaction or block.
* Implement **sanity checks** off-chain or in smart contracts to avoid unnecessary state updates triggered by anomalous data.

**✅ Summary**

QIE Oracle provides frequent, secure, and **cost-efficient access** to real-time asset prices. Developers can request new assets and trust transparent, auditable updates to power DeFi, gaming, and tokenized asset applications on QIE Layer 1.


# 👛 QIE Wallet Integration Guide for Websites

Connect your website or dApp to QIE Wallet using the standard EIP-1193 injected provider.

### Overview

QIE Wallet integrates with any website through the standard injected provider interface. The browser extension injects an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compatible provider into every page. Your site talks to this provider directly, or through a library such as ethers.js, viem, or wagmi.

Any dApp that already supports injected EVM wallets works with QIE Wallet with little or no change. This guide covers the full flow: detecting the wallet, connecting accounts, switching to the QIE network, and performing transactions and contract calls.

> **Scope:** EVM integration only (QIE Blockchain and other EVM networks). Bitcoin and Solana accounts in QIE Wallet are not exposed through the EIP-1193 provider and are out of scope here.

### Prerequisites

* QIE Wallet extension installed from the Chrome Web Store, with at least one wallet created or imported
* A website served over HTTPS (or `localhost` for development). Extensions do not inject providers into pages opened from `file://`
* ethers.js v6 for the code samples: `npm install ethers`
* Basic familiarity with async JavaScript and EVM concepts (accounts, chain IDs, gas)

No API keys or app registration are needed. The same code also works with other injected EVM wallets, which keeps your dApp wallet-agnostic.

### Network Parameters

#### Mainnet

| Parameter       | Value                                                                       |
| --------------- | --------------------------------------------------------------------------- |
| Network name    | QIE Blockchain Mainnet                                                      |
| Chain ID        | `1990` (hex: `0x7C6`)                                                       |
| RPC URL         | `https://rpc1mainnet.qie.digital` through `https://rpc5mainnet.qie.digital` |
| Currency symbol | QIE                                                                         |
| Decimals        | 18                                                                          |
| Block explorer  | <https://mainnet.qie.digital>                                               |

> **Caution:** Older aggregator listings still show the pre-V3 chain ID `5656` or the legacy chain ID `9731`. Do not use those. V3 (chain ID `1990`) is current.

#### Testnet

| Parameter       | Value                             |
| --------------- | --------------------------------- |
| Network name    | QIE Testnet                       |
| Chain ID        | `1983` (hex: `0x7BF`)             |
| RPC URL         | `https://rpc1testnet.qie.digital` |
| Currency symbol | QIE                               |
| Decimals        | 18                                |
| Block explorer  | <https://testnet.qie.digital>     |
| Faucet          | <https://www.qie.digital/faucet>  |

> **Testnet prerequisite:** QIE Testnet is hidden until the user enables the testnet toggle in QIE Wallet settings. Before that, `wallet_switchEthereumChain` to chain `1983` returns error `4902` even though the wallet knows the chain, and `wallet_addEthereumChain` will not help. Tell testers to switch the toggle on first.

### Step 1: Detect QIE Wallet

Use [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) (Multi Injected Provider Discovery) as the primary detection method. It finds QIE Wallet reliably even when the user has several wallet extensions installed, without fighting over `window.ethereum`.

```javascript
// Collect all announced wallet providers
const providers = [];
window.addEventListener('eip6963:announceProvider', (event) => {
  providers.push(event.detail); // { info: { uuid, name, icon, rdns }, provider }
});

// Ask installed wallets to announce themselves
window.dispatchEvent(new Event('eip6963:requestProvider'));

// Pick QIE Wallet from the announced providers
function getQIEProvider() {
  const match = providers.find((p) => p.info.rdns === 'me.qiewallet');
  return match ? match.provider : null;
}
```

Fallback for older setups:

```javascript
function getInjectedProvider() {
  // Preferred: EIP-6963 result
  const qie = getQIEProvider();
  if (qie) return qie;

  // Fallback: injected globals (window.qie is QIE Wallet's own)
  if (typeof window.qie !== 'undefined') return window.qie;
  if (typeof window.ethereum !== 'undefined') return window.ethereum;

  return null; // No wallet installed
}
```

If no provider is found, show an install prompt linking to the Chrome Web Store listing instead of failing silently.

**How QIE Wallet identifies itself**

* EIP-6963: `rdns: me.qiewallet`, `name: QIE Wallet`
* `window.qie`: always set, QIE Wallet only
* `window.ethereum`: claimed only if no other wallet already holds it. If MetaMask or another wallet injected first, it may point elsewhere

Prefer EIP-6963 or `window.qie` for unambiguous detection.

> **Warning:** The provider also reports `isMetaMask = true` for compatibility with dApps that only check for MetaMask. Any MetaMask-specific branch in your code will therefore run against QIE Wallet. To tell the wallets apart, use the EIP-6963 `rdns` value or `window.qie`, not `isMetaMask`.

### Step 2: Connect the User's Wallet

Request account access only in response to a user action, such as a **Connect Wallet** button. Unsolicited connection popups are treated as hostile by browsers and users.

```javascript
async function connectWallet() {
  const provider = getInjectedProvider();
  if (!provider) {
    alert('QIE Wallet is not installed.');
    return null;
  }

  try {
    // Opens the QIE Wallet popup asking the user to approve
    const accounts = await provider.request({ method: 'eth_requestAccounts' });
    return accounts[0]; // The active address
  } catch (error) {
    if (error.code === 4001) {
      console.log('Connection request was rejected');
    }
    return null;
  }
}
```

To check for an existing connection on page load **without** a popup, use `eth_accounts`. It returns connected addresses silently, or an empty array if the site is not connected.

```javascript
const accounts = await provider.request({ method: 'eth_accounts' });
const isConnected = accounts.length > 0;
```

### Step 3: Ensure the QIE Network Is Selected

After connecting, check the active chain and switch if needed. If the chain is unknown to the wallet (error `4902`), add it first.

```javascript
const QIE_CHAIN_ID = '0x7c6'; // 1990 (lowercase, matching what the wallet returns)
const QIE_CHAIN_ID_DECIMAL = 1990;

const QIE_NETWORK_PARAMS = {
  chainId: QIE_CHAIN_ID,
  chainName: 'QIE Blockchain Mainnet',
  nativeCurrency: { name: 'QIE', symbol: 'QIE', decimals: 18 },
  rpcUrls: [
    'https://rpc1mainnet.qie.digital',
    'https://rpc5mainnet.qie.digital',
  ],
  blockExplorerUrls: ['https://mainnet.qie.digital'],
};

async function ensureQIENetwork(provider) {
  const currentChainId = await provider.request({ method: 'eth_chainId' });

  // Compare numerically: the wallet returns lowercase hex ('0x7c6'),
  // so a string comparison against '0x7C6' would never match
  if (parseInt(currentChainId, 16) === QIE_CHAIN_ID_DECIMAL) return;

  try {
    await provider.request({
      method: 'wallet_switchEthereumChain',
      params: [{ chainId: QIE_CHAIN_ID }],
    });
  } catch (error) {
    if (error.code === 4902) {
      // Chain not added to the wallet yet
      await provider.request({
        method: 'wallet_addEthereumChain',
        params: [QIE_NETWORK_PARAMS],
      });
    } else {
      throw error;
    }
  }
}
```

> **Note:** Always compare chain IDs numerically. QIE Wallet returns `eth_chainId` as lowercase `0x7c6`; a strict string check against `0x7C6` fails and triggers a needless switch prompt on every load. The `chainId` param of `wallet_switchEthereumChain` is case-insensitive, so either casing works there.
>
> QIE Wallet ships with QIE network support built in, so for most users the switch call succeeds directly. The add-chain fallback matters when your dApp is also used from other injected wallets.

For a **testnet** build, swap in chain ID `0x7bf`, the testnet RPC, and the testnet explorer in `QIE_NETWORK_PARAMS`.

### Step 4: Core Operations with ethers.js

Wrap the injected provider in an ethers `BrowserProvider`. Reads go through the provider; anything that needs a signature (transactions, message signing) goes through the signer, which triggers the QIE Wallet approval popup.

```javascript
import { BrowserProvider, formatEther, parseEther } from 'ethers';

const injected = getInjectedProvider();
const ethersProvider = new BrowserProvider(injected);
const signer = await ethersProvider.getSigner();
```

**Read the native QIE balance**

```javascript
const address = await signer.getAddress();
const balanceWei = await ethersProvider.getBalance(address);
console.log(`Balance: ${formatEther(balanceWei)} QIE`);
```

**Send a native QIE transfer**

```javascript
const tx = await signer.sendTransaction({
  to: '0xRecipientAddressHere',
  value: parseEther('1.5'), // 1.5 QIE
});
console.log('Submitted:', tx.hash);

const receipt = await tx.wait(); // Wait for confirmation
console.log('Confirmed in block', receipt.blockNumber);
```

**Sign a message** (login, ownership verification)

```javascript
const signature = await signer.signMessage(
  'Sign in to ExampleDApp at 2026-09-17T10:00Z'
);
// Verify server-side with ethers.verifyMessage(message, signature)
```

> **Warning:** Always include a nonce or timestamp in login messages so signatures cannot be replayed.

**Sign EIP-712 typed data** (`eth_signTypedData_v4`)

Used for token permits, off-chain orders, and structured login payloads.

```javascript
const domain = {
  name: 'ExampleDApp',
  version: '1',
  chainId: 1990,
  verifyingContract: '0xYourContract',
};

const types = {
  Order: [
    { name: 'maker', type: 'address' },
    { name: 'amount', type: 'uint256' },
    { name: 'expiry', type: 'uint256' },
  ],
};

const value = {
  maker: address,
  amount: parseEther('10'),
  expiry: Math.floor(Date.now() / 1000) + 3600,
};

const signature = await signer.signTypedData(domain, types, value);
// Verify server-side with ethers.verifyTypedData(domain, types, value, signature)
```

Typed data shows as readable structured fields in the approval popup, so users can review exactly what they are signing.

### Step 5: Interact with Smart Contracts

Use the contract's address and ABI. Connect read-only calls to the provider and state-changing calls to the signer.

```javascript
import { Contract } from 'ethers';

const TOKEN_ADDRESS = '0xYourTokenContract';
const TOKEN_ABI = [
  'function balanceOf(address owner) view returns (uint256)',
  'function decimals() view returns (uint8)',
  'function symbol() view returns (string)',
  'function transfer(address to, uint256 amount) returns (bool)',
];

// Read (no popup, no gas)
const readContract = new Contract(TOKEN_ADDRESS, TOKEN_ABI, ethersProvider);
const decimals = await readContract.decimals();
const balance = await readContract.balanceOf(address);

// Write (opens QIE Wallet for approval, costs gas)
const writeContract = new Contract(TOKEN_ADDRESS, TOKEN_ABI, signer);
const tx = await writeContract.transfer('0xRecipient', 1000000n);
await tx.wait();
```

The same pattern covers any contract on the QIE network: DEX routers, NFT contracts, or the QIE Domains registry. Only the ABI and address change.

### Step 6: Handle Wallet Events

Users switch accounts and networks inside the wallet at any time. Subscribe to provider events and keep your app state in sync, otherwise you will show stale balances or send transactions from the wrong account.

```javascript
const injected = getInjectedProvider();

injected.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    // User disconnected the site from the wallet.
    // QIE Wallet signals site disconnection here, not through a 'disconnect' event.
    resetAppState();
  } else {
    // Active account changed
    setActiveAccount(accounts[0]);
    refreshBalances();
  }
});

injected.on('chainChanged', (chainId) => {
  // Simplest safe handling: reload so all providers and contracts reinitialize
  window.location.reload();
});

injected.on('connect', ({ chainId }) => {
  // Provider is ready; chainId is the active chain as a hex string
  console.log('Provider connected on chain', parseInt(chainId, 16));
});
```

> **Warning:** Do not rely on a `disconnect` listener with QIE Wallet: the provider never emits that event. Site disconnection (the user removing the site from the wallet's connected sites) arrives as `accountsChanged` with an empty array, which the first listener above already handles.

In single-page apps, remove listeners on component unmount with `injected.removeListener(eventName, handler)` to avoid duplicate handlers.

### Other Supported Provider Methods

Beyond the standard calls above, QIE Wallet handles the following methods. They are not listed in the extension's public docs but work as of v4.2.2.

| Method                                      | What it does                                                                                       |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `wallet_watchAsset`                         | Prompts the user to add a token to their wallet's asset list                                       |
| `wallet_requestPermissions`                 | Re-opens the account selection prompt; this is how a user changes which accounts a site is granted |
| `wallet_revokePermissions`                  | Removes the site's account grant from the dApp side                                                |
| `net_version`                               | Returns the active chain ID as a decimal string (`"1990"`)                                         |
| `eth_sign`                                  | Legacy raw-hash signing; prefer `personal_sign`                                                    |
| `eth_signTypedData`, `eth_signTypedData_v3` | Older typed-data variants; prefer `eth_signTypedData_v4`                                           |

Any method the wallet does not handle itself is forwarded to the RPC node of the active chain, so standard read calls such as `eth_call`, `eth_getBalance`, `eth_blockNumber` and `eth_getTransactionReceipt` work through the provider without a separate RPC client.

### Alternative Stacks: viem and wagmi

Both consume the same EIP-1193 provider. Define QIE as a custom chain once and reuse it.

#### viem

```javascript
import { createWalletClient, createPublicClient, custom, http, defineChain } from 'viem';

export const qieMainnet = defineChain({
  id: 1990,
  name: 'QIE Blockchain Mainnet',
  nativeCurrency: { name: 'QIE', symbol: 'QIE', decimals: 18 },
  rpcUrls: { default: { http: ['https://rpc5mainnet.qie.digital'] } },
  blockExplorers: {
    default: { name: 'QIE Explorer', url: 'https://mainnet.qie.digital' },
  },
});

const walletClient = createWalletClient({
  chain: qieMainnet,
  transport: custom(getInjectedProvider()),
});

const publicClient = createPublicClient({
  chain: qieMainnet,
  transport: http(),
});
```

#### wagmi (React)

wagmi picks up QIE Wallet automatically through its `injected()` connector, which uses EIP-6963 discovery under the hood.

```javascript
import { createConfig, http } from 'wagmi';
import { injected } from 'wagmi/connectors';
import { qieMainnet } from './chains';

export const config = createConfig({
  chains: [qieMainnet],
  connectors: [injected()],
  transports: { [qieMainnet.id]: http() },
});
```

Use ethers.js for a minimal vanilla integration, viem for typed low-level control, and wagmi for React dApps with hooks and connection UI.

### Best Practices

> **Never ask users for their recovery phrase or private keys, in any flow, ever.** QIE Wallet is non-custodial; keys stay on the user's device.

* Trigger connection and signing only from explicit user actions.
* Validate all transaction parameters client-side and show the user exactly what they are approving (recipient, amount, contract).
* Verify signed login messages server-side and include a one-time nonce to prevent replay.
* Do not hardcode gas prices; let the wallet estimate.
* Treat a non-empty `eth_accounts` result as "connected", not "unlocked". After the wallet auto-locks it keeps returning the granted addresses, so a signing or transaction request will still open an unlock prompt first. Expect that extra step and a possible `4001` rejection.

### Troubleshooting

| Symptom                                  | Likely cause                                                               | Fix                                                                  |
| ---------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Provider is `undefined`                  | Extension not installed, page on `file://`, or script ran before injection | Check after page load; prompt install; serve over HTTPS or localhost |
| Error `4001`                             | User rejected the request in the wallet popup                              | Expected path; show a friendly retry message                         |
| Error `4902` on switch                   | QIE chain not present in the connected wallet                              | Call `wallet_addEthereumChain` with the params from Step 3           |
| Error `4902` switching to testnet (1983) | Testnet toggle is off in QIE Wallet settings, so the chain is hidden       | Ask the user to enable testnet in wallet settings, then retry        |
| Transactions fail or balance wrong       | dApp pointed at pre-V3 params (chain ID 5656 or 9731)                      | Use chain ID `1990` and the mainnet RPCs from Step 3                 |
| Wrong account used                       | `accountsChanged` not handled                                              | Subscribe to events per Step 6                                       |
| Popup never appears                      | A different wallet captured `window.ethereum`                              | Use EIP-6963 detection per Step 1                                    |

### Pre-Ship Test Checklist

* \[ ] Connect and disconnect
* \[ ] Reject each popup once
* \[ ] Switch accounts mid-session
* \[ ] Switch networks mid-session
* \[ ] Confirm a transaction end-to-end on the QIE explorer


