# Introduction and Overview

**Welcome to W Chain**

W Chain is a next-generation blockchain platform designed to bring trust, transparency, and efficiency to global payments and decentralized finance (DeFi). By combining the strengths of public and private blockchain technologies, W Chain provides businesses, developers, and users with a flexible and secure foundation to build innovative applications that scale with their needs.

**What is W Chain?**

W Chain is a hybrid blockchain platform that blends the openness and transparency of public blockchains with the control and security of private networks. This unique architecture ensures that businesses can operate with confidence, knowing they have the flexibility to maintain privacy where needed, while also benefiting from the decentralization of a public chain.

Our vision is simple: to create a world where financial transactions are fast, secure, and accessible to everyone, everywhere. Whether you’re sending cross-border payments, developing cutting-edge DeFi applications, or securing enterprise data, W Chain empowers you to do it all efficiently and cost-effectively.


# Key Features That Make W Chain

**Mainnet and Testnet**:

* The **W Chain Mainnet** is our fully operational network, where real-world applications are deployed securely and efficiently.
* The **W Chain Testnet** is a safe testing environment for developers to experiment, deploy, and fine-tune applications before launching on the Mainnet.

**Hybrid Blockchain**: W Chain’s hybrid model offers the best of both worlds—public blockchain for transparency and community-driven applications, and private blockchain for businesses that need tighter control over their data and operations.

**High Performance**: W Chain is built to handle thousands of transactions per second (TPS), ensuring that no matter the scale, your business can run smoothly without interruptions or delays.

**Scalability**: Our architecture is designed to grow with you. Whether you're a startup or a global enterprise, W Chain can scale to meet your needs with ease.

**DeFi-Ready**: Developers can quickly deploy decentralized finance applications, from staking mechanisms to complex lending and borrowing protocols.


# Roadmap

<figure><img src="/files/fY08L7XS72oYUPXhbvkJ" alt=""><figcaption></figcaption></figure>


# Node

### Overview

In a Proof-of-Stake (PoS) Ethereum Virtual Machine (EVM) compatible blockchain, nodes form the foundational infrastructure that ensures the network’s functionality, security, and decentralization. Nodes are broadly classified into two categories—Validator Nodes and Non-Validator Nodes—each fulfilling specific roles within the ecosystem. This section provides a high-level introduction to these node types and their contributions to a PoS EVM network, setting the stage for detailed exploration in subsequent sections.

### Node Types and Roles

#### Validator Node

Validator Nodes are active participants in the PoS consensus mechanism. By staking a required amount of cryptocurrency, these nodes are responsible for validating transactions, proposing new blocks, and finalizing them through a process known as "sealing." They play a critical role in maintaining the network’s security and integrity, earning staking rewards and transaction fees in return for their efforts.

#### Non-Validator Node

Non-Validator Nodes, identified by a seal: false configuration, do not engage in the consensus process or block production. Operating as full nodes or light nodes, they focus on synchronizing with the blockchain, verifying transactions and blocks for local use, and relaying data across the network. These nodes enhance accessibility, support decentralized data propagation, and provide infrastructure for applications and users without the resource-intensive demands of validation.

### Network Contribution

Validator Nodes drive the core operations of block creation and consensus, ensuring the blockchain progresses securely and consistently. Non-Validator Nodes complement this by bolstering network resilience, enabling data availability, and facilitating broader participation. Together, they create a balanced and robust PoS EVM environment.


# Non-Validator Node Setup

A Non-Validator Node is a node that does not participate in the consensus process or block production. This often used by developers, dApps, exchanges, or individuals who need to query the blockchain.

This section will guide you through setting up a Non-Validator Node on W Chain.

### **Step 1: Prepare the System** <a href="#step-1-prepare-the-system" id="step-1-prepare-the-system"></a>

Before starting, ensure your system meets the minimum requirements for running a node:

* vCPUs: 2 or more
* Memory: At least 8GB
* Disk Space: At least 200 GB (SSD or NVMe recommended for optimal performance)
* Operating System: Ubuntu 20.04, 22.04, or 24.04
* Internet Connection: A broadband connection with at least 5Mbps upload/download speed.

It's possible to run a node from a local dedicated server, but it's recommended to run it on a professional cloud providers such as AWS, Digital Ocean, Azure or GCP.

### **Step 2: Install Dependencies** <a href="#step-2-install-dependencies" id="step-2-install-dependencies"></a>

Make sure you have up-to-date version of Ubuntu, Git and NPM installed.

```bash
sudo apt update && sudo apt upgrade -y
```

```bash
sudo apt install git -y && sudo apt install npm -y
```

{% hint style="info" %}
Some system may have different package manager, here we use <mark style="color:yellow;">apt</mark>, the most commonly used
{% endhint %}

### Step 3: Prepare Directory

```bash
cd ~
mkdir w-chain
cd w-chain
```

### Step 4: Download files from latest Release

