Developers Forum for XinFin XDC Network: JukLee0ira

How to Setup monitor tool

JukLee0ira — Thu, 20 Mar 2025 03:50:32 +0000

This monitoring tool provides a visual display of various performance metrics for node runtime, helping you understand node performance, debug, tune, and gain insight into actual Node runtime.

Here's how to deploy the monitoring tool:

Installing InfluxDB 1.8 and Grafana on Linux System

1. Update the System

Before starting the installation, first update the package manager of the system:

sudo apt update && sudo apt upgrade -y

2. Download and Install InfluxDB 1.8

Go to the InfluxData official repository and download the suitable version of InfluxDB 1.8 for your system. For Debian/Ubuntu systems, you can use the following commands:

wget https://dl.influxdata.com/influxdb/releases/influxdb_1.8.10_amd64.deb
sudo dpkg -i influxdb_1.8.10_amd64.deb

Start InfluxDB

Start the InfluxDB service and set it to start on boot:

sudo systemctl start influxdb
sudo systemctl enable influxdb

Check Service Status

You can check the status of the InfluxDB service with the following command:

sudo systemctl status influxdb

If you see active (running), it means the service is working fine.

After saving, restart the service:

sudo systemctl restart influxdb

and confirm that InfluxDB is listening on the port:

sudo lsof -i :8086

Create User and Database

You can use the following commands to create a user（user01，with password 12345678）,it will serve for high level management, creating databases and users.Then enter the influxdb command line interface to create a database（xdc）and a user（xdc）with password xdc.

curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER user01 WITH PASSWORD '12345678' WITH ALL PRIVILEGES"
influx -username 'user01' -password '12345678'
create database xdc
CREATE USER xdc WITH PASSWORD 'xdc'

Use the following commands to verify the created entries:

show databases
show users

3. Prepare Node

Download and configure xdpos, ensuring the folder settings are correct. Modify the startup script to add the following commands:

    --metrics \
    --metrics-influxdb \
    --metrics-influxdb.database "xdc" \
    --metrics-influxdb.username "xdc" \
    --metrics-influxdb.password "xdc" \
    --metrics-influxdb.endpoint "http://localhost:8086" \

start the node and check if the data is being pushed:

influx -username 'user01' -password '12345678'
use xdc
show measurements

Firewall Settings

If the firewall blocks access to port 8086, run the following command to check the status:

sudo ufw status

If the firewall is on and port 8086 is not allowed, run the following commands to open the port:

sudo ufw allow 8086
sudo ufw reload

4. Set Up Grafana

Install Grafana:

curl -tlsv1.3 --proto =https -sL https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install grafana -y
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

Check Grafana Status

Confirm if the Grafana service is running properly:

lsof -i :3000

Access the Grafana interface in your browser:

http://localhost:3000/

Configure InfluxDB Data Source

In Grafana, click on the "Data Sources" icon and select "InfluxDB". It is recommended to use the following configuration options:

Name: InfluxDB
Query Language: InfluxQL
HTTP
- URL: http://localhost:8086
- Access: Server (default)
- Whitelisted cookies: None (leave blank)
Auth: All options left as their default
InfluxDB Details
- Database:
- User:
- Password:
- HTTP Method: GET

Click on "Save and test" and wait for the confirmation to pop up,then you can follow the instruction to create a dashboard ,add panels and configure the dashboard.here is a often used example dashboard:

you can also create your own panel and dashboard to meet your needs,and adjust the parameters on Inspect>Penal JSON.

Configuring Multiple Data Sources

If you want to monitor the performance of multiple nodes at the same time, you can use the same steps to push data to the monitoring system. This means different nodes or services can send their performance metrics independently, allowing for centralized monitoring and data analysis. See the image below:

If you need to set up multiple data sources to view in the same dashboard, you can create a new variable in the dashboard to query the corresponding data.

To learn more about how dashboards work, refer to Grafana's documentation.

Using a Tracer to Locate Contracts

JukLee0ira — Tue, 17 Dec 2024 09:41:27 +0000

Abstract

The journey of the tool

