# 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