To initiate a Node, you need the latest binary and genesis.json. It always available at [W Chain's Github Repository for W chain Node](https://github.com/w-chain-team/node/releases/latest).

You need to select the suitable binary based on your Operating System and **architecture**. You can contact your Cloud Computing Provider if you are not sure about yours.

In this guide, we will use the most common one: Linux (amd64), as it's widely used in AWS EC2 instances.

#### Download BInary File

<mark style="color:yellow;">In this example we are using v.1.0.6</mark>

{% hint style="info" %}
You can download the latest binary file using `wget` or `curl`
{% endhint %}

```bash
curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/w-chain-node_v1.0.6_linux_amd64.tar.gz
```

After the download complete, print your directory contents to get the downloaded file name:

```bash
ls -lh
```

The file name will be in this format: "w-chain-node\_" + `version tag` + `system` + "\_" + `architecture` + ".tar.gz". Extract the file:

```bash
tar -xzf w-chain-node_v1.0.6_linux_amd64.tar.gz
```

Rename the file (Optional, but important for better UX):

```bash
mv w-chain-node-linux-amd64 w-chain-node
```

#### Download <mark style="color:yellow;">`genesis.json`</mark>

```bash
curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/genesis.json
```

You don't need to change anything from this genesis.json, just make sure it exists in the same directory with your binary file.

### Step 5: Verify Files

Make sure both binary file and genesis.json is correctly downloaded and in stored in same directory.&#x20;

Turn the binary file into executable:

```bash
chmod +x w-chain-node
```

Verify the version:

```bash
./w-chain-node version
```

`[VERSION INFO]`\
`Release version = 1.0.6`

### Step 6: Initialize Keys and Blockchain Data Directories

This command will initialize data directory and validator keys:

{% tabs %}
{% tab title="Mainnet" %}

```bash
./w-chain-node secrets init --data-dir main-chain --insecure
```

{% endtab %}

{% tab title="Testnet" %}

```bash
./w-chain-node secrets init --data-dir test-chain --insecure
```

{% endtab %}
{% endtabs %}

### Step 7: Create Server Config

The node is basically a server that will run 24/7, responding to queries and persisting blocks to database. Instead of passing the configs as flags to `server` command, it's strongly recommended to store the server configs in a json/yaml file.

Run this command (in <mark style="color:purple;">`/w-chain`</mark> directory) to generate server config template:

```bash
./w-chain-node server export --type json
ls -lh
```

You will see a file, <mark style="color:yellow;">`default-config.json`</mark> created.

Now, we will edit this config file to adjust with your actual server configuration.&#x20;

{% hint style="info" %}
You can use any supported text editor, in this example we use `nano`.
{% endhint %}

```bash
sudo nano default-config.json
```

{% hint style="warning" %}
This config below assuming you are following previous steps convention on directory creation. It also recommended to use absolute path, which can be different from system to system (usually /home/user/w-chain)
{% endhint %}

#### <mark style="color:yellow;">`genesis.json`</mark> location

```json
"chain_config": "/home/ubuntu/w-chain/genesis.json",
```

#### Path to Data Directory

{% tabs %}
{% tab title="Mainnet" %}

```json
"data_dir": "/home/ubuntu/w-chain/main-chain", 
```

{% endtab %}

{% tab title="Testnet" %}

```json
"data_dir": "/home/ubuntu/w-chain/main-chain", 
```

{% endtab %}
{% endtabs %}

#### Ports

```json
"grpc_addr": "127.0.0.1:9632", 
"jsonrpc_addr": "0.0.0.0:8545", 
```

{% hint style="warning" %}
NAT Address is your server/instance's Public IP
{% endhint %}

```json
"network": {
    ...
    "libp2p_addr": "0.0.0.0:1478", 
    "nat_addr": "12.34.567.890",
    ...
}
```

#### Minimum Gas Price accepted and Seal flag

{% hint style="info" %}
For Non-Validator Node, **Seal must be false**.\
Per v1.0.6 Min Gas Price in W Chain Network is 8 Gwei
{% endhint %}

```json
"price_limit": 800000000000,
"seal": false
```

### Step 8: Utilizing Blockchain Backup File

Joining a blockchain network will require a new node to sync with other existing nodes, this can take days even weeks, depends on how long the network already running so far. We have prepared backup files to jump start the process for you.&#x20;

{% hint style="info" %}
This backup file will be updated from time to time to ensure new node operators will have closer starting point to sync their new nodes to W Chain Network
{% endhint %}

```bash
# In the ./w-chain directory
cd main-chain
```

#### Download and unpack Trie

```sh
curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/20250908/trie.tar.gz
```

```sh
tar -xzf trie.tar.gz && rm trie.tar.gz
```

#### Download and unpack Blockchain

```sh
curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/20250908/blockchain.tar.gz
```

```sh
tar -xzf blockchain.tar.gz && rm blockchain.tar.gz
```

{% hint style="info" %}
Downloading and unpacking the Blockchain backup file will take some time, depends on your internet connection speed and Storage I/O rate
{% endhint %}

After this step, you should have 2 new directories (<mark style="color:blue;">`blockchain`</mark> and <mark style="color:blue;">`trie`</mark>), in addition to the existing <mark style="color:blue;">`consensus`</mark> and <mark style="color:blue;">`libp2p`</mark>.

#### Aligning permission and directory ownership

```sh
pwd
```

This will print your current working directory (i.e. `/home/ubuntu/w-chain/main-chain`), **copy it.**

```sh
ls -ld /w-chain/main-chain
```

you will see something like this:

```
drwxr-x--- 6 ubuntu ubuntu 4096 Apr 12 14:08 /data/w-chain/main-chain
```

based on the example above, we can see the user and user group is <mark style="color:yellow;">`ubuntu:ubuntu`</mark> (this may vary, depends on your system). Now, that we know the user and user group, we can align the permission:

```sh
sudo chown -R ubuntu:ubuntu /home/ubuntu/w-chain/main-chain
```

Now, your blockchain data is ready!

### Step 9: Create a System Service

To keep your Node instance running as a background service, you need to define the service. Run this on your terminal (inside your server/instance).

```bash
sudo nano /etc/systemd/system/w-chain-node.service
```

The text editor will open a blank page. Copy-paste the texts below into it:

```
[Unit]
Description=W Chain Validator Node
After=network.target
StartLimitIntervalSec=1

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/w-chain/w-chain-node server --config /home/ubuntu/w-chain/default-config.json

[Install]
WantedBy=multi-user.target
```

Then save and exit the text editor.

{% hint style="warning" %}
Once again, this is assuming you are following the directory and filename convention from previous steps. Your system may have different absolute path and different user, please adjust as needed.
{% endhint %}

### Step 10: Enable and Run the Node Service

After installing new service, you have to reload the service daemon and enable the service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable w-chain-node.service
```

Then start the service:

```bash
sudo systemctl start w-chain-node.service
```

**Congratulations**! Your node is now running and will start to catch up with the network, this may take few days, depends on the block-height and the I/O performance of your node.

### Important Commands to Maintain and Monitor Your Node

#### Service

{% tabs %}
{% tab title="Start Service" %}

```bash
sudo systemctl start w-chain-node.service
```

{% endtab %}

{% tab title="Stop Service" %}

```bash
sudo systemctl stop w-chain-node.service
```

{% endtab %}

{% tab title="Restart Service" %}

```bash
sudo systemctl restart w-chain-node.service
```

{% endtab %}
{% endtabs %}

#### Logging

{% tabs %}
{% tab title="Show Log" %}

```bash
journalctl -u w-chain-node
```

{% endtab %}

{% tab title="Live Log Print" %}

```bash
journalctl -u w-chain-node -f
```

{% endtab %}
{% endtabs %}


# Validator Node Setup

This section will guide you through setting up a Validator Node on W Chain.

### **Step 1: Prepare the System** <a href="#step-1-prepare-the-system" id="step-1-prepare-the-system"></a>

Before starting, ensure your system meets the minimum requirements for running a node:

* vCPUs: 4 or more
* Memory: At least 16GB
* Disk Space: At least 1TB (SSD or NVMe recommended for optimal performance)
* Operating System: Ubuntu 20.04, 22.04, or 24.04
* Node JS v.22 and NPM v10 or newer
* Internet Connection: A broadband connection with at least 5Mbps upload/download speed.

It's possible to run a node from a local dedicated server, but it's recommended to run it on a professional cloud providers such as AWS, Digital Ocean, Azure or GCP.

### **Step 2: Install Dependencies** <a href="#step-2-install-dependencies" id="step-2-install-dependencies"></a>

Make sure you have up-to-date version of Ubuntu, Git and NPM installed.

```bash
sudo apt update && sudo apt upgrade -y
```

```bash
sudo apt install git -y && sudo apt install npm -y
```

{% hint style="info" %}
Some system may have different package manager, here we use <mark style="color:yellow;">apt</mark>, the most commonly used
{% endhint %}

### Step 3: Prepare Directory

```bash
cd ~
mkdir w-chain
cd w-chain
```

### Step 4: Download files from latest Release

To initiate a Node, you need the latest binary and genesis.json. It always available at [W Chain's Github Repository for W chain Node](https://github.com/w-chain-team/node/releases/latest).

You need to select the suitable binary based on your Operating System and **architecture**. You can contact your Cloud Computing Provider if you are not sure about yours.

In this guide, we will use the most common one: Linux (amd64), as it's widely used in AWS EC2 instances.

#### Download BInary File

<mark style="color:yellow;">In this example we are using v.1.0.6</mark>

{% hint style="info" %}
You can download the latest binary file using `wget` or `curl`
{% endhint %}

```bash
curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/w-chain-node_v1.0.6_linux_amd64.tar.gz
```

After the download complete, print your directory contents to get the downloaded file name:

```bash
ls -lh
```

The file name will be in this format: "w-chain-node\_" + `version tag` + `system` + "\_" + `architecture` + ".tar.gz". Extract the file:

```bash
tar -xzf w-chain-node_v1.0.6_linux_amd64.tar.gz
```

Rename the file (Optional, but important for better UX):

```bash
mv w-chain-node-linux-amd64 w-chain-node
```

#### Download <mark style="color:yellow;">`genesis.json`</mark>

```bash
curl -L -O https://github.com/w-chain/node/releases/download/v1.0.6/genesis.json
```

You don't need to change anything from this genesis.json, just make sure it exists in the same directory with your binary file.

### Step 5: Verify Files

Make sure both binary file and genesis.json is correctly downloaded and in stored in same directory.&#x20;

Turn the binary file into executable:

```bash
chmod +x w-chain-node
```

Verify the version:

```bash
./w-chain-node version
```

`[VERSION INFO]`\
`Release version = 1.0.6`

### Step 6: Initialize Keys and Blockchain Data Directories

This command will initialize data directory and validator keys:

{% tabs %}
{% tab title="Mainnet" %}

```bash
./w-chain-node secrets init --data-dir main-chain --insecure
```

{% endtab %}

{% tab title="Testnet" %}

```bash
./w-chain-node secrets init --data-dir test-chain --insecure
```

{% endtab %}
{% endtabs %}

You will see the newly created public keys printed like this:

```
[SECRETS OUTPUT]
Public key (address) = 0x9C107AA6471e3...E9c6EdE083b8f5
BLS Public key       = 0x800f1157a49bb59f5e5d790...fe349fa19a3c323f518a4bd4aa963
Node ID              = 16Uiu2HAmVbykGW...DUpLgTw7NbDVbKf1Me4D
```

You can copy-paste it to some quick note to be used in next steps. We will also need the Private Key of this newly created Public Key.

{% tabs %}
{% tab title="Mainnet" %}

```bash
cd ~/w-chain/main-chain/consensus
nano validator.key
```

{% endtab %}

{% tab title="Testnet" %}

```bash
cd ~/w-chain/test-chain/consensus
nano validator.key
```

{% endtab %}
{% endtabs %}

You will see a single line of string. This is the **Private Key**.

Same as above, copy the Private Key and store it <mark style="color:yellow;">somewhere</mark> <mark style="color:yellow;">**safe**</mark>, we will use it in next step.

When you are done, exit the text editor, no need to save anything. And go back to root directory of your Node:

```bash
cd ../../
```

### Step 7: Create Server Config

The node is basically a server that will run 24/7, responding to queries and persisting blocks to database. Instead of passing the configs as flags to `server` command, it's strongly recommended to store the server configs in a json/yaml file.

Run this command (in <mark style="color:purple;">`/w-chain`</mark> directory) to generate server config template:

```bash
./w-chain-node server export --type json
ls -lh
```

You will see a file, <mark style="color:yellow;">`default-config.json`</mark> created.

Now, we will edit this config file to adjust with your actual server configuration.&#x20;

{% hint style="info" %}
You can use any supported text editor, in this example we use `nano`.
{% endhint %}

```bash
sudo nano default-config.json
```

{% hint style="warning" %}
This config below assuming you are following previous steps convention on directory creation. It also recommended to use absolute path, which can be different from system to system (usually /home/user/w-chain)
{% endhint %}

#### <mark style="color:yellow;">`genesis.json`</mark> location

```json
"chain_config": "/home/ubuntu/w-chain/genesis.json",
```

#### Path to Data Directory

{% tabs %}
{% tab title="Mainnet" %}

```json
"data_dir": "/home/ubuntu/w-chain/main-chain", 
```

{% endtab %}

{% tab title="Testnet" %}

```json
"data_dir": "/home/ubuntu/w-chain/main-chain", 
```

{% endtab %}
{% endtabs %}

#### Ports

{% hint style="warning" %}
This setup is meant for a Consensus purpose only, thus we disable the RPC function by removing the jsonrpc address.
{% endhint %}

```json
"grpc_addr": "127.0.0.1:9632", 
"jsonrpc_addr": "", 
```

Network section

```json
"network": {
    ...
    "libp2p_addr": "0.0.0.0:1478",
    ...
}
```

#### Minimum Gas Price accepted and Seal flag

{% hint style="info" %}
For Validator Node, Seal must be true.\
Per v1.0.6 Min Gas Price in W Chain Network is 8 Gwei
{% endhint %}

```json
"price_limit": 800000000000,
"seal": true
```

### Step 8: Utilizing Blockchain Backup File

Joining a blockchain network will require a new node to sync with other existing nodes, this can take days even weeks, depends on how long the network already running so far. We have prepared backup files to jump start the process for you.&#x20;

{% hint style="info" %}
This backup file will be updated from time to time to ensure new node operators will have closer starting point to sync their new nodes to W Chain Network
{% endhint %}

```bash
# In the ./w-chain directory
cd main-chain
```

#### Download and unpack Trie

```sh
curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/20250908/trie.tar.gz
```

```sh
tar -xzf trie.tar.gz && rm trie.tar.gz
```

#### Download and unpack Blockchain

```sh
curl -L -O https://w-chain-data.s3.eu-north-1.amazonaws.com/20250908/blockchain.tar.gz
```

```sh
tar -xzf blockchain.tar.gz && rm blockchain.tar.gz
```

{% hint style="info" %}
Downloading and unpacking the Blockchain backup file will take some time, depends on your internet connection speed and Storage I/O rate
{% endhint %}

After this step, you should have 2 new directories (<mark style="color:blue;">`blockchain`</mark> and <mark style="color:blue;">`trie`</mark>), in addition to the existing <mark style="color:blue;">`consensus`</mark> and <mark style="color:blue;">`libp2p`</mark>.

#### Aligning permission and directory ownership

```sh
pwd
```

This will print your current working directory (i.e. `/home/ubuntu/w-chain/main-chain`), **copy it.**

```sh
ls -ld /w-chain/main-chain
```

you will see something like this:

```
drwxr-x--- 6 ubuntu ubuntu 4096 Apr 12 14:08 /data/w-chain/main-chain
```

based on the example above, we can see the user and user group is <mark style="color:yellow;">`ubuntu:ubuntu`</mark> (this may vary, depends on your system). Now, that we know the user and user group, we can align the permission:

```sh
sudo chown -R ubuntu:ubuntu /home/ubuntu/w-chain/main-chain
```

Now, your blockchain data is ready!

### Step 9: Staking Contract

To join W Chain Network as a Validator Node, each node must stake at least 10,000,000 (10 Million) WCO. This is to ensure the Node operators to act honestly and follow the consensus, as any malicious act will result to stake slashing (rogue node will lose a part of its staked WCO).

{% hint style="info" %}
Running Node in W Chain Network also offer a lucrative Staking Reward, which explained in more details in this section.
{% endhint %}

#### Clone Staking Contract Script from W Chain Repository

```bash
cd ~/w-chain
git clone https://github.com/w-chain/staking-contract.git
```

It should create new directory: <mark style="color:purple;">staking-contract</mark>. Enter the directory and install the node dependencies

```bash
cd ~/w-chain/staking-contract
npm i
```

The process will only take few seconds, run this command next:

```bash
cp .env.example .env
sudo nano .env
```

This will copy the template .env and open it in a text editor, you will see this:

```
#JUST ADD YOUR PRIVATE KEY HERE
PRIVATE_KEY=your_private_key_here

# KEEP THIS AS IS
CONTRACT_ADDRESS=0xfAc510D5dB8cadfF323D4b979D898dc38F3FB6dF
RPC_URL=https://rpc.w-chain.com
```

Replace <mark style="color:orange;">your\_private\_key\_here</mark> with the actual Private Key you copied [back in Step 6](#step-6-initialize-keys-and-blockchain-data-directories). Do not change anything else, **save and exit** the text editor.

### Step 10: Load up the Stake

{% hint style="info" %}
(Optional) You can import the Private Key to a wallet app for your convenience.
{% endhint %}

The next important step is to fund the Validator address (Public Key) with WCO. Please remember, you need some WCO for gas fee, too! Ideally, you should have at least <mark style="color:yellow;">**10,000,001 WCO**</mark> inside this address.

After you fund the address, go to <mark style="color:purple;">`/staking-contract`</mark> directory and run the <mark style="color:orange;">`stake`</mark> script:

```bash
cd ~/w-chain/staking-contract
npm run cli stake 10000000
```

Wait for the script to process, if everything is correct, you will get the transaction hash returned.

Next, we will register BLS Public Key (obtained [from Step 6](#step-6-initialize-keys-and-blockchain-data-directories)). Run this command:

```bash
npm run cli registerBLSPublicKey 0x800f1157a49bb59f5e5d790...fe349fa19a3c323f518a4bd4aa963
```

{% hint style="warning" %}
This is an example, use your actual BLS Public Key
{% endhint %}

Wait for the script to process the on-chain call, if everything is correct, you will get the transaction hash returned.

{% hint style="info" %}
You can use isValidator method (<mark style="color:orange;">`npm run cli isValidator <address>`</mark>) to verify if your Public Key is now registered as Validator.
{% endhint %}

{% hint style="success" %}
After you done the <mark style="color:orange;">`stake`</mark> and <mark style="color:orange;">`registerBLSPublicKey`</mark>, your Validator Node is ready to run!
{% endhint %}

### Step 11: Create a System Service

To keep your Node instance running as a background service, you need to define the service. Run this on your terminal (inside your server/instance).

```bash
sudo nano /etc/systemd/system/w-chain-node.service
```

The text editor will open a blank page. Copy-paste the texts below into it:

```
[Unit]
Description=W Chain Validator Node
After=network.target
StartLimitIntervalSec=1

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/w-chain/w-chain-node server --config /home/ubuntu/w-chain/default-config.json

[Install]
WantedBy=multi-user.target
```

Then save and exit the text editor.

{% hint style="warning" %}
Once again, this is assuming you are following the directory and filename convention from previous steps. Your system may have different absolute path and different user, please adjust as needed.
{% endhint %}

### Step 12: Enable and Run the Node Service

After installing new service, you have to reload the service daemon and enable the service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable w-chain-node.service
```

Then start the service:

```bash
sudo systemctl start w-chain-node.service
```

**Congratulations**! Your node is now running and will start to catch up with the network, this may take few days, depends on the block-height and the I/O performance of your node.

### Important Commands to Maintain and Monitor Your Node

#### Service

{% tabs %}
{% tab title="Start Service" %}

```bash
sudo systemctl start w-chain-node
```

{% endtab %}

{% tab title="Stop Service" %}

```bash
sudo systemctl stop w-chain-node
```

{% endtab %}

{% tab title="Restart Service" %}

```bash
sudo systemctl restart w-chain-node
```

{% endtab %}
{% endtabs %}

#### Logging

{% tabs %}
{% tab title="Show Log" %}

```bash
journalctl -u w-chain-node
```

{% endtab %}

{% tab title="Live Log Print" %}

```bash
journalctl -u w-chain-node -f
```

{% endtab %}
{% endtabs %}


# Proof of Stake

**Proof of Stake (PoS)** is a consensus mechanism used by blockchain networks like W Chain to secure the network and validate transactions. Unlike Proof of Work (PoW), which relies on miners solving complex cryptographic puzzles, PoS allows network participants (known as validators) to produce and validate new blocks based on the amount of cryptocurrency they hold and are willing to “stake” (lock up) as collateral.

The PoS mechanism reduces energy consumption compared to PoW, while also incentivizing participants to act honestly since they have a financial stake in the network.

#### How PoS Works in W Chain

In W Chain’s PoS implementation, validators are selected based on their staked tokens, and they are responsible for producing and validating blocks. Validators earn rewards for their work but can also face penalties if they act dishonestly or fail to perform their duties.

Here’s how the PoS mechanism functions in W Chain:

1. **Validators Stake Tokens**: To become a validator, participants must lock up (or stake) a minimum amount of W Chain tokens in a staking contract.
2. **Block Validation**: Validators are chosen to produce blocks based on the amount of tokens they have staked and their past performance. Once selected, the validator proposes a new block to be added to the blockchain.
3. **Rewards and Penalties**: Validators earn rewards for producing valid blocks. However, if they attempt to manipulate the network or act maliciously, they risk losing part or all of their staked tokens.

<figure><img src="/files/wQQMB4qERUui387x2n8o" alt=""><figcaption></figcaption></figure>

**Staking in W Chain**

Staking is the process by which participants lock up their W Chain tokens to become validators. Validators are essential for maintaining the network's security and producing new blocks. The more tokens a validator stakes, the higher their chances of being selected to validate blocks and earn rewards.

**Benefits of Staking**:

* **Earning Rewards**: Validators earn rewards for producing blocks and validating transactions.
* **Network Security**: Staking ensures that validators are financially motivated to act honestly, securing the network.
* **Participation in Consensus:** Validators play a key role in maintaining consensus and ensuring the blockchain operates smoothly.

**Unstaking in W Chain**

Unstaking is the process of withdrawing staked tokens from the validator set. Validators can only unstake all of their tokens at once. After unstaking, they are no longer eligible to validate blocks or earn rewards.

**Important Considerations**:

* Validators must unstake all tokens at once; partial unstaking is not allowed.
* After unstaking, validators no longer participate in block production or receive rewards.

#### Epochs and Validator Responsibilities

Epochs are a critical concept in W Chain’s PoS implementation. They define specific time frames (measured in blocks) during which a particular set of validators is responsible for block production.

**How Epochs Work:**

1. **Epoch Duration**: Each epoch lasts for a set number of blocks. The duration can be configured by node operators during the genesis block creation.
2. **Validator Set Update**: At the end of each epoch, the validator set is updated. Validators query the ValidatorSet Smart Contract to retrieve the new set of validators for the next epoch.
3. **New Epoch Start**: After the epoch block is produced, a new epoch begins with the updated validator set.

**Why Epochs Are Important**:

* **Validator Rotation**: Epochs ensure that the validator set is regularly updated, providing fairness and decentralization. New validators can join, and inactive or dishonest validators are removed.
* **Staking and Unstaking**: Validators can only join or leave the set at the end of an epoch, ensuring the stability of the network during each epoch.

#### Validator Responsibilities

**Validators are responsible for**:

1. **Block Production**: Validators propose new blocks to be added to the blockchain. This requires maintaining a consistent connection to the network and following the consensus rules.
2. **Validating Transaction**s: Validators must ensure that all transactions in the proposed block are valid according to the network rules.
3. **Staking and Security**: Validators need to maintain their stake and ensure their node is operating correctly. Misbehavior or downtime can result in penalties or removal from the validator set.

**Penalties and Slashing**:

* Validators who act maliciously or fail to perform their duties may lose a portion of their staked tokens through a process called slashing. This incentivizes validators to act honestly and secure the network.

#### Proof of Stake Workflow in W Chain

1. **Become a Validator**:

* Stake the required minimum number of W Chain tokens.
* The validator becomes part of the validator set and is eligible to propose blocks.

2. **Participate in Consensus**:

* Validators are randomly selected to propose blocks based on the amount of staked tokens and their past performance.
* Validators validate transactions and propose a block to the network.

**Earn Rewards**:

* Validators earn W Chain token rewards for each valid block they produce.

4. **Unstaking:**

* Validators can choose to unstake their tokens, at which point they are removed from the validator set and cease participating in block production.


# Trade

This guide explains how to use the Trade page of W Swap. The interface is a familiar Uniswap V2-style experience adapted for W Chain (native token `WCO`) with the same core flow: connect a wallet, select tokens, approve if required, set slippage, and confirm the trade.

### Overview

* Network: W Chain (EVM-compatible; native gas token `WCO`)
* Purpose: Trade between supported ERC‑20 tokens on W Chain
* Model: a constant-product AMM (x·y = k)
* Key actions: Token selection, allowance approval, slippage and deadline configuration, transaction confirmation

### Prerequisites

* A supported EVM wallet such as `Rabby` (recommended) or `MetaMask` installed in your browser.
* Some `WCO` to pay gas fees on W Chain.
* Bridged or existing assets on W Chain. If your assets are on Ethereum or BNB Chain, you can use the Bridge page to bring them to W Chain first.

### Connect Your Wallet

1. Open W Swap and click `Connect Wallet`.
2. Select your wallet—`Rabby` (recommended) offers enhanced transaction safety; `MetaMask` is also supported.
3. Switch to `W Chain` in your wallet when prompted. If W Chain is not added, the app can suggest adding it automatically.

### Select Tokens and Amounts

1. On the Trade page, use the token selectors for `From` and `To`.
2. Choose a token from the list or paste a contract address for custom tokens.
3. Enter the `From` amount; the interface quotes the estimated output and route.
4. Review:
   * `Price Impact`: Expected slippage due to trade size vs. pool depth.
   * `Minimum Received`: Accounted for slippage tolerance.
   * `Route`: The path across pools the trade will take.

Notes on Wrapped Native Token:

* Some interfaces label the wrapped native token as `WETH` historically. On W Chain, the native token is `WCO`, and its wrapped form may be shown as `Wrapped WCO (WWCO)`. Treat any “WWCO or WETH” entry as the wrapped version of WCO used in pools.

### Allowance Approval (If Required)

Many ERC‑20 tokens require an on-chain approval before they can be spent by the router.

1. If you see an `Approve` button, click it to submit an approval transaction.
2. Wait for confirmation in your wallet and the explorer.
3. Once approved, the `Swap` button becomes available.

### Settings: Slippage and Deadline

* Slippage Tolerance: Adjust in the settings panel to control acceptable price movement. A typical range is `0.1%–1%` for liquid pools; higher for illiquid assets.
* Transaction Deadline: Prevents stuck trades; the swap reverts if not included before the deadline.
* Expert Mode: If available, use with caution; it disables some safety checks.

### Execute the Trade

1. Click `Trade` (the button may be labeled `Swap` in the UI).
2. Review the summary in the confirmation modal.
3. Confirm in your wallet and wait for the transaction to be mined.
4. Track the transaction via the link to `scan.w-chain.com` provided by the DApp.

### Troubleshooting

* `Insufficient Liquidity`: Try smaller amounts or a different route.
* `Approval Failed`: Reopen your wallet, confirm permissions, and retry.
* `High Price Impact Warning`: Reduce trade size or split into smaller trades.
* `Transaction Reverted`: Increase slippage tolerance slightly or check token allowances.
* `Stuck/Pending`: Consider increasing gas settings in your wallet and resubmitting.

### Safety Tips

* Only paste token addresses from trusted sources.
* Double-check the `Minimum Received` value matches expectations.
* Keep some `WCO` for gas; trades will fail if your gas balance is 0.

### FAQs

* Can I trade from Ethereum or BNB Chain directly? No, first bridge supported assets to W Chain using the `Bridge` page, then trade on W Chain.
* Why do I see `Approve` before `Trade`? ERC‑20 tokens require a one-time allowance for the router to spend your tokens.
* Where do I view my transaction? Use the explorer link (e.g., `https://scan.w-chain.com/tx/<hash>`).


# Liquidity

Provide and manage liquidity in constant-product AMM pools on W Chain. This guide covers creating positions, understanding LP tokens and fees, and safely removing liquidity.

### Overview

* Network: W Chain (EVM-compatible; native gas token `WCO`)
* Model: a constant-product AMM (x·y = k)
* LP Tokens: Minted to represent your position; burned when removing liquidity
* Fees: 0.25% per trade paid to LPs (accrues within pool reserves)

### Prerequisites

* A supported wallet (e.g., Rabby or Metamask) connected to `W Chain`.
* Sufficient `WCO` for gas.
* The two assets you want to deposit. If assets are on Ethereum or BNB Chain, bridge them first.

### Add Liquidity

1. Open `Liquidity` or `Add Liquidity` page.
2. Select the token pair (Token A and Token B). You may paste contract addresses for custom tokens.
3. Enter an amount for one token; the UI computes the corresponding amount for the other token based on current pool price.
4. Approve spending for each token if prompted (`Approve Token A` / `Approve Token B`).
5. Review details:
   * `Pool Share`: Estimated percentage of the pool you’ll own.
   * `Prices`: Implied exchange rates after your deposit.
   * `Slippage/Min Received`: Relevant when creating the initial pool or large deposits.
6. Click `Supply` (or `Add Liquidity`) and confirm in your wallet.
7. After confirmation, you receive `LP tokens` representing your position.

Notes:

* If a pool does not exist yet, your deposit sets the initial price. Carefully choose amounts to avoid unintended pricing.
* For new pools, higher slippage tolerance may be needed; the UI will guide you.

### Remove Liquidity

1. Navigate to your position (e.g., `Pool` page or `Your Liquidity`).
2. Choose the position and select `Remove`.
3. If prompted, approve the router to spend your LP tokens (`Approve LP`).
4. Select the percentage to remove (e.g., 25%, 50%, 100%).
5. Review expected amounts of Token A and Token B.
6. Click `Remove`, confirm in your wallet, and wait for the transaction to finalize.

### Fees and Rewards

* Each trade pays a 0.25% liquidity fee to LPs, accruing inside the pool as additional reserves.
* Your portion of fees is implicit in the increased value of your LP tokens.
* Realization occurs when you withdraw liquidity (your redeemed amounts include fee accrual).

### Risks and Best Practices

* Impermanent Loss: Price divergence between tokens can reduce your position value vs. holding.
* Slippage: Large deposits/withdrawals can move price; consider splitting actions.
* Smart Contract Risk: Use official UI and verified token addresses.
* Gas Costs: Keep `WCO` for approvals, adds, and removals.

### Troubleshooting

* `Approve Required`: Approve both tokens before adding liquidity; approve LPs before removing.
* `Insufficient Balance`: Confirm balances on W Chain and consider bridging if needed.
* `Transaction Reverted`: Increase slippage tolerance or reduce deposit size.
* `No Positions Visible`: Ensure correct wallet and network (`W Chain`) are selected.

### FAQs

* How do I earn fees? Fees accumulate in the pool; your LP token share entitles you to a proportional claim when you withdraw.
* Can I add single-sided liquidity? a constant-product AMM requires balanced deposits; use a swap first if needed.
* Where can I see my positions? Use the `Pool` or `Your Liquidity` view in the DApp.


# Bridge

Bridge supported assets between W Chain and other networks using W Swap’s Bridge page. This guide covers supported chains and tokens, approvals, transaction statuses, and best practices.

### Overview

* Networks Supported: `Ethereum`, `BNB Chain`, and `W Chain`
* Native Tokens: `ETH` (Ethereum), `BNB` (BNB Chain), `WCO` (W Chain)
* Purpose: Move supported assets cross‑chain to trade or provide liquidity on W Chain
* Finality: A validator-based process confirms bridge transfers; funds are minted or released when votes reach quorum

### Supported Assets

* From Ethereum → W Chain:
  * `USDT`
  * `USDC`
* From BNB Chain → W Chain:
  * `bUSDT`
  * `bUSDC`
  * `XRP` (BEP‑20)
  * `DOGE` (BEP‑20)
  * `SOL` (BEP‑20)
* From W Chain → Ethereum or BNB Chain:
  * Tokens mirrored on W Chain including `USDT`, `USDC`, and Binance‑peg variants (`bUSDT`, `bUSDC`), plus `XRP`, `DOGE`, `SOL` for BNB Chain direction.

Note:

* Token availability depends on the selected From/To networks. The Bridge page filters assets accordingly.
* On W Chain, bridged tokens have distinct addresses; always verify the token symbol and address shown in the UI.

### Chain IDs and Explorer Links

* Chain IDs:
  * `Ethereum Mainnet`: `1`
  * `BNB Chain Mainnet`: `56`
  * `W Chain Mainnet`: `171717`
* Explorers (used by the DApp):
  * Ethereum: `https://etherscan.io/tx/<hash>`
  * BNB Chain: `https://bscscan.com/tx/<hash>`
  * W Chain: `https://scan.w-chain.com/tx/<hash>`

Testnets (if applicable):

* `Sepolia` (Ethereum): `11155111`
* `BNB Chain Testnet`: `97`
* `W Chain Testnet`: `71117` (Explorer: `https://scan-testnet.w-chain.com/tx/<hash>`)

### Prerequisites

* A supported EVM wallet (e.g., Rabby—recommended for enhanced safety—or MetaMask).
* Gas on the source chain (`ETH` for Ethereum, `BNB` for BNB Chain, `WCO` for W Chain).
* The token you want to bridge in your source chain wallet.

### Bridging Steps

1. Open the `Bridge` page and connect your wallet.
2. In `From`, choose the source network (Ethereum / BNB Chain / W Chain). In `To`, choose the destination.
3. Select a supported asset for the chosen route; use the token selector or search.
4. Enter the amount to bridge. The UI shows any limits/fees and estimated arrival.
5. If prompted, click `Approve` to grant the bridge contract permission to transfer your token.
6. Click `Bridge` and confirm in your wallet.
7. Track status in the `Confirm` modal and `Bridge History`. Typical statuses include:
   * `Transaction Initialized`
   * `Transaction Pending`
   * `Transaction Submitted`
   * `Transaction Awaiting Validators Votes`
   * `Transaction Successful` (funds arrive on destination)
   * `Transaction Failed` or `Rejected`

Arrival and Claiming:

* No manual claim step is generally required. Funds are credited on the destination chain once validators finalize the transfer.
* The DApp provides explorer links for both source and destination transactions.

### Fees and Timing

* Fees vary by route and token. They are displayed before you confirm the bridge.
* Timing depends on source chain congestion and validator finalization. Expect longer times during network congestion.

### Bridge History

* Use `Bridge History` to review previous transfers, current status, and retry or reference transaction hashes as needed.

### Troubleshooting

* `Approval Required`: Approve the specific token on the source chain before bridging.
* `Unsupported Route`: Switch networks or choose a supported asset for the selected From/To pair.
* `Pending Too Long`: Check the explorer links and try again during lower congestion; ensure adequate gas.
* `Rejected/Failed`: Review wallet prompts, increase gas settings if necessary, and retry.

### Safety Tips

* Only bridge tokens listed by the DApp; do not paste arbitrary addresses.
* Confirm the `From` and `To` networks are correct before submitting.
* Maintain sufficient gas on both sides if you plan to interact immediately after bridging.

### FAQs

* Can I bridge directly to trade? Yes—bridge first to W Chain, then use the Trade page.
* Do I need to claim funds? No, funds arrive automatically after validator finalization.
* Where do I find transaction links? In the modal and history, linking to `etherscan.io`, `bscscan.com`, and `scan.w-chain.com`.


# WAVE


# Farm

<figure><img src="/files/cQA7QC7Lb4LaLcPlcgBb" alt=""><figcaption></figcaption></figure>

### What Is WAVE Farm?

* **Network**: W Chain (custom EVM network). Gas token is `WCO` (acts like ETH on W Chain).
* **DEX**: [W Swap](/w-swap/trade). Liquidity providers receive **LP tokens** that represent their share of a pool.
* **Farm**: WAVE Farm lets you stake those LP tokens to earn **WAVE** rewards.

***

### Quick Start

1. Open `https://wave.w-chain.com` in a desktop browser with an EVM wallet (Rabby is recommended).
2. Connect your wallet. If prompted, approve adding **W Chain** to your wallet.
3. Fund your wallet with some `WCO` to pay gas fees.
4. Add liquidity on [**W Swap** Liquidity Pool page](/w-swap/liquidity) to receive LP tokens.
5. Return to **WAVE Farm** and stake the LP tokens to start earning WAVE.

***

### Interface Overview

* **Total Value Locked (TVL)**: Overall value staked in the protocol.
* **Your Farms**: Shows your total staked amount, pending rewards, and pool list.
* **Actions**:
  * `Add Liquidity`: Shortcut to W Swap’s liquidity page.
  * `Harvest All`: Claim all pending WAVE rewards across all pools.
  * Per‑pool actions: `Stake / Deposit`, `Harvest`, and `Withdraw`.

***

### How It Works (LP Staking)

* You deposit LP tokens (from W Swap) into the farm’s contracts.
* The farm periodically distributes **WAVE** rewards to each pool based on allocation (weight/multiplier).
* Your share of the pool’s rewards depends on your **stake relative to total staked LP** in that pool.

***

### [Add Liquidity on W Swap](/w-swap/liquidity#add-liquidity)

1. Go to `https://w-swap.com/#/pool`.
2. Select a token pair (e.g., `WAVE/WCO`, `USDT/WCO`).
3. Provide equal value of each token and confirm the transaction.
4. After the transaction, you’ll receive **LP tokens** for that pair.

Tip: Pools with higher multipliers may have higher reward rates but often attract more stakers (see Dilution below).

***

### Stake (Deposit) LP Tokens

1. On `https://wave.w-chain.com`, locate the pool that matches your LP token (e.g., `WAVE/WCO`).
2. Click `Stake` or `Deposit`.
3. If this is your first time, click `Approve` to allow the farm to use your LP tokens.
4. Enter the LP amount to stake and confirm the transaction.
5. After confirmation, your staked balance appears under the pool, and rewards begin accruing.

Notes:

* Approval is a one‑time transaction per LP token.
* Gas fees are paid in `WCO`. Keep a small buffer for future actions.

***

### Harvest Rewards (Single Pool)

1. In the pool row, click `Harvest` to claim your pending WAVE from that pool.
2. Confirm the transaction in your wallet.
3. After confirmation, your wallet receives WAVE and the pool’s pending amount resets to `0`.

When to harvest:

* You can harvest anytime. Frequent harvesting increases gas costs; occasional harvesting is more cost‑efficient.

***

### Harvest All (Across All Pools)

1. Click `Harvest All` in the top right of Your Farms.
2. Review the summary (pending WAVE amount) and confirm.
3. The app sends transactions to claim rewards from all pools you are staked in.

Tip: Harvest All is convenient but may cost more gas overall than harvesting only the pool(s) you care about at the moment.

***

### Withdraw LP Tokens

1. In the pool row, click `Withdraw`.
2. Enter the LP amount you want to remove and confirm.
3. Your LP tokens return to your wallet; you stop earning rewards on the withdrawn amount.

Common reasons to withdraw:

* Rebalancing liquidity, reducing exposure, or moving to a different pool.

***

### Reward APR Explained

* **APR** is the annualized rate of rewards distributed to a pool, expressed as a percentage of the pool’s total value.
* It depends on several factors, and therefore **changes over time**:
  * WAVE emission rate to farms.
  * Pool weight/multiplier (allocation).
  * Total value staked in the pool (TVL).
  * Market price of WAVE and the LP tokens.

Conceptual formula:

```
Pool APR ≈ (Rewards to pool per year × WAVE price) / Pool TVL
```

Your personal yield will be close to the pool APR when your share of the pool is small relative to total TVL; harvesting and compounding can move you closer to **APY** (with compounding) rather than APR (no compounding).

***

### Dilution Risk (Why Your APR Can Drop)

* **Dilution** happens when more users stake into the same pool. Your fractional share of rewards becomes smaller.
* Pools with high multipliers often attract new stake quickly, which can dilute early participants unless they also increase stake.
* Practical implications:
  * If TVL rises faster than rewards allocated to the pool, APR falls.
  * Your pending rewards accumulate at a slower rate when your share shrinks.
  * To maintain yield, some users harvest and restake (compound), but this requires additional gas and exposes you to IL (impermanent loss) if you adjust underlying liquidity.

Risk tips:

* Don’t chase APR alone; check pool TVL trends and token volatility.
* Harvest on a cadence that balances gas cost and reward accrual.
* Diversify across pools to reduce single‑pool dilution risk.

***

### Fees, Gas, and Costs

* All transactions (approve, stake, harvest, withdraw) cost gas paid in `WCO`.
* Keep a small `WCO` balance to avoid failed transactions.
* Liquidity positions on W Swap are subject to **DEX trading fees** and **impermanent loss**; the farm rewards aim to offset these but cannot guarantee profit.

***

### Troubleshooting

* Can’t connect wallet: Ensure your wallet is unlocked and your browser allows wallet connections.
* Wrong network: Switch to **W Chain** in your wallet. The site may prompt you to add/switch networks.
* No LP tokens showing: Confirm you added liquidity to the exact token pair and are on the correct network.
* Approval error: Try increasing the gas or resetting wallet allowance if an earlier approve was rejected.
* Stuck transaction: Speed up or cancel from your wallet; then retry.

***

### FAQs

* **What’s the difference between APR and APY?** APR ignores compounding; APY includes it. If you harvest and restake regularly, your realized return moves toward APY.
* **Which pool should I choose?** Consider multiplier, TVL, token volatility, and your portfolio goals. Higher APR can be short‑lived if dilution increases.
* **Do I need to claim rewards before withdrawing?** No. Withdrawing usually harvests or leaves rewards claimable depending on pool contract behavior. When in doubt, harvest first.
* **Is my principal safe?** Your LP tokens are staked in smart contracts. Smart contract risk, market risk, and impermanent loss still apply.

***

### Useful Links

* WAVE Farm: `https://wave.w-chain.com`
* W Swap (Add Liquidity): `https://app.w-swap.com/#/pool`
* W Chain: `https://w-chain.com`

***

### Best Practices (Quick Checklist)

* Keep `WCO` for gas at all times.
* Approve only the LP tokens you plan to stake.
* Monitor APR and TVL; watch for dilution.
* Harvest on a sensible schedule; consider compounding if it fits your strategy.
* Review token risks and impermanent loss before adding liquidity.

***

### Disclaimer

This guide is for informational purposes only and does not constitute financial advice. Rewards, APR, and prices fluctuate. Always do your own research and manage risk responsibly.


# Block Explorer


# W Scan

W Scan is a self‑hosted Blockscout explorer for W Chain. It runs the latest Blockscout backend (`v8.11`) with a frontend based on `v2` plus custom UI improvements. It supports both W Chain Mainnet and Testnet and includes the full Blockscout feature set.

### Overview

* Networks: `W Chain Mainnet` and `W Chain Testnet`
* Chain IDs: Mainnet `171717`, Testnet `71117`
* Explorer URLs:
  * Mainnet: `https://scan.w-chain.com`
  * Testnet: `https://scan-testnet.w-chain.com`
* Core features: address/transaction/block/token search, decoded input data, internal txs, logs, contract verification, ABI publishing, read/write contract, token pages, labels, and API access.

### Quick Start

1. Open the appropriate URL (Mainnet or Testnet).
2. Use the top search bar to paste an `address`, `transaction hash`, `block number/hash`, or `token contract`.
3. Click results to open detail pages with balances, transfers, logs, decoded calls, and more.
4. Switch networks via the network selector in the header.

### Address Pages

* Summary: shows total balance, token holdings, and recent transactions.
* Tokens: view ERC‑20 balances and transfer history per token.
* Internal txs: inspect value transfers created within contract executions.
* Labels: community or system labels may appear for known contracts.

### Transaction Details

* Overview: status, gas usage, fee, nonce, and timestamps.
* Decoding: function signature and input parameters are decoded when ABI is known.
* Logs: event topics and parameters; filter or expand for details.
* Internal txs: visualize internal calls/value movements during execution.

### Token Pages

* Metadata: name, symbol, decimals, holders, and transfers.
* Holders: ranked list of addresses and their balances.
* Analytics: supply and transfer charts when available.

### Smart Contracts

* Verify: publish source code to enable full decoding and ABI access.
* ABI: once verified, ABI is available to clients and the explorer.
* Read/Write: interact with verified contracts directly from the UI (read state or send transactions).

### Network Switching

* Use the header selector to switch between `Mainnet` and `Testnet`.
* Links and searches remain network‑scoped; ensure you’re on the correct network before sharing URLs.

### API & Exports

* W Scan exposes Blockscout’s standard APIs for indexing and querying chain data.
* For endpoints, authentication options, rate limits, CSV exports, and GraphQL/REST usage, see the official Blockscout documentation at `https://docs.blockscout.com`.

### Troubleshooting

* Data not found: confirm you’re on the right network (Mainnet vs Testnet).
* Undecoded input: verify the contract and publish the ABI to enable decoding.
* Pending tx: network congestion may delay inclusion; retry with appropriate gas settings.
* Indexing lag: recent blocks may take a moment to index; refresh after a short interval.

### FAQs

* Is everything supported? Yes—W Scan includes the full Blockscout feature set for W Chain.
* Can I verify contracts? Yes—publish sources and metadata to enable full decoding and interaction.
* Where do I find developer docs? See `https://docs.blockscout.com` for complete guidance and API references \[Blockscout Docs].


# B2B Address Notification Service

## Coin & Token Transfer Watcher

This document explains how to use the Watched Addresses system to receive real-time webhook notifications for W Chain coin (WCO) transfers and ERC-20 token transfers involving your registered addresses.

The system provides:

* A CRUD API to manage watched addresses and webhook URLs
* Real-time POST webhooks on transfers matching your watch rules
* Automatic retries with exponential backoff on delivery failures

All user-facing addresses and hashes in API responses and webhooks are 0x-prefixed. Internally, addresses are stored lowercase without the 0x prefix.

### Authentication

All endpoints require an API key via the HTTP Authorization header:

* Authorization: Bearer YOUR\_API\_KEY

If the key is valid, the server resolves your watcher\_id and authorizes the request. If invalid or missing, the server returns 401 Unauthorized.

### Base Path

* Base URL:  <https://oracle.w-chain.com/api>

### Address Normalization

* Input (create/update): You may send addresses with or without the 0x prefix. The server normalizes by stripping 0x if present and storing lowercase hex without 0x.
* Output (list/get/update responses and webhooks): All addresses and transaction hashes are 0x-prefixed for consistency with wallets and explorers.

### Endpoints

#### Create a watched address

* Method: `POST`
* Path: `/notifications/watched-addresses`
* Body fields:
  * `address` (string, required): Address with or without 0x; must be 40 hex characters when normalized
  * `watch_coin` (boolean, optional, default `true`): Watch native coin (WCO) transfers
  * `watch_token` (boolean, optional, default `true`): Watch ERC-20 token transfers
  * `webhook_url` (string, required): HTTPS URL to receive webhooks

Example:

```bash
curl -X POST https://oracle.w-chain.com/api/notifications/watched-addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "address": "0xabc1234567890abcdefabc1234567890abcdef0",
        "watch_coin": true,
        "watch_token": true,
        "webhook_url": "https://yourapp.example.com/watched-address-webhook"
      }'
```

Success response (200):

```json
{
  "success": true,
  "data": {
    "id": "...",
    "watcher_id": 123,
    "address": "0xabc1234567890abcdefabc1234567890abcdef0",
    "watch_coin": true,
    "watch_token": true,
    "webhook_url": "https://yourapp.example.com/watched-address-webhook",
    "created_at": "...",
    "updated_at": "..."
  }
}
```

#### List watched addresses

* Method: `GET`
* Path: `/notifications/watched-addresses`

Example:

```bash
curl -X GET https://oracle.w-chain.com/api/notifications/watched-addresses \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success response (200):

```json
{
  "success": true,
  "data": [
    {
      "id": "...",
      "watcher_id": 123,
      "address": "0xabc1234567890abcdefabc1234567890abcdef0",
      "watch_coin": true,
      "watch_token": true,
      "webhook_url": "https://yourapp.example.com/watched-address-webhook",
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}
```

#### Get a watched address by ID

* Method: `GET`
* Path: `/notifications/watched-addresses/:id`

Example:

```bash
curl -X GET https://oracle.w-chain.com/api/notifications/watched-addresses/ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success response (200):

```json
{
  "success": true,
  "data": {
    "id": "...",
    "watcher_id": 123,
    "address": "0xabc1234567890abcdefabc1234567890abcdef0",
    "watch_coin": true,
    "watch_token": true,
    "webhook_url": "https://yourapp.example.com/watched-address-webhook",
    "created_at": "...",
    "updated_at": "..."
  }
}
```

#### Update a watched address

* Method: `PATCH`
* Path: `/notifications/watched-addresses/:id`
* Body: Any subset of the create fields (`address`, `watch_coin`, `watch_token`, `webhook_url`)

Example:

```bash
curl -X PATCH https://oracle.w-chain.com/api/notifications/watched-addresses/ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "watch_token": false }'
```

Success response (200):

```json
{
  "success": true,
  "data": {
    "id": "...",
    "watcher_id": 123,
    "address": "0xabc1234567890abcdefabc1234567890abcdef0",
    "watch_coin": true,
    "watch_token": false,
    "webhook_url": "https://yourapp.example.com/watched-address-webhook",
    "created_at": "...",
    "updated_at": "..."
  }
}
```

#### Delete a watched address

* Method: `DELETE`
* Path: `/notifications/watched-addresses/:id`

Example:

```bash
curl -X DELETE https://oracle.w-chain.com/api/notifications/watched-addresses/ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success response (200):

```json
{ "success": true }
```

### Webhook Delivery

When a transfer involving any of your watched addresses occurs, we send a POST request with JSON to the `webhook_url` configured for that watched address.

* Method: `POST`
* Headers:
  * `Content-Type: application/json`
  * `Authorization: Bearer <api_key>` this is the same API Key used by the Watcher identity, should be used to ensure the authenticity of the webhook request
* Timeout: 10 seconds. If your endpoint does not respond within 10 seconds, it is treated as a failure and retried.

#### Payload fields

These fields are sent in the request body. Values are formatted for user-facing consumption as described.

* `id` (number): Internal notification ID
* `watched_addresses_id` (string, UUID): The watched\_addresses row ID
* `watcher_id` (number): Your watcher ID
* `hash` (string): 0x-prefixed transaction hash
* `type` (string enum): `COIN_TRANSFER` or `TOKEN_TRANSFER`
* `sender` (string): 0x-prefixed sender address
* `receiver` (string): 0x-prefixed receiver address. For contract creations or transactions without a `to`, this may be an empty string.
* `amount` (number | null):
  * COIN\_TRANSFER: Amount is in wei, as a JSON number. Note: very large values may exceed JavaScript’s exact integer range; handle carefully if you require exact arithmetic.
  * TOKEN\_TRANSFER: Raw token units as a JSON number (decimals not applied). Fetch the token’s decimals and normalize on your side if needed.
* `asset` (string):
  * COIN\_TRANSFER: The literal string `WCO`
  * TOKEN\_TRANSFER: 0x-prefixed token contract address
* `timestamp` (string): Timestamp of notification row creation as produced by Postgres (timestamp without time zone). Treat as a textual timestamp; convert/timezone as desired on your side.
* `webhook_url` (string): The target URL (provided for your reference)
* `api_key` (string | null): The API key stored for your watcher, if any (also sent via the Authorization header)
* `next_retry_at` (string | null): Scheduled time for the next retry (if previously failed), else null

Example payload:

```json
{
  "id": 12345,
  "watched_addresses_id": "a1b2c3d4-1111-2222-3333-abcdefabcdef",
  "watcher_id": 678,
  "hash": "0x3fa9e1...c1d2",
  "type": "TOKEN_TRANSFER",
  "sender": "0x1111111111111111111111111111111111111111",
  "receiver": "0x2222222222222222222222222222222222222222",
  "amount": 2500000000000000000,
  "asset": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
  "timestamp": "2025-09-10 08:00:00.000000",
  "webhook_url": "https://yourapp.example.com/watched-address-webhook",
  "api_key": "YOUR_API_KEY_OR_NULL",
  "next_retry_at": null
}
```

### Retry Policy (Exponential Backoff)

If a webhook delivery fails (non-2xx response, timeout, or network error), the system schedules a retry using the following backoff (minutes):

* 1, 3, 10, 15, 60

On the Nth failure, the Nth interval is used; after the 5th failure, retries continue every 60 minutes.

* `retry_count` increments on each failure.
* `next_retry_at` is set to `now + interval`.
* On a successful 2xx response, `processed_at` is set and the notification will not be retried further.

The retry worker selects unprocessed notifications whose `next_retry_at` is due.

### Implementation Notes

* Address formatting
  * Inputs accept with or without 0x; stored lowercase without 0x internally.
  * API responses (create/list/get/update) return addresses with 0x.
  * Webhook payload prefixes `hash`, `sender`, `receiver`, and (for tokens) `asset` with 0x.
* Receiver may be empty string
  * For coin transfers where `to` is null (e.g., contract creation), receiver is emitted as an empty string.
* Amount type
  * Currently sent as a JSON number. If exact precision is required in your system, convert or handle carefully to avoid precision loss in JavaScript environments.
* Asset field
  * `WCO` for native coin transfers; otherwise the token contract address (0x-prefixed) for token transfers.
* Timeouts
  * Webhook POSTs time out in 10 seconds (treated as failure).
* Authorization header on webhook
  * If an API key is present for the watcher, the webhook request to your server includes `Authorization: Bearer <api_key>`.

### Example Receiver (Pseudocode)

```ts
import express from 'express';
const app = express();
app.use(express.json());

app.post('/watched-address-webhook', (req, res) => {
  // Optionally verify Authorization header matches what you expect
  // const auth = req.headers['authorization'];

  const n = req.body; // See payload fields above

  // Handle idempotency if you store notifications (e.g., by `n.id`)

  if (n.type === 'COIN_TRANSFER') {
    // n.asset === 'WCO'
    // n.amount is wei (number); beware precision in JS
  } else if (n.type === 'TOKEN_TRANSFER') {
    // n.asset is token contract address (0x-prefixed)
    // n.amount is raw units; fetch token decimals to normalize
  }

  res.status(200).send('ok');
});

app.listen(3000);
```

### Troubleshooting

* 401 Unauthorized on API calls
  * Ensure `Authorization: Bearer YOUR_API_KEY` is present and valid.
* Webhook not received
  * Confirm your server is reachable over HTTPS and returns 200 within 10 seconds.
  * Check if retries are scheduled by inspecting your logs or querying notifications with `processed_at IS NULL` and `next_retry_at` in the past.
* Amount precision issues
  * The `amount` is sent as a JSON number; for exact arithmetic, convert or handle using big number libraries on your side.

### Change Log

* 2025-09: Added `asset` to notification schema and payload. For coin transfers set to `WCO`; for token transfers set to the token contract address.
* 2025-09: Standardized 0x-prefix formatting in API responses and webhook payloads (hash, sender, receiver, token asset).


# WCO Supply Information API

### Overview

The WCO Supply Information API provides real-time data about the WCO token supply distribution, including circulating supply, locked supply, and burned tokens. This endpoint is essential for understanding the tokenomics and current state of WCO tokens in circulation.

### Endpoint Details

**URL:** `https://oracle.w-chain.com/api/wco/supply-info`\
**Method:** `GET`\
**Cache:** 2 minutes TTL\
**Authentication:** None required

### Response Structure

The API returns a comprehensive JSON response with the following structure:

```json
{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "cache": {
    "ttl_seconds": 120,
    "note": "This endpoint is cached for 2 minutes"
  },
  "summary": {
    "initial_supply_wco": "1000000000",
    "locked_supply_wco": "250000000.123456789",
    "burned_supply_wco": "5000000.987654321",
    "circulating_supply_wco": "744999999.888888890"
  },
  "raw": {
    "units": {
      "native": "WCO",
      "base": "wei",
      "wei_per_wco": "1000000000000000000"
    },
    "initial_supply_wei": "1000000000000000000000000000",
    "locked_supply_wei": "250000000123456789000000000",
    "burned_supply_wei": "5000000987654321000000000",
    "circulating_supply_wei": "744999999888888890000000000",
    "locked_supply_breakdown": [
      {
        "address": "0x1234...",
        "label": "validators-staking",
        "balance_wei": "200000000000000000000000000",
        "balance_wco": "200000000.0"
      },
      {
        "address": "0x5678...",
        "label": "vesting:team",
        "balance_wei": "50000000123456789000000000",
        "balance_wco": "50000000.123456789"
      }
    ],
    "burned_supply_breakdown": {
      "address": "0x0000000000000000000000000000000000000000",
      "label": "evm-zero-address",
      "balance_wei": "5000000987654321000000000",
      "balance_wco": "5000000.987654321"
    }
  },
  "methodology": {
    "formula": "circulating = initial_genesis_supply - (sum of locked addresses balances) - burned_balance",
    "data_sources": {
      "rpc_provider": "WCHAIN_RPC_PROVIDER",
      "multicall3_contract": "aggregate3 + getEthBalance"
    },
    "address_labels": {
      "validators_staking": "0x1234...",
      "vesting_contracts": {
        "team": "0x5678...",
        "advisors": "0x9abc..."
      },
      "burn_address": "0x0000000000000000000000000000000000000000"
    },
    "verification": {
      "how_to_verify": "Query each address balance on-chain or via any RPC, and confirm calculations match the formula."
    }
  }
}
```

### Understanding the Response

#### Summary Section

The `summary` section provides human-readable WCO token amounts:

* **`initial_supply_wco`**: The total initial supply of WCO tokens at genesis
* **`locked_supply_wco`**: Total tokens locked in various contracts (staking, vesting, etc.)
* **`burned_supply_wco`**: Total tokens sent to the burn address (0x0000...)
* **`circulating_supply_wco`**: Tokens available for trading and transactions

#### Raw Data Section

The `raw` section contains precise wei-denominated values and detailed breakdowns:

* **`units`**: Explains the denomination system (1 WCO = 10^18 wei)
* **`*_supply_wei`**: Exact token amounts in wei (smallest unit)
* **`locked_supply_breakdown`**: Individual balances of each locked address
* **`burned_supply_breakdown`**: Details of tokens sent to burn address

#### Methodology Section

Provides transparency about data collection and calculation methods:

* **`formula`**: Mathematical formula used for circulating supply calculation
* **`data_sources`**: Technical details about data retrieval methods
* **`address_labels`**: Human-readable labels for contract addresses
* **`verification`**: Instructions for independently verifying the data

### Calculation Methodology

#### Circulating Supply Formula

```
Circulating Supply = Initial Supply - Locked Supply - Burned Supply
```

#### Locked Supply Categories

1. **Validators Staking Contract**: Tokens staked by validators for network security
2. **Vesting Contracts**: Tokens allocated to team, advisors, and other stakeholders with time-based release schedules

#### Data Collection Process

1. **Multicall3 Integration**: Uses efficient batch calls to query multiple address balances simultaneously
2. **Real-time Queries**: Balances are fetched directly from the W-Chain RPC provider
3. **Precision Handling**: All calculations use BigInt to maintain precision with large numbers
4. **Error Handling**: Implements safeguards against negative circulating supply due to chain anomalies

### Use Cases

#### For Developers

* **DeFi Integration**: Use circulating supply data for market cap calculations
* **Analytics Dashboards**: Display real-time tokenomics information
* **Trading Applications**: Incorporate supply metrics into trading algorithms

#### For Researchers

* **Tokenomics Analysis**: Study token distribution and unlock schedules
* **Market Research**: Analyze supply dynamics and their market impact
* **Verification**: Independently verify supply calculations using provided methodology

#### For Exchanges

* **Market Data**: Provide accurate circulating supply for market cap calculations
* **Compliance**: Maintain transparency about token supply for regulatory purposes

### Data Freshness and Caching

* **Cache Duration**: 2 minutes (120 seconds)
* **Update Frequency**: Data refreshes automatically every 2 minutes
* **Real-time Accuracy**: Balances reflect the most recent blockchain state within cache window

### Verification Guide

To independently verify the supply data:

1. **Query Individual Addresses**: Use any W-Chain RPC endpoint to query balances of addresses listed in `methodology.address_labels`
2. **Sum Locked Balances**: Add up all balances from validators staking and vesting contracts
3. **Query Burn Address**: Check balance of `0x0000000000000000000000000000000000000000`
4. **Apply Formula**: Subtract locked and burned amounts from initial supply
5. **Compare Results**: Your calculation should match the API response

### Error Handling

The API implements robust error handling:

* **Network Issues**: Automatic retries for RPC calls
* **Invalid Responses**: Graceful handling of malformed blockchain responses
* **Negative Supply Protection**: Clamps circulating supply to zero if calculation results in negative value

### Rate Limiting

No explicit rate limiting is applied, but the 2-minute cache reduces the load on underlying blockchain infrastructure. For high-frequency applications, respect the cache TTL to optimize performance.

### Support

For technical support or questions about this API:

* Check the verification methodology to ensure correct interpretation
* Review the raw data section for precise calculations
* Consult the W-Chain documentation for blockchain-specific details


# WPoints Public API

### Overview

The Points API provides comprehensive access to user points data within the W-Chain ecosystem. These endpoints allow you to retrieve points information for individual users, leaderboards, and comparative analytics across different time periods and categories.

### Base URL

`https://oracle.w-chain.com/api/points`

### Authentication

All Points API endpoints are publicly accessible and do not require authentication.

### Common Parameters

#### Month Format

When specifying months in API calls, use the format: `YYYY-MM`

* Example: `2024-01` for January 2024
* Example: `2024-12` for December 2024

#### User Parameter

User addresses should be provided as Ethereum-compatible addresses (0x prefixed hex strings).

***

### Endpoints

#### 1. Monthly Leaderboard

**Endpoint:** `GET /leaderboard`\
**Cache:** 5 minutes\
**Description:** Retrieves the points leaderboard for a specific month, showing all users ranked by their total points.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/leaderboard?month=2024-01
```

**Example Response**

```json
[
  {
    "user": "0x1234567890123456789012345678901234567890",
    "points": 15750
  },
  {
    "user": "0x0987654321098765432109876543210987654321",
    "points": 12300
  },
  {
    "user": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "points": 8900
  }
]
```

**Response Fields**

* `user`: Ethereum address of the user
* `points`: Total points earned by the user in the specified month

**Notes**

* Results are automatically sorted by points in descending order (highest first)
* Only includes users who earned points during the specified month

***

#### 2. User Points Details

**Endpoint:** `GET /user`\
**Cache:** 5 minutes\
**Description:** Retrieves detailed points information for a specific user in a given month, including individual point entries with categories and transaction hashes.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user?month=2024-01&user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
[
  {
    "category": "trading",
    "points": 500,
    "created_at": "2024-01-15T14:30:00.000Z",
    "hash": "0xabc123def456789..."
  },
  {
    "category": "staking",
    "points": 250,
    "created_at": "2024-01-14T09:15:00.000Z",
    "hash": "0xdef789abc123456..."
  },
  {
    "category": "liquidity_provision",
    "points": 1000,
    "created_at": "2024-01-13T16:45:00.000Z",
    "hash": "0x123456789abcdef..."
  }
]
```

**Response Fields**

* `category`: The category/type of activity that earned the points
* `points`: Number of points earned for this specific activity
* `created_at`: ISO timestamp when the points were awarded
* `hash`: Transaction hash associated with the point-earning activity

**Notes**

* Results are ordered by creation date (most recent first)
* Provides granular view of all point-earning activities

***

#### 3. User Points by Category

**Endpoint:** `GET /user-by-category`\
**Cache:** 30 seconds\
**Description:** Retrieves aggregated points for a specific user grouped by category for a given month.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user-by-category?month=2024-01&user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
[
  {
    "category": "trading",
    "points": 5500
  },
  {
    "category": "liquidity_provision",
    "points": 3200
  },
  {
    "category": "staking",
    "points": 1800
  },
  {
    "category": "referral",
    "points": 750
  }
]
```

**Response Fields**

* `category`: The category/type of activity
* `points`: Total points earned in this category for the specified month

**Notes**

* Results are sorted by points in descending order (highest category first)
* Provides a summary view of user's point distribution across activities

***

#### 4. Current Month User Points

**Endpoint:** `GET /user-by-current-month`\
**Cache:** 1 minute\
**Description:** Retrieves the total points for a specific user in the current month.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user-by-current-month?user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
{
  "points": 8750
}
```

**Response Fields**

* `points`: Total points earned by the user in the current month

**Notes**

* Automatically uses the current month (no month parameter needed)
* Useful for real-time dashboards and current progress tracking

***

#### 5. Points Comparison vs Last Month

**Endpoint:** `GET /vs-last-month`\
**Cache:** 1 minute\
**Description:** Compares a user's points between the current period and the corresponding period in the previous month, with intelligent date range handling.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/vs-last-month?user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
{
  "current": {
    "points": 8750,
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-19T23:59:59.999Z"
    }
  },
  "lastMonth": {
    "points": 6200,
    "period": {
      "start": "2023-12-01T00:00:00.000Z",
      "end": "2023-12-19T23:59:59.999Z"
    }
  },
  "comparison": {
    "difference": 2550,
    "percentageChange": 41.13,
    "isFullMonthComparison": false
  }
}
```

**Response Fields**

**Current Period:**

* `current.points`: Points earned in the current period
* `current.period.start`: Start date of current comparison period
* `current.period.end`: End date of current comparison period

**Last Month Period:**

* `lastMonth.points`: Points earned in the corresponding previous period
* `lastMonth.period.start`: Start date of previous comparison period
* `lastMonth.period.end`: End date of previous comparison period

**Comparison Analytics:**

* `comparison.difference`: Absolute difference in points (current - last month)
* `comparison.percentageChange`: Percentage change from last month (rounded to 2 decimal places)
* `comparison.isFullMonthComparison`: Boolean indicating if comparing full months or partial periods

**Intelligent Date Range Logic**

The endpoint uses smart date range comparison:

1. **Late in Month (Day >= 28)**: Compares full months
   * Current: Full current month
   * Previous: Full previous month
2. **Early/Mid Month (Day < 28)**: Compares equivalent date ranges
   * Current: Month start to current date
   * Previous: Same date range in previous month
   * Example: If today is Jan 19, compares Jan 1-19 vs Dec 1-19

**Use Cases**

* **Progress Tracking**: Monitor user engagement trends
* **Gamification**: Show improvement or decline in user activity
* **Analytics**: Understand user behavior patterns over time

***

### Error Handling

All endpoints return appropriate HTTP status codes and error messages:

#### 400 Bad Request

Returned when required parameters are missing or invalid.

```json
{
  "statusCode": 400,
  "statusMessage": "Missing month parameter"
}
```

#### 404 Not Found

Returned when no points data is found for the specified criteria.

```json
{
  "statusCode": 404,
  "statusMessage": "Points not found"
}
```

### Caching Strategy

Each endpoint implements intelligent caching to balance data freshness with performance:

| Endpoint                 | Cache Duration | Reasoning                                     |
| ------------------------ | -------------- | --------------------------------------------- |
| `/leaderboard`           | 5 minutes      | Leaderboard changes relatively slowly         |
| `/user`                  | 5 minutes      | Detailed history is relatively stable         |
| `/user-by-category`      | 30 seconds     | Category summaries may update more frequently |
| `/user-by-current-month` | 1 minute       | Current month data changes more frequently    |
| `/vs-last-month`         | 1 minute       | Comparison data needs to be relatively fresh  |

### Rate Limiting

No explicit rate limiting is enforced, but clients should respect the cache durations to optimize performance and reduce server load.

### Data Categories

Common point categories include:

* `trading`: Points earned from trading activities
* `staking`: Points from staking WCO tokens
* `liquidity_provision`: Points from providing liquidity to pools
* `referral`: Points from referring new users
* `governance`: Points from participating in governance
* `bridge`: Points from using cross-chain bridge functionality

### Best Practices

#### For Developers

1. **Cache Awareness**: Respect cache durations in your application logic
2. **Error Handling**: Implement proper error handling for 400/404 responses
3. **Date Formatting**: Always use YYYY-MM format for month parameters
4. **Address Validation**: Validate Ethereum addresses before making API calls

#### For Analytics

1. **Trend Analysis**: Use `/vs-last-month` for growth tracking
2. **Category Insights**: Use `/user-by-category` to understand user behavior
3. **Leaderboard Tracking**: Monitor `/leaderboard` for competitive analysis

#### For User Interfaces

1. **Real-time Updates**: Use `/user-by-current-month` for live progress displays
2. **Historical Data**: Use `/user` for detailed activity timelines
3. **Comparative Views**: Use `/vs-last-month` for progress indicators

### Support

For technical support or questions about the Points API:

* Verify parameter formats match the documentation
* Check error messages for specific guidance
* Ensure user addresses are valid Ethereum addresses
* Consult the caching information for data freshness expectations


# Public Price API

### Overview

The W-Chain Price API provides real-time price data for tokens within the W-Chain ecosystem. Currently supporting WCO and WAVE tokens, this API delivers USD-denominated prices with caching for optimal performance. Future token additions will follow the same endpoint structure and response format.

### Base URL

`https://oracle.w-chain.com/api/price`

### Authentication

All Price API endpoints are publicly accessible and do not require authentication.

### Common Response Format

All price endpoints return a consistent JSON structure:

```json
{
  "price": 1.2345,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}
```

#### Response Fields

* `price`: Current price of the asset in USD (number)
* `asset`: Token symbol/identifier (string)
* `base_currency`: Always "USD" for price denomination (string)

***

### Supported Tokens

#### 1. WCO Token Price

**Endpoint:** `GET /wco`\
**Cache:** 1 minute\
**Description:** Retrieves the current USD price of WCO token from the latest price feed data.

**Example Request**

```
GET https://oracle.w-chain.com/api/price/wco
```

**Example Response**

```json
{
  "price": 0.0234,
  "asset": "WCO",
  "base_currency": "USD"
}
```

**Data Source**

* **Source**: Internal price feed database (`price_feed_wco` table)
* **Update Frequency**: Real-time price feed updates
* **Precision**: Full decimal precision as stored in database
* **Fallback**: Returns `null` if no price data available

**Technical Implementation**

* Queries the most recent price entry from `price_feed_wco` table
* Implements 60-second caching to reduce database load
* Orders by timestamp descending to get latest price
* Handles database errors gracefully

***

#### 2. WAVE Token Price

**Endpoint:** `GET /wave`\
**Cache:** Inherits from WCO cache (1 minute)\
**Description:** Retrieves the current USD price of WAVE token, calculated using WCO price and WAVE/WCO trading pair data.

**Example Request**

```
GET https://oracle.w-chain.com/api/price/wave
```

**Example Response**

```json
{
  "price": 1.4567,
  "asset": "WAVE",
  "base_currency": "USD"
}
```

**Price Calculation**

WAVE USD price is calculated using the formula:

```
WAVE_USD_Price = WAVE_WCO_Rate × WCO_USD_Price
```

Where:

* `WAVE_WCO_Rate`: Latest trading pair price from pair ID 1
* `WCO_USD_Price`: Current WCO price from `/api/price/wco`

**Data Sources**

* **Primary**: Trading pair data (pair ID: 1) for WAVE/WCO rate
* **Secondary**: WCO USD price from internal price feed
* **Dependencies**: Requires both WCO price and trading pair data

**Technical Implementation**

* Makes internal API call to `/api/price/wco` for WCO price
* Fetches latest WAVE/WCO pair price using `getLatestPairPricesById(1)`
* Multiplies pair rate by WCO USD price for final WAVE USD price
* Inherits caching behavior from WCO endpoint

***

### Future Token Support

Additional tokens will be added following the same patterns:

#### Endpoint Structure

```
GET /api/price/{token_symbol}
```

#### Response Format

All future tokens will maintain the same response structure:

```json
{
  "price": number,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}
```

#### Implementation Patterns

New tokens will follow one of these implementation patterns:

1. **Direct Price Feed** (like WCO):
   * Dedicated price feed table
   * Direct USD pricing
   * Simple database query
2. **Calculated Price** (like WAVE):
   * Based on trading pair data
   * Calculated against base token (typically WCO)
   * Derived USD pricing

***

### Error Handling

#### Database Errors

When price data cannot be retrieved:

```json
{
  "price": null,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}
```

#### Missing Dependencies

For calculated prices (like WAVE), if dependencies are unavailable:

* Returns appropriate error response
* Logs error details for debugging
* Maintains API consistency

### Caching Strategy

#### WCO Token

* **Cache Key**: `api_price_wco`
* **TTL**: 60 seconds
* **Strategy**: Database query caching
* **Invalidation**: Time-based expiration

#### WAVE Token

* **Cache Dependency**: Inherits from WCO caching
* **Additional Caching**: Trading pair data may have separate caching
* **Effective TTL**: Minimum of dependent cache TTLs

#### Benefits

* Reduces database load
* Improves response times
* Maintains data freshness
* Handles high-frequency requests efficiently

### Rate Limiting

No explicit rate limiting is enforced, but the caching mechanism naturally throttles database queries. Clients should:

* Respect cache durations
* Avoid excessive polling
* Implement client-side caching for frequently accessed data

### Use Cases

#### For DeFi Applications

* **Portfolio Valuation**: Calculate total portfolio value in USD
* **Trading Interfaces**: Display current market prices
* **Yield Farming**: Calculate APY and rewards in USD terms
* **Liquidity Pools**: Price LP tokens and calculate impermanent loss

#### For Analytics Platforms

* **Market Data**: Real-time price tracking and charts
* **Market Cap Calculations**: Combine with supply data for market cap
* **Price Alerts**: Trigger notifications on price movements
* **Historical Analysis**: Track price trends over time

#### For Wallets and Exchanges

* **Balance Display**: Show USD values of token holdings
* **Trading Pairs**: Price discovery for trading interfaces
* **Order Books**: Reference pricing for limit orders
* **Fee Calculations**: Calculate transaction fees in USD

### Data Freshness

#### WCO Price Updates

* **Source**: Real-time price feed system
* **Frequency**: Continuous updates based on market activity
* **Latency**: Sub-minute from price feed to API (with caching)

#### WAVE Price Updates

* **Source**: Trading pair activity on W-Chain DEX
* **Frequency**: Updates with each trade in WAVE/WCO pair
* **Latency**: Depends on WCO price freshness + pair data updates

### Best Practices

#### For Developers

1. **Handle Null Prices**: Always check for `null` price values
2. **Implement Fallbacks**: Have backup pricing sources when possible
3. **Cache Appropriately**: Respect API cache durations in your application
4. **Error Handling**: Implement robust error handling for network issues

#### For High-Frequency Applications

1. **Batch Requests**: Group multiple price requests when possible
2. **WebSocket Alternative**: Consider WebSocket connections for real-time updates
3. **Local Caching**: Implement application-level caching
4. **Rate Management**: Avoid overwhelming the API with requests

#### For Financial Applications

1. **Precision Handling**: Use appropriate decimal precision for financial calculations
2. **Timestamp Tracking**: Track when prices were last updated
3. **Audit Trails**: Log price data usage for compliance
4. **Backup Systems**: Implement redundant price sources

### Integration Examples

#### JavaScript/TypeScript

```javascript
// Fetch single token price
async function getTokenPrice(symbol) {
  try {
    const response = await fetch(`https://oracle.w-chain.com/api/price/${symbol.toLowerCase()}`);
    const data = await response.json();
    return data.price;
  } catch (error) {
    console.error(`Error fetching ${symbol} price:`, error);
    return null;
  }
}