The journey of creating the tracer tool began with a requirement: we needed to identify contract addresses that contained certain opcodes for better analysis and security auditing. Initially, we built a JavaScript version of the tool. This early iteration allowed us to interact with the blockchain and search for specific opcodes in blocks, providing a foundation for the solution.

We iterated on a few approaches, including using JS scripts for parsing and developing a native tracer, eventually coming up with a solution that provides excellent coverage of analysis in terms of the code executions being considered. This solution also delivers good performance, making it feasible to efficiently search a long stretch of historical data.

This solution includes a tracer to identify contract addresses within blocks and locate contracts containing specific opcodes. The specific implementation can be found here, and below is an example request:

Request Example:

RPC="http://172.16.3.16:8547"
NUMBER="0x399e"
curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{
  "jsonrpc": "2.0",
  "id": 1002,
  "method": "debug_traceBlockByNumber",
  "params": [
    "'"${NUMBER}"'", {
        "tracer":"contractTracer"
    }
  ]
}' | jq

Response Example:

{
  "jsonrpc": "2.0",
  "id": 1002,
  "result": [
    {
      "result": [
        "0xf63f8ba05d790b93db0005de3e65d90cd0b68bf6"
      ]
    }
  ]
}

In this request, contractTracer is used to trace contract code in a specified block. By matching a specific opcode, it filters contract addresses. The result is an array of contract addresses that contain the specified opcode.

JavaScript Version

The first version of the tool was built in JavaScript, leveraging Node.js to interact with blockchain nodes. It worked by iterating over blocks and using the RPC endpoint to analyze contract code. The JavaScript version was functional but had limitations:

Retrieving Transactions from Blocks: By querying blocks (e.g., using eth_getBlockByNumber), all transactions within that block were obtained.
Checking Each Transaction's Receipt: Using eth_getTransactionReceipt, the receipt of each transaction was queried. In the receipt, the contractAddress field would display the address of any newly created contract.
Confirming If the Address Is a Contract: For each contractAddress, eth_getCode was used to query the code at that address. If the returned code was non-zero, it indicated that the address was a smart contract. If a contract was created, eth_getCode was used to query the opcodes of that contract, matching them against the specified opcode. If a match was found, the contract address was written to a file.

This approach has a limitation: it cannot detect contracts created by the CREATE or CREATE2 opcodes. The reason is that it only checks the To field of a transaction, which shows the transaction's target address. However, contracts created with CREATE or CREATE2 are usually generated by internal calls within a contract, not by transactions directly sent from an externally owned account (EOA). As a result, these contracts don’t appear in the tx.To() field because they are created during the transaction execution, not as part of the transaction's target address.

Although callTracer can be used to check for opcodes used in a transaction, this method requires decoding a large amount of data, which can lead to frequent timeouts and significantly affect performance. This is especially true when scanning a large range of blocks. Therefore, we decided to explore a solution that requires fewer RPC calls and is much faster.

Golang version

Golang is usually faster than JS. By implementing a native tracer directly in the Golang client, we could reduce encoding/decoding and networking overhead. This led us to focus on developing a native tracer.

CaptureEnter Iteration

To address the limitations of the JavaScript version, we introduced the CaptureEnter iteration. In this version, we created a tracer within the node to track opcodes during contract execution. We added the possibility for users to customize all the tracers within XDC Golang client. This feature is utilized in our tool to specify the opcode of interest. This tracer accepted an opcode and returned the contract addresses containing the specified opcode.

This version focused on enhancing the tool's performance and scalability. It achieved a significant reduction in processing time (approximately 45-fold). The first approach took 1 day to process 22k blocks, while the improved version processed 1 million blocks in the same amount of time. This makes the tool far more practical for handling larger block ranges

CaptureState Version

The latest iteration, known as CaptureState, implemented its main logic in CaptureState, allowing for precise tracking of contract deployment and execution. Instead of analyzing static code, this version focused on actual execution threads of contracts, enabling us to track the code that was actively used rather than dormant.

Key Logic Explanation

When implementing the tracer, it follows these main steps to locate and filter contracts:

Initialization and Setup: In the Go code, the tracer's structure and initialization function are defined. Parameters in the structure control which opcode to search for.
Opcode Matching: While going through blocks and executing code, the tracer compares each instruction’s opcode with the user-specified opcode.

Note: If a contract contains an opcode but it is not called, the tracer will not detect this opcode.

Matching contract addresses are added to the result array.

Limitations

Currently, the tracer directly compares opcodes without differentiating between PREVRANDAO and DIFFICULTY. Both share the same opcode value (0x44).The PREVRANDAO opcode was enabled after block 76321000. Therefore, when using this tool, if you search for this opcode in blocks before 76321000, the matching results will correspond to the DIFFICULTY opcode. Understanding this limitation is crucial for accurately interpreting the results.

How to Use (Script)

For easier batch processing and data storage, a Node.js script opCodeFinder.js is provided and the implementation can be found here.This script searches for contracts with specific opcodes in a given block range and stores the results in a .txt file.

Script Example:

node src\opCodeFinder.js 72290000 latest PREVRANDAO https://rpc.ankr.com/xdc

Parameters

[START_BLOCK]: The starting block number for the search, e.g., 72290000 .
[END_BLOCK]: The ending block number or latest for the most recent block.
[OPCODE]: The opcode to search for, e.g., PREVRANDAO (case-sensitive).
[RPC_ENDPOINT]: The URL of the RPC node, e.g., https://rpc.ankr.com/xdc .

After running this script, all matching contract addresses are stored in a specified txt file for further analysis and use.

Results and Analysis

After developing the CaptureState version, we ran extensive analysis to identify contracts that might be vulnerable due to the presence of specific opcodes. For instance, contracts containing the PREVRANDAO opcode were of particular interest because of their potential impact on randomness generation and security.

Through our analysis, we identified several contracts that could be vulnerable based on their use of certain opcodes. This information is crucial for developers and auditors to assess the security of smart contracts and take appropriate measures to mitigate risks.

By using this method, developers can efficiently locate contracts with specific opcodes on the blockchain, providing valuable support for security audits and code analysis.

XDCValidator.sol：managing KYC and validators

JukLee0ira — Tue, 27 Aug 2024 06:21:41 +0000

The XDCValidator.sol contract helps with decentralized identity checks (called KYC) and managing validators. It does these tasks: handles user identity verification, lets users suggest and choose validators, and allows the community to vote on whether to accept identity checks that might not pass the standards.

Become a masternode

The process of becoming a masternode is shown in the diagram below:

         User 
          O   
         /|\  
         / \  

          |
          | Upload KYC information to participate
          | in the candidate process.
          v
+-----------------+
|   uploadKYC()   | 
+-----------------+
          |
          | Become an owner by depositing XDC
          | (minCandidateCap) and proposing
          | a candidate address.
          v
+-----------------+
|    propose()    | Propose an address as a candidate
+-----------------+
          | 
          |
          v
Now you are a candidate node owner

Kick out the masternodes

An invalid KYC will cause a owner to lose all of his candidate node. The process is shown in the diagram below:

+-----------------+
|   Candidates    |
|     (Node)      |
+-----------------+
          | 
          | 
          |
          v
+-----------------+
| voteInvalidKYC()| Report invalid KYC for other candidates
+-----------------+
          |
          | Check the invalid vote percentage
          | using `invalidPercent()` 
          |
          v
+---------+---------+
|                   |
v                   v
75% against         (else)
invalid KYC         valid KYC
the owner of KYC    Candidate remains valid.
Lost his candidates      
and funds

Resign

If you want to resign from candidacy. The process is shown in the diagram below:

        Owner
          O   
         /|\  
         / \  
          |
          |
          v
    +----------+
    | resign() |
    +----------+
          | Withdraws candidacy
          |
          |              
          | Locking Period
          | 30 days lock-up
          |
          |
          v
    +------------+
    | withdraw() |
    +------------+
     Withdraw funds from contract

Functions

Implementing KYC management and Validator management through several functions, with specific roles as follows:

uploadKYC

Uploads user KYC. This operation only stores the user's verification details and does not confer owner status.
Function Signature:

function uploadKYC(string memory kychash)

Who can use: Anyone(msg.sender)

