Skip to content

Alex110709/obsidian-core

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

75 Commits
.letta
.letta
 
 
assets
assets
 
 
blockchain
blockchain
 
 
chaincfg
chaincfg
 
 
cmd/obsidiand
cmd/obsidiand
 
 
config
config
 
 
consensus
consensus
 
 
crypto
crypto
 
 
database
database
 
 
docs
docs
 
 
evm
evm
 
 
mining
mining
 
 
network
network
 
 
rpcserver
rpcserver
 
 
scripts
scripts
 
 
smartcontract
smartcontract
 
 
stratum
stratum
 
 
testnet
testnet
 
 
tests
tests
 
 
tor
tor
 
 
website
website
 
 
wire
wire
 
 
zkp
zkp
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
Dockerfile
Dockerfile
 
 
README.md
README.md
 
 
build_and_push.sh
build_and_push.sh
 
 
docker-compose.cluster.yml
docker-compose.cluster.yml
 
 
docker-compose.pool.yml
docker-compose.pool.yml
 
 
docker-compose.seeds.yml
docker-compose.seeds.yml
 
 
docker-compose.testnet.yml
docker-compose.testnet.yml
 
 
docker-compose.tor.yml
docker-compose.tor.yml
 
 
docker-compose.yml
docker-compose.yml
 
 
example.env
example.env
 
 
go.mod
go.mod
 
 
go.sum
go.sum
 
 
torrc
torrc
 
 

Repository files navigation

Obsidian Chain

The World's First Production-Ready EVM + ZK-SNARK Hybrid Blockchain

Production Ready Version Tests ZK Proofs Docker

A privacy-focused, EVM-compatible blockchain with real ZK-SNARK proofs, shielded transactions, and fair launch (no premine).

Latest Version: v3.0.0 | Release Notes | Production Ready Report

What's New in v3.0.0 - Chromatic Phase + Parallel Processing

🎨 Revolutionary Smooth Halving System

  • ⚡ 1-Second Block Time: Lightning-fast confirmations
  • 🌈 Chromatic Phase: Smooth exponential decay instead of harsh halvings
  • 📈 10 Billion Supply: Expanded for global adoption
  • 🔄 2-Year Phases: Gradual transitions every ~63M blocks
  • 💰 Stable Mining: Predictable rewards without shock events

🚀 Parallel Block Processing

  • ⚡ 10x Faster Sync: Parallel validation during IBD
  • 🔄 Smart Mode Switching: IBD vs Real-time optimization
  • 📊 Ordering Guarantee: Strict block sequence maintained
  • 🎯 Auto-scaling: CPU cores automatically utilized
Reward: 158 OBS → [Smooth Decay] → 79 OBS over 2 years
Sync: 10,000 blocks → 16 minutes (was 2.7 hours)

See Chromatic Phase and Parallel Processing for details.

⭐ Key Features

🔒 Privacy & ZK-SNARKs

  • Real Groth16 Proofs: 324-byte zero-knowledge proofs (not placeholders!)
  • Complete Privacy: Sender, receiver, and amount hidden
  • Nullifier-based Double-Spend Prevention: Cryptographically secure
  • Privacy Modes: Transparent, Shielded, Hybrid
  • Merkle Tree: 20-level tree (1M+ note capacity)

⚡ EVM Compatibility

  • Full Ethereum Compatibility: Deploy any Solidity contract
  • Web3 API: Standard Ethereum JSON-RPC
  • Smart Contracts: Complete EVM support
  • Gas System: EIP-1559 style with 30M limit
  • StateDB: Complete vm.StateDB implementation

🚀 Performance

  • Parallel Processing: 12-worker block validation
  • Fast Sync: Optimized blockchain synchronization
  • Efficient Proofs: ~50ms generation, ~5ms verification
  • Low Overhead: Minimal resource usage

