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

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.

python finder.py --rpc <RPC_URL> [--delay 0.3]

Parameters:

--rpc: EVM JSON-RPC endpoint URL
--delay: (Optional) Delay between RPC requests in seconds (default: 0.3)

Example:

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.

python forester.py --chain <CHAIN_NAME>

Example:

python forester.py --chain 11155111

Output:

[+] 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.

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:

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:

EMPTY_LEAF = Web3.keccak(b'')
# 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470

Use wisely

Made with ❤️ for the ghosties all over the world