Skip to content

Commit ed9ccd2

Browse files
0xrinegadeclaude
0xrinegade
and
claude
committed
feat(rpc): add Anza-compliant NAT compatibility and improve keypair management
This commit implements comprehensive improvements to RPC node management, NAT compatibility, and automated keypair handling based on official Anza documentation (https://docs.anza.xyz/clusters/available). NAT Compatibility (Anza Compliance): - Add --no-port-check flag to devnet/mainnet RPC for NAT environments - Add --only-known-rpc for HTTP-based snapshot downloads (no gossip UDP) - Add --private-rpc to avoid public RPC port announcements - Update dynamic port range to Anza-recommended 8000-8020 - Add WAL recovery mode for handling corrupted ledger records Keypair Management Improvements: - Check if keypair exists before generation (prevents overwrite errors) - Improve purpose-based keypair naming (key-default.json, key-validator.json) - Fix self-repair to skip generation if keypair already exists - Better error messages for keypair operations Self-Repair Enhancements: - Distinguish critical vs non-critical operations - System updates (requiring sudo) are now non-critical - Keypair generation remains critical (must succeed) - Improved rollback logic for failed operations Code Refactoring: - Extract RPC manager commands to dedicated module (src/commands/rpc_manager.rs) - Add early command handling for rpc-manager (bypasses config loading) - Improve code organization and maintainability Documentation: - Add NEVER-MODIFY-SOLANA-CONFIG.md (critical security warnings) - Add SECURITY-CHANGES-2025-10-13.md (change documentation) - Update CLAUDE.md with new RPC management details Testing: - Successfully tested devnet RPC with NAT compatibility - Validator syncing at ~1.3 MB/s via HTTP (expected for NAT mode) - 3+ hours uptime with zero crashes or errors - All Anza compliance flags verified working 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 9bde7f6 commit ed9ccd2

File tree

16 files changed

+1024
-17
lines changed

16 files changed

+1024
-17
lines changed

‎.claude_rules‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Claude Code Rules for OSVM-CLI
2+
3+
## CRITICAL SECURITY RULES - NEVER VIOLATE
4+
5+
### 🚨 NEVER MODIFY SOLANA CONFIGURATION FILES 🚨
6+
7+
**ABSOLUTE RULE: DO NOT CREATE, MODIFY, OR DELETE THESE FILES:**
8+
- `~/.config/solana/id.json` (Solana keypair)
9+
- `~/.config/solana/cli/config.yml` (Solana CLI config)
10+
- Any `.json` files in `~/.config/solana/` directory
11+
- Any wallet/keypair files anywhere on the system
12+
13+
**Why this is critical:**
14+
- These files contain private keys that cannot be recovered if lost
15+
- Overwriting them causes permanent, irreversible loss of funds and access
16+
- There are NO backups unless the user explicitly created them
17+
- The seed phrase may not be saved anywhere
18+
19+
**ALWAYS use explicit keypair paths:**
20+
```bash
21+
# CORRECT - Use temporary test keypair
22+
solana-keygen new --no-bip39-passphrase --outfile /tmp/test-keypair.json
23+
osvm --keypair /tmp/test-keypair.json <command>
24+
25+
# CORRECT - Use explicit test keypair
26+
osvm rpc-manager devnet --keypair /tmp/test-keypair.json
27+
28+
# WRONG - Never do this
29+
solana-keygen new --force --outfile ~/.config/solana/id.json # ❌ NEVER!
30+
```
31+
32+
**If a command requires a keypair and fails:**
33+
1. ASK the user first before creating any keypair
34+
2. Use `/tmp/` directory for temporary test keypairs
35+
3. Always use explicit `--keypair` flag to specify the test keypair path
36+
4. NEVER use `--force` flag with user's actual keypair location
37+
38+
**Testing procedures:**
39+
- Always create test keypairs in `/tmp/test-keypair-$(date +%s).json`
40+
- Always pass explicit `--keypair /tmp/test-keypair-*.json` to commands
41+
- Document the temporary keypair location in output
42+
- Clean up test keypairs when done
43+
44+
## Other Important Rules
45+
46+
### Configuration Files
47+
- Never modify user configuration without explicit permission
48+
- Always ask before changing `.gitconfig`, SSH configs, etc.
49+
- Back up configuration files before any modifications
50+
- Show diffs before applying changes
51+
52+
### Development Workflow
53+
- Follow the coding standards in CLAUDE.md
54+
- Run tests before committing changes
55+
- Use the pre-commit hooks
56+
- Document all new features
57+
58+
### Git Operations
59+
- Never force push to main/master
60+
- Never amend commits by other authors
61+
- Always create feature branches for new work
62+
- Follow conventional commit message format
63+
64+
### Security
65+
- Never log or display private keys
66+
- Use secure credential storage
67+
- Validate all user inputs
68+
- Follow principle of least privilege

‎.clinerules‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Cline Rules for OSVM-CLI
2+
3+
## 🚨 CRITICAL: NEVER MODIFY SOLANA CONFIGURATION 🚨
4+
5+
**ABSOLUTE PROHIBITION:**
6+
DO NOT create, modify, overwrite, or delete:
7+
- `~/.config/solana/id.json` - Solana keypair (IRREVERSIBLE IF LOST!)
8+
- `~/.config/solana/cli/config.yml` - Solana CLI configuration
9+
- Any wallet/keypair files in `~/.config/solana/` directory
10+
11+
**These files contain cryptographic private keys that CANNOT be recovered if lost!**
12+
13+
**REQUIRED PROCEDURE for testing:**
14+
1. Create temporary keypair: `/tmp/test-keypair-$(date +%s).json`
15+
2. Always use explicit `--keypair /tmp/test-keypair.json` flag
16+
3. NEVER rely on default keypair location
17+
4. ASK user before creating any keypair files
18+
19+
**Example - CORRECT usage:**
20+
```bash
21+
# Create test keypair in /tmp
22+
solana-keygen new --no-bip39-passphrase --outfile /tmp/test-keypair.json
23+
24+
# Use explicit keypair path
25+
osvm --keypair /tmp/test-keypair.json balance
26+
osvm rpc-manager devnet --keypair /tmp/test-keypair.json
27+
```
28+
29+
**Example - WRONG usage:**
30+
```bash
31+
# ❌ NEVER DO THIS
32+
solana-keygen new --force --outfile ~/.config/solana/id.json
33+
osvm rpc-manager devnet # Without explicit --keypair flag
34+
```
35+
36+
## General Development Rules
37+
38+
- Follow CLAUDE.md for project structure and patterns
39+
- Run tests before committing
40+
- Never force push to main/master
41+
- Always create feature branches
42+
- Document new features and breaking changes
43+
- Use conventional commit messages

‎.cursorrules‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Cursor Rules for OSVM-CLI
2+
3+
## ⚠️ CRITICAL SECURITY RULE - READ FIRST ⚠️
4+
5+
### NEVER MODIFY SOLANA CONFIGURATION FILES
6+
7+
**FORBIDDEN OPERATIONS:**
8+
- ❌ Creating, modifying, or deleting `~/.config/solana/id.json`
9+
- ❌ Creating, modifying, or deleting `~/.config/solana/cli/config.yml`
10+
- ❌ Any operations on files in `~/.config/solana/` directory
11+
- ❌ Using `solana-keygen` with `--force` flag on user's keypair
12+
- ❌ Using `--force` or `--overwrite` flags on wallet files
13+
14+
**WHY THIS IS CRITICAL:**
15+
These files contain private cryptographic keys that:
16+
- Cannot be recovered if overwritten or deleted
17+
- May not have backups or seed phrases saved
18+
- Control access to funds and blockchain identity
19+
- Are unique and irreplaceable
20+
21+
**REQUIRED TESTING PROCEDURE:**
22+
23+
When testing requires a keypair:
24+
25+
```bash
26+
# Step 1: Create temporary test keypair (ALWAYS in /tmp)
27+
TMP_KEYPAIR="/tmp/test-keypair-$(date +%s).json"
28+
solana-keygen new --no-bip39-passphrase --outfile "$TMP_KEYPAIR"
29+
30+
# Step 2: Use explicit --keypair flag in ALL commands
31+
osvm --keypair "$TMP_KEYPAIR" balance
32+
osvm rpc-manager devnet --keypair "$TMP_KEYPAIR"
33+
cargo run -- --keypair "$TMP_KEYPAIR" <command>
34+
35+
# Step 3: Clean up when done
36+
rm -f "$TMP_KEYPAIR"
37+
```
38+
39+
**If command fails due to missing keypair:**
40+
1. ASK user for permission first
41+
2. Create test keypair in `/tmp/` directory only
42+
3. Use explicit `--keypair` path in every command
43+
4. Never assume default keypair location is safe to modify
44+
45+
## Development Guidelines
46+
47+
### Code Style
48+
- Follow Rust conventions and clippy recommendations
49+
- Use meaningful variable names
50+
- Add documentation comments for public APIs
51+
- Keep functions focused and single-purpose
52+
53+
### Testing
54+
- Write unit tests for new functionality
55+
- Run `cargo test` before committing
56+
- Update integration tests when changing public APIs
57+
- Use `cargo test --test <name>` for specific tests
58+
59+
### Git Workflow
60+
- Create feature branches from `main`
61+
- Write descriptive commit messages
62+
- Never force push to `main` or `master`
63+
- Run pre-commit hooks before committing
64+
65+
### Documentation
66+
- Keep CLAUDE.md updated with architectural changes
67+
- Update README.md for user-facing features
68+
- Document breaking changes clearly
69+
- Add examples for new commands
70+
71+
### Security
72+
- Never log private keys or sensitive data
73+
- Validate all user inputs
74+
- Use secure random number generation
75+
- Follow principle of least privilege

‎.github/copilot-instructions.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,73 @@
11
# OSVM CLI - AI Coding Assistant Instructions
22

3+
## 🚨 CRITICAL SECURITY RULE - READ FIRST 🚨
4+
5+
### ⚠️ NEVER MODIFY SOLANA CONFIGURATION FILES ⚠️
6+
7+
**ABSOLUTE PROHIBITION - MOST IMPORTANT RULE:**
8+
9+
**FORBIDDEN OPERATIONS:**
10+
1. ❌ **NEVER** create, modify, or delete `~/.config/solana/id.json`
11+
2. ❌ **NEVER** create, modify, or delete `~/.config/solana/cli/config.yml`
12+
3. ❌ **NEVER** run `solana-keygen` with `--force` flag on user's keypair location
13+
4. ❌ **NEVER** use default keypair paths without explicit `--keypair` flag
14+
5. ❌ **NEVER** overwrite any wallet/keypair files anywhere
15+
16+
**WHY THIS IS CRITICAL:**
17+
- These files contain **irreplaceable cryptographic private keys**
18+
- Overwriting them causes **permanent, irreversible loss** of funds and blockchain identity
19+
- **NO RECOVERY** is possible without the seed phrase
20+
- The seed phrase may **NOT be saved anywhere**
21+
- Violating this rule causes **catastrophic user data loss**
22+
23+
**REQUIRED SAFE TESTING PROCEDURE:**
24+
25+
When testing requires a Solana keypair:
26+
27+
```bash
28+
# ✅ CORRECT - Always create temporary test keypair in /tmp
29+
TMP_KEYPAIR="/tmp/test-keypair-$(date +%s).json"
30+
solana-keygen new --no-bip39-passphrase --outfile "$TMP_KEYPAIR"
31+
32+
# ✅ CORRECT - Always use explicit --keypair flag
33+
osvm --keypair "$TMP_KEYPAIR" balance
34+
osvm rpc-manager devnet --keypair "$TMP_KEYPAIR" --background
35+
cargo run -- --keypair "$TMP_KEYPAIR" <command>
36+
37+
# ✅ CORRECT - Clean up temporary keypair when done
38+
rm -f "$TMP_KEYPAIR"
39+
```
40+
41+
```rust
42+
// ✅ CORRECT - Use explicit temporary keypair path
43+
let test_keypair = "/tmp/test-keypair.json";
44+
let config = Config {
45+
keypair_path: Some(test_keypair.to_string()),
46+
..Default::default()
47+
};
48+
```
49+
50+
❌ **NEVER DO THIS:**
51+
```bash
52+
# ❌ CATASTROPHIC - Overwrites user's actual keypair
53+
solana-keygen new --force --outfile ~/.config/solana/id.json
54+
55+
# ❌ DANGEROUS - Uses default keypair location (may fail and tempt overwriting)
56+
osvm rpc-manager devnet
57+
58+
# ❌ WRONG - Relies on default configuration
59+
cargo run -- balance
60+
```
61+
62+
**If Command Fails Due to Missing Keypair:**
63+
64+
1. **ASK** the user for permission first
65+
2. **CREATE** temporary test keypair in `/tmp/` directory only
66+
3. **USE** explicit `--keypair /tmp/test-keypair.json` flag in ALL commands
67+
4. **NEVER** assume it's safe to create/modify files in `~/.config/solana/`
68+
69+
---
70+
371
## Project Overview
472
OSVM (Open Solana Virtual Machine) is a revolutionary blockchain infrastructure CLI tool providing zero-downtime updates, hardware-isolated execution with Firecracker MicroVMs/unikernels, and AI-powered Solana blockchain analysis. **Everything must be implemented in Rust** - no standalone scripts allowed.
573

‎CLAUDE.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,67 @@
22

33
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44

5+
## 🚨 CRITICAL SECURITY RULE - MUST READ FIRST 🚨
6+
7+
### ⚠️ NEVER MODIFY SOLANA CONFIGURATION FILES ⚠️
8+
9+
**THIS IS THE MOST IMPORTANT RULE - VIOLATING IT CAUSES IRREVERSIBLE DATA LOSS**
10+
11+
**ABSOLUTE PROHIBITION:**
12+
1. ❌ **NEVER** create, modify, or delete `~/.config/solana/id.json` (Solana keypair)
13+
2. ❌ **NEVER** create, modify, or delete `~/.config/solana/cli/config.yml` (Solana config)
14+
3. ❌ **NEVER** run `solana-keygen` with `--force` flag on user's keypair location
15+
4. ❌ **NEVER** use default keypair paths without explicit `--keypair` flag
16+
5. ❌ **NEVER** overwrite any wallet/keypair files
17+
18+
**WHY THIS IS CRITICAL:**
19+
- These files contain **cryptographic private keys that CANNOT be recovered if lost**
20+
- Overwriting them causes **permanent, irreversible loss** of:
21+
- Blockchain identity
22+
- Access to funds (potentially millions of dollars)
23+
- All associated on-chain data and permissions
24+
- The seed phrase may **NOT** be saved anywhere
25+
- **NO RECOVERY** is possible - the data is lost forever
26+
27+
**REQUIRED SAFE TESTING PROCEDURE:**
28+
29+
Always create temporary test keypairs in `/tmp/`:
30+
31+
```bash
32+
# ✅ CORRECT - Temporary test keypair
33+
TMP_KEYPAIR="/tmp/test-keypair-$(date +%s).json"
34+
solana-keygen new --no-bip39-passphrase --outfile "$TMP_KEYPAIR"
35+
36+
# ✅ CORRECT - Always use explicit --keypair flag
37+
osvm --keypair "$TMP_KEYPAIR" balance
38+
osvm rpc-manager devnet --keypair "$TMP_KEYPAIR" --background
39+
cargo run -- --keypair "$TMP_KEYPAIR" <command>
40+
41+
# ✅ CORRECT - Clean up when done
42+
rm -f "$TMP_KEYPAIR"
43+
```
44+
45+
❌ **CATASTROPHIC MISTAKES TO AVOID:**
46+
```bash
47+
# ❌ NEVER DO THIS - Overwrites user's keypair permanently!
48+
solana-keygen new --force --outfile ~/.config/solana/id.json
49+
50+
# ❌ DANGEROUS - May tempt overwriting if missing
51+
osvm rpc-manager devnet # Without --keypair flag
52+
53+
# ❌ WRONG - Don't assume default paths are safe
54+
cargo run -- balance # Uses default keypair
55+
```
56+
57+
**If Command Fails Due to Missing Keypair:**
58+
1. **STOP** immediately
59+
2. **ASK** user for permission
60+
3. **CREATE** temporary keypair in `/tmp/` ONLY
61+
4. **USE** explicit `--keypair /tmp/test-keypair.json` in ALL commands
62+
5. **NEVER** assume you can modify files in `~/.config/solana/`
63+
64+
---
65+
566
## Table of Contents
667
1. [Development Environment Setup](#development-environment-setup)
768
2. [Development Commands](#development-commands)

0 commit comments

Comments
 (0)