💰 Fair Economics

  • No Premine: 0 initial supply (100% fair launch)
  • Block Reward: ~158 OBS initially (Chromatic Phase)
  • Block Time: 1 second (ultra-fast)
  • Phase Duration: ~2 years (smooth decay, not harsh halving)
  • Max Supply: 10,000,000,000 OBS (10 Billion)
  • DarkMatter PoW: AES/SHA256 hybrid consensus

Specifications

  • Block Time: 1 second (ultra-fast confirmations)
  • Gas Limit: 30M (EIP-1559 style)
  • Total Supply: 10 Billion OBS
  • Block Reward: Chromatic Phase system (smooth decay, ~158 OBS initially)
  • Phase Duration: 2 years (~63M blocks)
  • Consensus: DarkMatter PoW (AES/SHA256 hybrid)
  • Privacy: Shielded addresses (zobs*), encrypted memos
  • Tokens: ERC-20 style tokens with shielded transfers
  • Burn Redistribution: 0.1% of burned OBS redistributed to miners

Privacy Features (NEW in v1.1.0)

Shielded Transactions

Obsidian implements Zcash-style shielded transactions for complete privacy:

  • Shielded Addresses (z-addresses): Start with zobs prefix
  • Transparent Addresses (t-addresses): Standard addresses starting with Obs
  • Private Transfers: Amount, sender, and receiver hidden using cryptographic proofs
  • Encrypted Memos: Attach encrypted messages to transactions (up to 512 bytes)
  • Selective Disclosure: View-only keys allow read access without spending permission

Transaction Types

  1. Transparent (t→t): Standard public transactions
  2. Shielded (z→z): Fully private transactions
  3. Shielding (t→z): Move funds from transparent to shielded pool
  4. Deshielding (z→t): Move funds from shielded to transparent pool

Token System

Create and manage custom tokens without smart contracts. Full token lifecycle support with minting, burning, and ownership transfers.

Token Features:

  • Issuance: Create tokens with custom parameters
  • Minting: Additional token creation (if enabled)
  • Burning: Permanent token destruction
  • Transfers: Send tokens between addresses
  • Shielding: Private token transactions
  • Ownership: Transfer token control

RPC Methods:

  • issuetoken - Create new tokens
  • minttoken - Mint additional tokens
  • burntoken - Burn tokens permanently
  • transfertoken - Transfer tokens
  • transfertokenownership - Change token owner
  • shieldtoken - Private token transfers
  • gettokenbalance - Check balances

See Token Guide for detailed documentation.

GUI Wallet

Obsidian includes a beautiful desktop wallet with full privacy support.

Features

  • 🌑 Dark Modern UI: Clean, professional interface
  • 🔐 BIP39 Recovery: 24-word mnemonic phrase backup
  • 👁️ Balance Overview: Real-time balance across all addresses
  • 📤 Easy Sending: Send to transparent or shielded addresses
  • 📥 Address Generation: Create new transparent/shielded addresses
  • 🔒 Auto Shield/Unshield: Automatic privacy routing
  • 📊 Transaction History: Track all your transactions
  • 💾 Wallet Backup: Export and import wallet files

Quick Start

# Install dependencies
pip3 install base58 ecdsa requests coincurve mnemonic

# Run GUI wallet
python3 wallet_gui.py

Usage

  1. Create New Wallet: Generate a new wallet with 24-word recovery phrase
  2. Load Wallet: Import existing wallet from file or recovery phrase
  3. Receive: Generate new addresses (transparent or shielded)
  4. Send: Send OBS to any address (auto shield/unshield)
  5. Backup: Export wallet file for safekeeping

Screenshots

The GUI wallet features:

  • Overview Tab: View total balance and all addresses
  • Send Tab: Send transactions with memo support
  • Receive Tab: Generate new addresses
  • History Tab: View all transactions
  • Settings Tab: Manage wallet and view recovery phrase

🚀 Quick Start (5 Minutes)

Prerequisites

  • Go 1.22+ (or Docker)
  • 4GB RAM minimum
  • 100GB storage