// Fetch multiple token prices
async function getPortfolioValue(holdings) {
  const prices = await Promise.all([
    fetch('https://oracle.w-chain.com/api/price/wco').then(r => r.json()),
    fetch('https://oracle.w-chain.com/api/price/wave').then(r => r.json())
  ]);
  
  let totalValue = 0;
  holdings.forEach(holding => {
    const price = prices.find(p => p.asset === holding.symbol)?.price || 0;
    totalValue += holding.amount * price;
  });
  
  return totalValue;
}
```

#### Python

```python
import requests
import asyncio
import aiohttp

def get_token_price(symbol):
    """Fetch token price synchronously"""
    try:
        response = requests.get(f'https://oracle.w-chain.com/api/price/{symbol.lower()}')
        response.raise_for_status()
        return response.json()['price']
    except requests.RequestException as e:
        print(f"Error fetching {symbol} price: {e}")
        return None

async def get_multiple_prices(symbols):
    """Fetch multiple token prices asynchronously"""
    async with aiohttp.ClientSession() as session:
        tasks = []
        for symbol in symbols:
            url = f'https://oracle.w-chain.com/api/price/{symbol.lower()}'
            tasks.append(session.get(url))
        
        responses = await asyncio.gather(*tasks)
        prices = {}
        
        for response, symbol in zip(responses, symbols):
            if response.status == 200:
                data = await response.json()
                prices[symbol] = data['price']
            else:
                prices[symbol] = None
        
        return prices
