120 lines
4.4 KiB
Markdown
120 lines
4.4 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
|
|
usage: finder.py [-h] --rpc RPC [--bonus BONUS] [--delay DELAY]
|
|
|
|
EVM NFT Snapshot Collector for Ghostchain Preclaims
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
--rpc RPC EVM JSON-RPC Node URL
|
|
--bonus BONUS Additional JML ownership amounton top of the collateral (default: 6.9 CSPR)
|
|
--delay DELAY 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
|
|
usage: forester.py [-h] --network-id NETWORK_ID
|
|
|
|
Dynamic Merkle Tree for Ghost Preclaims
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
--network-id NETWORK_ID
|
|
EVM numeric Network ID to mix into preimage (e.g., 11155111)
|
|
```
|
|
|
|
Example:
|
|
|
|
```bash
|
|
python forester.py --network-id 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
|