Method 1: Using Scripts (Easiest)

# Clone repository
git clone https://github.com/yourusername/obsidian-core.git
cd obsidian-core

# Build binary
go build -o obsidiand ./cmd/obsidiand

# Start node (solo mode)
./scripts/start_node.sh

# Or with custom miner address
OBSIDIAN_MINER_ADDRESS="YourAddress123456789012345" \
  ./scripts/start_node.sh

Method 2: Docker (Recommended for Production)

# Quick start
docker-compose up -d

# View logs
docker-compose logs -f

# Test RPC
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

Method 3: Manual Binary

# Build
go build -o obsidiand ./cmd/obsidiand

# Run
./obsidiand --miner=YourMinerAddress123456789012345

That's it! Your node is now running:

  • P2P: 0.0.0.0:8333
  • RPC: http://0.0.0.0:8545 (Ethereum-compatible)
  • Mining: Active (if miner address set)
  • Privacy: ZK-SNARK enabled

Quick Start with Docker

The fastest way to run Obsidian Core:

# Pull and run the latest version (v2.0.5)
docker pull yuchanshin/obsidian-node:v2.0.5
docker run -d -p 8333:8333 -p 8545:8545 yuchanshin/obsidian-node:v2.0.5

# With custom configuration
docker run -d \
  -p 8333:8333 -p 8545:8545 \
  -e SOLO_MINING=true \
  -e MINER_ADDRESS=YourAddress \
  -v obsidian-data:/home/obsidian/data \
  yuchanshin/obsidian-node:latest

Docker Compose Deployments

Multiple deployment configurations available:

# Standard single node
docker-compose up -d

# Mining pool
docker-compose -f docker-compose.pool.yml up -d

# Seed nodes
docker-compose -f docker-compose.seeds.yml up -d

# Cluster deployment
docker-compose -f docker-compose.cluster.yml up -d

# Tor-enabled node
docker-compose -f docker-compose.tor.yml up -d

Building from Source

Linux

# Install Go (Ubuntu/Debian)
sudo apt update
sudo apt install golang-go

# Clone and build
git clone https://github.com/your-org/obsidian-core.git
cd obsidian-core
go mod tidy
go build ./cmd/obsidiand

# Run
./obsidiand

macOS

# Install Go using Homebrew
brew install go

# Or download from https://golang.org/dl/

# Clone and build
git clone https://github.com/your-org/obsidian-core.git
cd obsidian-core
go mod tidy
go build ./cmd/obsidiand

# Run
./obsidiand

Windows

# Install Go from https://golang.org/dl/
# Or using Chocolatey
choco install golang

# Clone and build
git clone https://github.com/your-org/obsidian-core.git
cd obsidian-core
go mod tidy
go build ./cmd/obsidiand

# Run
.\obsidiand.exe

Cross-Platform Build

# Build for Linux (from any platform)
GOOS=linux GOARCH=amd64 go build ./cmd/obsidiand

# Build for Windows (from any platform)
GOOS=windows GOARCH=amd64 go build ./cmd/obsidiand

# Build for macOS (from any platform)
GOOS=darwin GOARCH=amd64 go build ./cmd/obsidiand

Running the Node

# Run directly (development)
go run cmd/obsidiand/main.go

# Or run built binary
./obsidiand

This will start the node, initialize the blockchain with the Genesis block, and start a CPU miner simulation.

Environment Variables

Obsidian Core can be configured using environment variables. Below is a complete list of all available variables:

Network Configuration

Variable Default Description
NETWORK mainnet Network type (mainnet, testnet, regtest)
P2P_ADDR 0.0.0.0:8333 P2P server listen address and port (e.g., 0.0.0.0:18333)
RPC_ADDR 0.0.0.0:8545 RPC server listen address and port
SEED_NODES - Comma-separated list of seed nodes (e.g., node1,node2 or node1:8333,node2:8333)
SEED_PORT 8333 Default port to use for seed nodes if not specified in SEED_NODES