```

### Monitoring and Observability

#### Health Checks

* Monitor API response times
* Track cache hit/miss ratios
* Alert on price data staleness
* Monitor database connectivity

#### Key Metrics

* **Response Time**: API endpoint latency
* **Cache Efficiency**: Cache hit percentage
* **Data Freshness**: Time since last price update
* **Error Rate**: Failed requests percentage
* **Dependency Health**: WCO price availability for WAVE calculations

### Support and Troubleshooting

#### Common Issues

1. **Null Prices**: Check if price feed is active and database is accessible
2. **Stale Data**: Verify cache TTL settings and price feed updates
3. **WAVE Price Errors**: Ensure both WCO price and trading pair data are available
4. **High Latency**: Check database performance and network connectivity

#### Getting Help

* Verify endpoint URLs and request format
* Check for network connectivity issues
* Review error messages in API responses
* Monitor W-Chain network status for underlying issues

***

*This API documentation covers the current implementation of WCO and WAVE price endpoints. As new tokens are added to the W-Chain ecosystem, they will follow similar patterns and be documented with the same level of detail.*


# W Swap Trade Volume API

This document describes the W Swap Trade Volume API endpoint that returns the last 24 hours of traded volume (in USD) for a specific trading pair.

### Endpoint

* Method: `GET`
* URL: `https://oracle.w-chain.com/api/w-swap/volume/:id`

