111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# Ghost Preclaim Snapshot Tool
|
|
The Ghost Preclaim Snapshot Tool is a comprehensive utility designed for the Envious NFT ecosystem, enabling seamless collection of NFT holdings snapshots and generation of cryptographically verifiable Merkle tree proofs. These proofs serve as the foundation for Ghostchain preclaim mechanisms, which are integral to the platform's governance framework.
|
|
|
|
## Overview
|
|
This repository contains two Python scripts that work together to:
|
|
|
|
1. Collect NFT ownership data and collateral balances from an EVM chain
|
|
2. Generate Merkle tree proofs for each EVM chain
|
|
|
|
## Requirements
|
|
```bash
|
|
pip install web3 tqdm
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Collect Snapshot Data
|
|
The Ghost Preclaim Snapshot Tool provides a straightforward command-line interface for collecting NFT snapshot data across multiple blockchain networks. Before running the tool, ensure you have properly configured your environment with the necessary RPC endpoints and network access credentials.
|
|
|
|
```bash
|
|
python finder.py --rpc <RPC_URL> [--delay 0.3]
|
|
```
|
|
|
|
Parameters:
|
|
```bash
|
|
--rpc: EVM JSON-RPC endpoint URL
|
|
--delay: (Optional) Delay between RPC requests in seconds (default: 0.3)
|
|
```
|
|
|
|
Example:
|
|
|
|
```bash
|
|
python finder.py --rpc https://sepolia.infura.io/v3/YOUR_KEY
|
|
```
|
|
|
|
### Generate Merkle Proofs
|
|
|
|
The Merkle proof generation module transforms raw snapshot data into cryptographically verifiable proofs that enable efficient and secure preclaim verification on the Ghostchain governance platform. This critical component ensures that only legitimate NFT holders can participate in governance decisions and claim their allocations.
|
|
|
|
```bash
|
|
python forester.py --chain <CHAIN_NAME>
|
|
```
|
|
|
|
Example:
|
|
|
|
```bash
|
|
python forester.py --chain 11155111
|
|
```
|
|
|
|
Output:
|
|
|
|
```bash
|
|
[+] Reading data snapshot: snapshots\sepolia.json
|
|
|
|
============================================================================================================
|
|
=== FINAL MERKLE ROOT FOR [11155111]: 0x95eeb07a13173eaad41a98e2216f84171641a76474e9e9f4c3bc069e4d461e8c ===
|
|
============================================================================================================
|
|
[+] Total padded leaves: 128
|
|
[+] Merkle tree size: 255
|
|
[+] Proof size: 7
|
|
[+] Total shares: 420000000000000000
|
|
|
|
[+] Proof are stored into: preclaims\11155111.json
|
|
```
|
|
|
|
## Supported Networks
|
|
* Sepolia Testnet
|
|
* Linea Sepolia Testnet
|
|
* BeraChain Testnet
|
|
* ZetaChain Testnet
|
|
|
|
This tool support any EVM-compatible blockchain where the JML (John McAfee Legacy) and GMV (Ghost McAfee Vision) smart contracts are deployed. This universal compatibility ensures seamless operation across multiple networks without requiring chain-specific configuration.
|
|
|
|
```bash
|
|
JML (NFT Collection): 0x91ba8A14D2CC851aBb69212c09f59e06e1e7f0a5
|
|
GMV (ERC20 Collateral Token): 0x7EF911f8ef130F73D166468c0068753932357B17
|
|
```
|
|
|
|
## Technical details
|
|
This section provides comprehensive technical specifications for developers, auditors, and advanced users who need to understand the underlying cryptographic mechanisms and data structures.
|
|
|
|
### Merkle Tree Implementation
|
|
The Merkle tree serves as the cryptographic backbone for verifying requested claims without exposing the entire dataset on-chain.
|
|
|
|
#### Leaf Node Construction
|
|
Each leaf node in the Merkle tree represents a unique NFT holding and is computed using the following formula:
|
|
|
|
```bash
|
|
leaf = keccak256(token_id + address + balance)
|
|
```
|
|
|
|
Where components are:
|
|
|
|
| Component | Description | Format |
|
|
|:-----------|:------------:|:------------|
|
|
| `token_id` | Unique NFT identifier within the contract | 32-byte unsigned integer (big-endian) |
|
|
| `address` | Token owner's wallet address | 20-byte EVM address |
|
|
| `balance` | GMV Collateral behind the NFT | 32-byte unsigned integer (big-endian) |
|
|
|
|
#### Empty Leaf Handling
|
|
For tree padding to achieve power-of-two size, empty leaves are represented as:
|
|
|
|
```bash
|
|
EMPTY_LEAF = Web3.keccak(b'')
|
|
# 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470
|
|
```
|
|
|
|
## Use wisely
|
|
|
|
Made with ❤️ for the ghosties all over the world
|