Peer Management

Variable Default Description
MAX_PEERS 125 Maximum number of peer connections
MIN_PEERS 8 Minimum number of peer connections to maintain
CONNECT_TIMEOUT 30s Timeout for establishing peer connections
MESSAGE_TIMEOUT 300s Timeout for receiving peer messages (5 minutes)
MAX_MESSAGE_SIZE 10485760 Maximum P2P message size in bytes (10MB)
BAN_DURATION 24h Duration to ban misbehaving peers

Mining Configuration

Variable Default Description
SOLO_MINING true Enable/disable solo mining
MINER_ADDRESS ObsidianDefaultMinerAddress123456789 Address to receive mining rewards
POOL_SERVER false Enable/disable Stratum pool server
POOL_ADDR 0.0.0.0:3333 Pool server listen address
POOL_LISTEN 0.0.0.0:3333 Pool server listen address (alternative)

Logging

Variable Default Description
LOG_LEVEL info Logging level (debug, info, warn, error)
LOG_FILE - Path to log file (empty = stdout only)

Storage

Variable Default Description
DATA_DIR . Directory for blockchain data storage

Privacy & Tor

Variable Default Description
TOR_ENABLED false Enable/disable Tor networking
TOR_PROXY_ADDR 127.0.0.1:9050 Tor SOCKS5 proxy address

Important Security Note: The built-in Tor configuration is set to client-only mode and will NOT operate as an exit node. This prevents your node from relaying other users' traffic, which could expose you to legal liability. The following settings are pre-configured in /etc/tor/torrc:

  • ExitPolicy reject *:* - Rejects all exit traffic
  • ExitRelay 0 - Disables exit relay functionality
  • ClientOnly 1 - Only acts as a Tor client

Go Runtime (Performance Tuning)

Variable Default Description
GOGC 100 Go garbage collection target percentage (lower = more aggressive GC)
GOMAXPROCS CPU cores Maximum number of OS threads for Go runtime

Example Configurations

Solo Mining Node

SOLO_MINING=true \
MINER_ADDRESS=YourObsidianAddress \
LOG_LEVEL=info \
./obsidiand

Mining Pool Server

POOL_SERVER=true \
POOL_LISTEN=0.0.0.0:3333 \
MINER_ADDRESS=PoolOwnerAddress \
SOLO_MINING=false \
./obsidiand

Tor-Enabled Privacy Node

TOR_ENABLED=true \
TOR_PROXY_ADDR=127.0.0.1:9050 \
SOLO_MINING=false \
LOG_LEVEL=info \
./obsidiand

Docker with Tor:

services:
  obsidian-tor:
    image: yuchanshin/obsidian-node:latest
    ports:
      - "8333:8333"
      - "8545:8545"
    environment:
      - TOR_ENABLED=true
      - TOR_PROXY_ADDR=127.0.0.1:9050
      - SOLO_MINING=false
    volumes:
      - obsidian-data:/home/obsidian/data

Security Note: Tor is configured as client-only and will NOT operate as an exit node, protecting you from legal liability.

Node Connecting to Seed Nodes

Option 1: Using SEED_PORT (Recommended)

SEED_NODES=192.168.1.10,192.168.1.11 \
SEED_PORT=18333 \
SOLO_MINING=false \
./obsidiand

Option 2: Explicit ports in SEED_NODES

SEED_NODES=192.168.1.10:18333,192.168.1.11:18333 \
SOLO_MINING=false \
./obsidiand

Option 3: Mixed (some with ports, some without)

SEED_NODES=192.168.1.10:18333,192.168.1.11,192.168.1.12:9000 \
SEED_PORT=8333 \
SOLO_MINING=false \
./obsidiand
# Result: 192.168.1.10:18333, 192.168.1.11:8333, 192.168.1.12:9000