### Purpose

* Returns the 24-hour aggregated USD volume for the specified trading pair.
* Also returns the pair name for convenience.

### Request

* Path parameter `id` (number): The `trade_pairs.id` of the pair.

#### Example

```
GET https://oracle.w-chain.com/api/w-swap/volume/2
```

### Success Response

* Status: `200 OK`
* Body:

```json
{
  "vol24h": 12345.67,
  "pair": "USDT/WCO"
}
```

#### Field Details

* `vol24h` (number): Total swap volume in USD over the past 24 hours.
* `pair` (string): The human-readable pair name from `trade_pairs.name`.

### Error Responses

* `400 Bad Request`: Missing `id` path parameter.

```json
{
  "statusCode": 400,
  "statusMessage": "Missing id parameter"
}
```

* `404 Not Found`: Pair not found (no matching `trade_pairs.id`).

```json
{
  "statusCode": 404,
  "statusMessage": "Pair not found"
}
```

### How Volume Is Calculated

* Source table: `trade_pair_swap_events`.
* Aggregation: Sum of `usd_value` for rows where:
  * `pair_id` equals the requested `id`.
  * `timestamp` is within the last 24 hours (`gt now - 24h` and `lte now`).
* USD valuation:
  * Stablecoins (`USDT`, `USDC`, and bridged variants) use a 1:1 USD mapping.
  * `WCO` is valued using its CoinGecko USD price.
  * Other tokens may currently resolve to `0` USD unless specifically supported.
* Caching: Results are cached for \~60 seconds to reduce load.

### `trade_pairs` Reference

The following pairs (from `trade_pairs`) are relevant for W Swap operations and USD valuation logic. The `usd_value_from` column indicates which token is used to determine USD value during swaps: `0` means `token0`, `1` means `token1`.

| id | name     | platform | pair\_address                              | token0\_address                            | token1\_address                            | token0\_decimals | token1\_decimals | fee | usd\_value\_from | wave\_pid |
| -- | -------- | -------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ---------------- | ---------------- | --- | ---------------- | --------- |
| 1  | WAVE/WCO | 0        | 0x35264f0e8cd7a32341f47dbfbf2d85b81fd0ef0a | 0x42abfb13b4e3d25407ffa9705146b7cb812404a0 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 0         |
| 2  | USDT/WCO | 0        | 0xd4e9176d5189dbb24f40e5c6c45bb1682dcb3324 | 0x40cb2cccf80ed2192b53fb09720405f6fe349743 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 6                | 18               | 300 | 0                | 1         |
| 3  | USDC/WCO | 0        | 0x00d91ce419c068e36928fd8e9379b11d0011f052 | 0x643ec74ed2b79098a37dc45dcc7f1abfe2ade6d8 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 6                | 18               | 300 | 0                | 2         |
| 4  | SOL/WCO  | 0        | 0x9556d7afa868cb8b25657d34f3e0d46929f9d710 | 0xd4f93cacd6d607789c8ecf1dddeba8b0c4d915a8 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 4         |
| 5  | DOGE/WCO | 0        | 0x8b5f11ea77641b208fb53b4b91b2825db64b8c32 | 0x6cdfda79787caa4ad1a95456095bedc95abd2d75 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 8                | 18               | 300 | 1                | 5         |
| 6  | XRP/WCO  | 0        | 0x24f07de79398f24c9d4dd60a281a29843e43b7fd | 0x4560d5eb0c32a05fa59acd2e8d639f84a15a2414 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 6         |

#### Note on `wave_pid`

The `wave_pid` sequence skips `3` because in Wave Farm, pool ID `3` is a `WCO` Single Stake pool (not an LP pool). Therefore, LP-related pairs continue with `4`, `5`, `6`, etc.

### Usage Examples

#### cURL

```bash
curl -s "http://<host>/api/w-swap/volume/2"
```

#### JavaScript (fetch)

```js
// Fetch 24h volume for pair id 2 (USDT/WCO)
const resp = await fetch('/api/w-swap/volume/2');
if (!resp.ok) throw new Error('Request failed');
const data = await resp.json();
// data.vol24h is a number in USD; data.pair is the pair name
```

### Implementation Notes

* Internals use a 60-second cache to avoid excessive DB queries.
* If there are no swap events in the last 24h for the given pair, `vol24h` returns `0`.
* Authentication is not required for this public endpoint.

### Related Endpoints

* `GET /api/w-swap/lp-value/:id` — returns latest pair price and LP price (in USD).


# W Swap LP Price API

This document describes the W Swap LP Value API endpoint that returns the latest token price and LP (Liquidity Provider) token price in USD for a specific trading pair.

### Endpoint

* Method: `GET`
* Path: `/api/w-swap/lp-value/:id`

### Purpose

* Returns the latest price of the pair.
* Returns the estimated USD value of one LP token for the pair.
* Also returns the pair name for convenience.