Modifers: none

Parameters:

kychash : The hash of the user's KYC information. ### propose Owner proposes _candidate to become a masternode. Function Signature:

function propose(address _candidate)

Who can use: Anyone who has uploaded KYC (or is the owner) and has paid enough deposit.

Modifers: onlyKYCWhitelisted, onlyValidCandidateCap,onlyNotCandidate

Parameters:

_candidate : The address of the nominee.

vote

Deposits an amount not less than minVoterCap into the contract to cast a vote for the candidate.During voting, the candidate's total cap value will be updated.If it's the first time voting:

The voter will be added to the candidate's voter list.
The voter's stake for that candidate will be updated.

Function Signature:

function vote(address _candidate)

Who can use: Anyone (msg.sender) who has paid enough voting amount

Modifers: onlyValidVoterCap,onlyValidCandidate

Parameters:

_candidate : The address of the candidate receiving the vote. ### unvote Revokes a vote for a candidate, with the corresponding funds refunded after X blocks. Function Signature:

function unvote(
    address _candidate,
    uint256 _cap
)

Who can use: Anyone (msg.sender) who has a valid vote for a specific candidate node

Modifers: onlyValidVote

Parameters:

_candidate : The address of the candidate for whom the vote is to be revoked.
_cap : The amount to be refunded.

voteInvalidKYC

Allows the masternode, through a vote among masternode owner , to decide if another owner's KYC information meets the requirements. If over 75% of the owners deem it invalid, the KYC is considered Unqualified, leading to the forfeiture of funds from that owner and all their candidates.

Function Signature:

function voteInvalidKYC(address _invalidCandidate)

Who can use: Candidate

Modifers: onlyValidCandidate,onlyValidCandidate

Parameters:

_invalidCandidate : The address of the candidate whose owner's KYC validity is under judgment.

invalidPercent

Checks the percentage of "Invalid KYC" votes for a particular owner, indicating the level of community approval regarding that owner's KYC information.
Function Signature:

function invalidPercent(address _invalidCandidate) returns (uint)

Who can use: Anyone(msg.sender)

Modifers: onlyValidCandidate

Parameters:

_invalidCandidate : The address of the candidate whose owner's KYC recognition level needs to be queried.

The user can withdraw from candidacy and reclaim their funds upon meeting certain conditions.

resign

Withdraws candidacy, with the corresponding deposit refunded after X blocks. This function can only be called by the owner.
Function Signature:

function resign(address _candidate)

Who can use: Owner

Modifers: onlyOwner,onlyCandidate

Parameters:

_candidate : The address of the candidate wishing to withdraw their candidacy.

withdraw

This function allows for the withdrawal of funds from the contract, exclusively available to approved candidates.
Function Signature:

function withdraw(uint256 _blockNumber, uint _index)

Who can use: Addresses that have previously staked (as owner or voter) and have unlocked funds

Modifers: onlyValidWithdraw

Parameters:

_blockNumber : The block height associated with the withdrawal request. This is used to link the withdrawal action to a specific point in the blockchain's history.
_index : An index pointing to the user's current withdrawal request in the record. This helps in locating and processing the correct withdrawal operation for the candidate.

Modifers

The contract incorporates several Modifiers to govern the execution conditions of functions, serving specific purposes as outlined below:

onlyValidCandidateCap: The deposited amount (msg.value) must exceed minCandidateCap.
onlyValidVoterCap: The amount deposited into the contract (msg.value) must be greater than minVoteCap.
onlyKYCWhitelisted: A KYC record is required, or the address must have proposed or owns another candidate.
onlyOwner(address _candidate): restricts calls to the owner associated with the specified candidate.
onlyCandidate(address _candidate): allows calls only from the candidate specified.
onlyValidCandidate(address _candidate): permits calls exclusively from a legitimate candidate.
onlyNotCandidate(address _candidate): permits calls only from addresses that are not candidates.
onlyValidVote(address _candidate, uint256 _cap): requires the vote to be legitimate with respect to the candidate and the cap.
onlyValidWithdraw(uint256 _blockNumber, uint _index): demands that the block number is reasonable and valid for the withdrawal operation.