Docker Port Mapping Notes:

  • If your miner exposes port 18333 externally: Use SEED_PORT=18333
  • If using Docker network (container names): Use default SEED_PORT=8333

Custom P2P Port

# Listen on port 18333 instead of default 8333
P2P_ADDR=0.0.0.0:18333 \
SOLO_MINING=true \
MINER_ADDRESS=YourAddress \
./obsidiand

Docker Example with Custom Ports:

services:
  miner:
    image: yuchanshin/obsidian-node:latest
    ports:
      - "18333:18333"  # External:Internal (both 18333)
      - "18545:8545"   # RPC on different external port
    environment:
      - P2P_ADDR=0.0.0.0:18333        # Listen on 18333 inside container
      - SOLO_MINING=true
      - MINER_ADDRESS=YourAddress

Seed Node

P2P_ADDR=0.0.0.0:8333 \
MAX_PEERS=500 \
SOLO_MINING=false \
DATA_DIR=/var/lib/obsidian \
LOG_FILE=/var/log/obsidian/node.log \
./obsidiand

Full Node with Custom Configuration

NETWORK=mainnet \
P2P_ADDR=0.0.0.0:8333 \
RPC_ADDR=127.0.0.1:8545 \
SEED_NODES=seed1.obsidian.network:8333,seed2.obsidian.network:8333 \
MAX_PEERS=125 \
MIN_PEERS=8 \
SOLO_MINING=true \
MINER_ADDRESS=obs5pPyd6DA6tYyYwip4hYcBWWFTNf4wj8nn \
DATA_DIR=/home/obsidian/data \
LOG_LEVEL=info \
LOG_FILE=/home/obsidian/logs/obsidian.log \
./obsidiand

Docker Environment File (.env)

# Network
NETWORK=mainnet
P2P_ADDR=0.0.0.0:8333
RPC_ADDR=0.0.0.0:8545

# Peers
MAX_PEERS=125
MIN_PEERS=8
SEED_NODES=seed1:8333,seed2:8333

# Mining
SOLO_MINING=true
MINER_ADDRESS=your_address_here

# Logging
LOG_LEVEL=info
LOG_FILE=/home/obsidian/logs/obsidian.log

# Storage
DATA_DIR=/home/obsidian/data

# Privacy
TOR_ENABLED=false

# Performance
GOGC=50
GOMAXPROCS=4

Documentation

Docker Hub

Official multi-architecture Docker images are available at: yuchanshin/obsidian-node

# Latest version (automatically selects correct architecture)
docker pull yuchanshin/obsidian-node:latest

# Specific versions
docker pull yuchanshin/obsidian-node:v3.0.0
docker pull yuchanshin/obsidian-node:v1.2.4

Supported Architectures:

  • ✅ linux/amd64 (Intel/AMD x86_64)
  • ✅ linux/arm64 (Apple Silicon M1/M2/M3, AWS Graviton, Raspberry Pi)

Platform-Specific Pull:

# Force specific architecture (optional)
docker pull --platform linux/amd64 yuchanshin/obsidian-node:latest
docker pull --platform linux/arm64 yuchanshin/obsidian-node:latest

Docker automatically selects the correct architecture for your system.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Community

Production Deployment

System Requirements

Minimum:

  • CPU: 2 cores
  • RAM: 2GB
  • Storage: 50GB SSD
  • Network: 1 Mbps

Recommended:

  • CPU: 4 cores
  • RAM: 8GB
  • Storage: 200GB SSD
  • Network: 10 Mbps

Configuration

See the Environment Variables section above for a complete list of all configuration options.

Quick configuration example:

# Create .env file
cat > .env << EOF
NETWORK=mainnet
P2P_ADDR=0.0.0.0:8333
RPC_ADDR=0.0.0.0:8545
LOG_LEVEL=info
LOG_FILE=/var/log/obsidian/obsidian.log
SOLO_MINING=true
MINER_ADDRESS=your_address_here
MAX_PEERS=125
BAN_DURATION=24h
DATA_DIR=/var/lib/obsidian
EOF