### Request

* Path parameter `id` (number): The `trade_pairs.id` of the pair.

#### Example

```
GET /api/w-swap/lp-value/2
```

### Success Response

* Status: `200 OK`
* Body:

```json
{
  "latestPrice": 1.2345,
  "lpPriceInUsd": 0.5678,
  "pair": "USDT/WCO"
}
```

#### Field Details

* `latestPrice` (number): The latest exchange rate of the pair (token1 per token0 or vice versa depending on pair configuration).
* `lpPriceInUsd` (number): The estimated value of 1 LP token in USD.
* `pair` (string): The human-readable pair name from `trade_pairs.name`.

### Error Responses

* `400 Bad Request`: Missing `id` path parameter.

```json
{
  "statusCode": 400,
  "statusMessage": "Missing id parameter"
}
```

* `404 Not Found`: Price or pair not found (no matching `trade_pairs.id` or missing price data).

```json
{
  "statusCode": 404,
  "statusMessage": "Price not found"
}
```

### Supported Trade Pairs

The following trade pairs are supported by this API. Use the corresponding `ID` in the request URL.

| ID | Pair Name |
| -- | --------- |
| 1  | WAVE/WCO  |
| 2  | USDT/WCO  |
| 3  | USDC/WCO  |
| 4  | SOL/WCO   |
| 5  | DOGE/WCO  |
| 6  | XRP/WCO   |

### Implementation Notes

* The endpoint fetches the latest price and pair name in a single query for efficiency.
* Results are cached for 60 seconds (`maxAge: 60`, `swr: true`) to reduce database load and improve response times.
* Authentication is not required for this public endpoint.

### Related Endpoints

* `GET /api/w-swap/volume/:id` — returns the last 24 hours of traded volume (in USD).


# Web3 Wallet Setup

As a full pledged EVM compatible network, you can interact with W Chain Network using all popular Web3 Wallet app. (i.e. Rabby, Metamask, Rainbow, Phantom, etc).

Add the following Network Information to your Wallet App. Depends on your app choice, it may fall under "Add Custom Network" section.

{% tabs %}
{% tab title="Mainnet" %}

* Network name: **W Chain**
* RPC URL: <https://rpc.w-chain.com>
* ChainID: **171717**
* Currency Symbol: **WCO**
* Decimal&#x73;**: 18** (if asked)
* Block explorer URL: <https://scan.w-chain.com>
  {% endtab %}

{% tab title="Testnet" %}

* Network name: **W Chain Testnet**
* RPC URL: <https://rpc-testnet.w-chain.com>
* ChainID: **71117**
* Currency Symbol: **WCO**
* Block explorer URL: <https://scan-testnet.w-chain.com>
  {% endtab %}
  {% endtabs %}


# Smart contract

W Chain utilizes the Ethereum Virtual Machine (EVM) in the backend. Smart contracts are written in Solidity and they can function on W Chain as they do on Ethereum. To deploy a smart contract, you send a transaction containing your bytecode without specifying any recipients. After the contract is deployed, it will be available to all users of the W Chain network.&#x20;

You don't have to write and deploy your smart contract manually like that, there many tools or frameworks that will help you write, test and deploy your smart contracts in better ways.

### Foundry

Foundry is an open-source, modern development framework designed for writing, testing, and deploying Solidity smart contracts for Ethereum and other EVM-compatible blockchains. Written in Rust, it offers a fast, efficient, and developer-friendly environment with tools like Forge for compiling, testing, and deploying contracts, Cast for interacting with the blockchain via the command line, and Anvil for running a local Ethereum node for testing.&#x20;

Foundry emphasizes simplicity, speed, and modularity, allowing developers to write robust tests in Solidity, debug contracts easily, and integrate with existing Ethereum tools. Its focus on a test-driven development approach and seamless integration with Git makes it a popular choice for building secure and scalable decentralized applications.

We recommend Foundry, as it natively use Solidity in its scripting, testing and deploying functionalities. You will never need to switch between different programming languages, use Solidity everywhere!

Here is the recommended settings for your <mark style="color:yellow;">`foundry.toml`</mark>:

```toml
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = '0.8.19'
optimizer = true
optimizer_runs = 10_000

[etherscan]
wchain = { key = "verifyContract", chain = 171717, url = 'https://scan.w-chain.com/api' }
wchain-test = { key = "verifyContract", chain = 71117, url = 'https://scan-testnet.w-chain.com/api' }

[rpc_endpoints]
wchain = "https://rpc.w-chain.com"
wchain-test = "https://rpc-testnet.w-chain.com"
```

Using this settings, you will be able to use the RPC in your CLI commands. Here are some examples:

```bash
cast send 0x6807dc923806fE8Fd134338EABCA509979a7e0cB --value 1ether --rpc-url wchain --private-key $PRIVATE_KEY
```

```bash
cast balance 0x6807dc923806fE8Fd134338EABCA509979a7e0cB --rpc-url wchain
```

```
forge create src/SomeContract.sol:MyContract --rpc-url wchain --verify --chain 171717 --private-key $PRIVATE_KEY
```

### Hardhat

Hardhat is an open-source, flexible, and extensible development environment for writing, compiling, testing, and deploying Solidity smart contracts for Ethereum and EVM-compatible blockchains. Built with JavaScript and Node.js, it provides a robust framework for developers to create, debug, and deploy smart contracts efficiently.&#x20;

Key features include the Hardhat Network for local blockchain testing, a powerful task runner for automating workflows, and support for plugins to extend functionality. Hardhat’s intuitive API, detailed error reporting, and integration with tools like TypeScript and Ethers.js make it ideal for both beginners and experienced developers building secure, scalable decentralized applications.

Compared to Foundry, Hardhat will require you to switch contexts between Solidity and Javascript/TypeScript. This benefits developers with good Javascript background as it will use familiar testing modules, and share same contexts with Ethers JS, building early connection to UI/Frontend side of the dApp.

Here is a settings you can start from:

```javascript
module.exports = {
  networks: {
    w_chain_testnet: {
      url: "https://rpc-testnet.w-chain.com",
      accounts: [process.env.PRIVATE_KEY],
    },
    w_chain: {
      url: "https://rpc.w-chain.com",
      accounts: [process.env.PRIVATE_KEY],
    }
  },
  etherscan: {
    apiKey: "free-key",
    customChains: [
      {
        network: "W Chain Testnet",
        chainId: 71117,
        urls: {
          apiURL: "https://scan-testnet.w-chain.com/api",
          browserURL: "https://scan-testnet.w-chain.com"
        }
      },
      {
        network: "W Chain",
        chainId: 171717,
        urls: {
          apiURL: "https://scan.w-chain.com/api",
          browserURL: "https://scan.w-chain.com"
        }
      }
    ]
  }
};
```

&#x20;

### Verifying Smart Contract

We recommend you to use Foundry or Hardhat to build, deploy and to verify the source code on W Chain Block Explorer. If there's any situation you want to manually verify a smart contract, you can send the POST request to W Chain Block Explorer's API. Here's an example:

```bash
curl --location 'https://scan.w-chain.com/api?module=contract&action=verifysourcecode' \
--form 'contractaddress="0xYourContractAddress"' \
--form 'sourceCode="// SPDX-License-Identifier: GPL-3.0 pragma solidity ^0.8.17; contract Storage { uint256 number; function store(uint256 num) public { number = num; } function retrieve() public view returns (uint256){ return number; } }"' \
--form 'contractname="Storage"' \
--form 'codeformat="solidity-single-file"' \
--form 'compilerversion="v0.8.17+commit.8df45f5f"' \
--form 'optimizationUsed="1"' \
--form 'runs="200"' \
--form 'constructorArguements=""' \
--form 'evmversion="london"' \
--form 'licenseType="3"'
```

{% hint style="warning" %}
It's very important to ensure the exact code format, source code, compiler version, constructor arguments (if any), optimizations configs and EVM version.
{% endhint %}


# Audit Reports

<table><thead><tr><th>Audit Category</th><th data-type="files">Audit Files</th></tr></thead><tbody><tr><td>W Chain L1 Blockchain Audit Report</td><td><a href="/files/p0OpINtKLxFBTHXJXa5U">/files/p0OpINtKLxFBTHXJXa5U</a></td></tr><tr><td>W Coin Migration Portal Audit Report</td><td><a href="/files/cFB7NQZAhAHDWJWD7YqH">/files/cFB7NQZAhAHDWJWD7YqH</a></td></tr></tbody></table>