GP-CLI — Graveyard Protocol Command Line Interface

Close empty Solana SPL token accounts and reclaim the locked rent (SOL) back to your wallet.

---

Requirements

• Node.js 20+
• A Solana wallet private key (JSON byte array or Base58 string)

---

Installation

npm install -g @graveyardprotocol/gp-cli

Or run directly from the repo:

git clone https://github.com/GraveyardProtocol/gp-cli
cd gp-cli
npm install
npm link          

---

Quick Start

1. Add a wallet

gp add-wallet

You will be prompted for your private key. Both formats are accepted:

Format	Example
JSON byte array	[12, 34, 56, ...] — exported by Phantom / Solflare
Base58 string	5Jxyz... — some wallet exporters

Your private key is never stored in plaintext. It is encrypted with AES-256-GCM using a password you choose, and stored in ~/.gp-cli/wallets.json.

2. Close empty token accounts

gp close-empty

You will be shown a scan summary and asked to confirm before any transaction is submitted.

3. Claim your SOUL tokens

gp claim-soul

At the end of each weekly epoch, SOUL tokens are allocated based on your Ghost Point share. Use this command to claim them to your wallet.

---

All Commands

Command	Description
gp add-wallet	Add and encrypt a Solana wallet
gp remove-wallet	Remove a saved wallet
gp list-wallets	Show all saved wallet public keys
gp close-empty	Scan and close empty token accounts
gp close-empty --dry-run	Preview what would be closed — no transactions sent
gp close-empty --all	Process every saved wallet in sequence
gp stats	Show Ghost Point and SOL earnings for current and previous epoch
gp stats --all	Show stats for all saved wallets in a summary table
gp stats --wallet <address>	Look up any wallet address directly (no saved wallet needed)
gp claim-soul	Claim SOUL tokens earned in the previous epoch
gp claim-soul --all	Claim for all saved wallets in sequence
gp claim-soul --dry-run	Preview claimable SOUL without submitting a transaction

---

How It Works

Closing Empty Token Accounts

CLI                           Backend                      Solana
 │                               │                            │
 ├─ gp close-empty               │                            │
 │                               │                            │
 ├──── GET /scan/{wallet} ───────►                            │
 │◄─── { total_accounts, SOL } ──┤  scans on-chain ──────────►
 │                               │◄─ results ─────────────────┤
 │                               │                            │
 ├──── GET /getBatchCount ───────►                            │
 │◄─── { totalBatches } ─────────┤                            │
 │                               │                            │
 ├──── POST /processBatch ───────►                            │
 │◄─── { intentID,              ─┤  builds instructions       │
 │       instructionsBatch }     │                            │
 │                               │                            │
 ├── build Tx, sign locally ─────►                            │
 │                               │                            │
 ├──── POST /executeBatch ───────►                            │
 │◄─── { txSignature, SOL } ─────┤  simulates + submits ──────►
 │                               │◄─ confirmed ───────────────┤

The CLI never broadcasts to Solana directly. Signing happens locally with your decrypted keypair; the signed transaction is handed to the backend API which simulates, sends, and confirms it.

Claiming SOUL Tokens

CLI                           Backend                      Solana
 │                               │                            │
 ├─ gp claim-soul                │                            │
 │                               │                            │
 ├──── GET /epoch/data/{wallet} ─►                            │
 │◄─── { previousEpoch: {       ─┤                            │
 │       userSoul, claimState } }│                            │
 │                               │                            │
 ├── show summary, confirm ──────►                            │
 │                               │                            │
 ├──── POST /soul/claim ─────────►                            │
 │◄─── { txSignature } ──────────┤  builds ATA + transfer ───►
 │                               │◄─ confirmed ───────────────┤

SOUL transfers are signed and submitted entirely by the backend using the Community Wallet — no signing is required from your keypair.

---

Protocol Economics

Item	Value
Protocol fee	20% of reclaimed rent per batch
You receive	~80% of total locked SOL
Ghost Points	100 points per closed account
Referral bonus	10% of referred user's Ghost Points credited to referrer
Average rent per account	~0.00204 SOL

Epochs & SOUL Distribution

Epochs run weekly, starting Monday 00:00 UTC. At the close of each epoch, SOUL tokens are distributed proportionally based on each participant's share of total Ghost Points earned. Use gp stats to track your share before claiming.

---

Security

• Private keys encrypted with AES-256-GCM
• Key derived via PBKDF2 (SHA-256, 100,000 iterations)
• Stored at ~/.gp-cli/wallets.json — never transmitted
• GCM authentication tag prevents ciphertext tampering
• SOUL claims require no local signing — the backend community wallet handles the transfer

---

Local Storage

Path	Contents
~/.gp-cli/wallets.json	Encrypted wallet entries

---

Note: The source code provided in this repository is for transparency and auditing purposes only. It does not constitute an Open Source grant.

---

License

Graveyard Protocol CLI (gp-cli) is proprietary software. All rights reserved.

The use of this software is governed by the Proprietary Software License Agreement found in the LICENSE file included in this repository.

Commercial Use: Permitted under the terms of the license.

Modification/Redistribution: Strictly prohibited.

Reverse Engineering: Strictly prohibited.

For third-party library attributions, please refer to the THIRD_PARTY_LICENSES file generated in the distribution.