Security Best Practices

  1. Run as non-root user: The Docker image uses a dedicated user
  2. Use firewall rules: Only expose necessary ports
  3. Enable rate limiting: RPC requests are rate-limited by default
  4. Regular backups: Backup your data directory regularly
  5. Monitor logs: Check logs for suspicious activity
  6. Use HTTPS: Put RPC behind a reverse proxy with TLS
  7. Strong authentication: Implement authentication for RPC access

Monitoring

Check node health:

# Health check endpoint
curl http://localhost:8545/health

# Metrics endpoint
curl http://localhost:8545/metrics

# RPC methods
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}' \
  http://localhost:8545

Backup and Recovery

# Backup blockchain data
docker exec obsidian-node tar czf /backup/obsidian-data.tar.gz /home/obsidian/data

# Restore from backup
docker cp obsidian-data.tar.gz obsidian-node:/tmp/
docker exec obsidian-node tar xzf /tmp/obsidian-data.tar.gz -C /home/obsidian/

Performance Tuning

Go Runtime

Set Go environment variables for optimal performance:

GOGC=50              # Aggressive garbage collection
GOMAXPROCS=4         # Number of CPU cores to use

Database

The node uses BoltDB for blockchain storage. For best performance:

  • Use SSD storage
  • Ensure sufficient disk space
  • Regular database compaction

Troubleshooting

Common Issues

Node won't start:

  • Check logs: docker logs obsidian-node
  • Verify ports are not in use: lsof -i :8333
  • Check disk space: df -h

No peer connections:

  • Check firewall rules
  • Verify seed nodes are reachable
  • Enable Tor if behind NAT
  • IMPORTANT: When connecting nodes in Docker, use internal port (8333) not external mapped port
    • ❌ Wrong: SEED_NODES=192.168.1.10:18333 (external mapped port)
    • ✅ Correct: SEED_NODES=192.168.1.10:8333 (internal container port)
    • Alternative: Use Docker networks and container names instead of IP:port mapping

High memory usage:

  • Reduce MAX_PEERS
  • Adjust GOGC value
  • Check for memory leaks in logs

Recent Updates

v1.2.4 (Latest)

  • P2P: Increased handshake timeout from 30s to 60s for better network stability
  • Debugging: Added comprehensive debug logging for P2P handshake process
  • Reliability: Improved peer connection reliability on slow networks

v1.2.3

  • Logging: Replaced emojis with text labels for better terminal compatibility
  • Format: [MINING], [OK], [SUCCESS], [ERROR], [BROADCAST], [LAUNCH], [PEER]
  • Compatibility: Works on all terminals and logging systems
  • Multi-arch: linux/amd64 and linux/arm64 support

v1.2.2

  • Logging: Consolidated startup logs into single comprehensive line
  • Monitoring: All critical info in one line (Network, PoW, Tor, P2P, Mining, Height)
  • UX: Dramatically reduced log spam when running multiple nodes
  • Documentation: Complete environment variables reference with examples

v1.2.1

  • Environment Variables: Added comprehensive documentation for all configuration options
  • Logging: Improved structured logging with reduced verbosity

v1.2.0 (Production Release)

  • Security: Rate limiting, request validation, non-root Docker user
  • Logging: Structured logging with file output support
  • Monitoring: Health check and metrics endpoints
  • Docker: Optimized multi-stage build with security hardening
  • Configuration: Comprehensive environment variable support
  • Error Handling: Improved error handling and graceful shutdown
  • Resource Management: Memory and CPU limits in Docker Compose
  • Testing: All tests passing with increased coverage

v1.1.0

  • Enhanced validation and token mint processing
  • Complete token management features (minting, burning, ownership transfer)
  • Improved security and vulnerability fixes
  • P2P networking tests and improvements
  • Updated dependencies

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

14 tags

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages