Oroz Blockchain

Oroz is a modern Proof-of-Stake (PoS) blockchain platform with advanced governance, delegation, and configurable protocol parameters. Built in Go, it provides enterprise-grade security, scalability, and developer-friendly tools.

🌟 Key Features

• Proof-of-Stake Consensus: Stake-weighted proposer selection with BFT finality
• On-Chain Governance: Validator voting for protocol parameter changes
• Delegation System: Stake delegation with configurable validator commissions
• Slashing Protection: Double-signing detection and downtime penalties
• Configurable Parameters: All protocol parameters updatable via governance
• Rich API: 20+ REST endpoints for blockchain interaction
• P2P Network: Automatic peer discovery and sync mechanism
• Developer Tools: CLI tools for key management and transactions

📋 System Requirements

• Go: 1.21 or higher
• Storage: 10GB+ available space
• Memory: 4GB+ RAM recommended
• Network: Internet connection for P2P networking

🚀 Quick Start

1. Clone and Build

git clone https://github.com/mine3krish/oroz-blockchain.git
cd oroz-blockchain
go mod download
go build -o cmd/oroz-node cmd/node/main.go
go build -o cmd/orozkey cmd/orozkey/main.go
go build -o cmd/oroztx cmd/oroztx/main.go

2. Generate Wallet

./bin/orozkey --action new --file alice.wallet

3. Configure Genesis

Edit configs/genesis.json with your wallet address and initial stake.

4. Start Node

./bin/oroz-node --config config.json

5. Send Transaction

./bin/oroztx --wallet alice.wallet --to 0xRECIPIENT --amount 1000000000000000000

🏗️ Architecture

Core Components

• State Management: LevelDB-based persistent state with account balances, stakes, and governance data
• Consensus Engine: Stake-weighted proposer selection with checkpoint voting
• Transaction Pool: In-memory mempool with validation and fee estimation
• P2P Network: TCP-based networking with peer discovery and block propagation
• REST API: HTTP server for external integrations and wallet interactions

Transaction Types

Type	Description	Required Fields
transfer	Send tokens between accounts	to, amount
stake	Stake tokens for validation	amount
unstake	Unstake tokens	amount
register_validator	Register as validator	amount, pubkey
delegate	Delegate stake to validator	to, amount
undelegate	Remove delegation	to, amount
param_change_proposal	Propose parameter change	to (param), amount (value)
vote_param_change	Vote on proposal	to (param), data (yes/no)

🔧 Configuration

Node Configuration (config.json)

{
  "state_path": "data/state.db",
  "block_path": "data/blocks.db", 
  "genesis_path": "configs/genesis.json",
  "wallet_path": "alice.wallet",
  "port": 8080,
  "api_port": 8001,
  "peers": ["localhost:8081"]
}

Protocol Parameters

All configurable via governance:

• block_reward: Block reward amount (wei)
• block_time: Block interval (seconds)
• finality_depth: Blocks for finality
• min_validator_stake: Minimum stake to become validator
• max_validators: Maximum active validators
• payout_interval: Reward distribution interval (blocks)
• commission: Default validator commission (%)
• downtime_window: Blocks to track for downtime
• fee_per_byte: Transaction fee per byte

📡 API Reference

Account Management

• GET /balance/{address} - Get account balance
• GET /account/{address} - Get account details (balance, nonce, stake)
• GET /address/{address} - Same as account

Transactions

• POST /sendtx - Broadcast transaction
• GET /tx/{hash} - Get transaction by hash
• GET /addresstxns/{address} - Get transactions for address
• POST /estimateFee - Estimate transaction fee

Blockchain Data

• GET /block/{height} - Get block by height
• GET /blocks?start={}&end={} - Get block range
• GET /blocktxns/{height} - Get transactions in block
• GET /chaininfo - Get blockchain info
• GET /mempool - Get pending transactions

Validators & Staking

• GET /validators - List all validators
• GET /validator/{address} - Get validator details
• POST /register_validator - Register as validator
• GET /delegations?validator={} - Get delegations to validator
• GET /delegator_rewards?delegator={} - Get delegation history

Governance

• POST /param_proposal - Submit parameter change proposal
• POST /param_vote - Vote on proposal
• GET /param_proposals - List all proposals
• GET /param_proposal_status?param={} - Get proposal status
• GET /param_proposal_votes?param={} - Get votes for proposal
• GET /protocol_params - Get current parameters

🏛️ Governance

Proposing Parameter Changes

1. Submit Proposal (validator only):

./bin/oroztx --wallet validator.wallet --type param_change_proposal --to block_reward --amount 2000000000000000000

2. Vote on Proposal (validator only):

./bin/oroztx --wallet validator.wallet --type vote_param_change --to block_reward --data yes

3. Automatic Execution:
   • Changes apply when >2/3 validator stake votes "yes"
   • Proposals expire after 100 blocks if not passed

🔒 Security Features

• Ed25519 Signatures: All transactions cryptographically signed
• Double-Signing Protection: Validators slashed for conflicting blocks/votes
• Downtime Slashing: Validators jailed for missing too many blocks
• Replay Protection: Nonce-based transaction ordering
• Rate Limiting: API endpoints protected against DoS
• Finality: BFT-style checkpoints prevent deep reorganizations

🔧 Development

Building from Source

# Install dependencies
go mod download

# Build all binaries
make build

# Run tests
go test ./...

# Start development node
./bin/oroz-node --genesis configs/genesis.json --wallet alice.wallet

Adding New Transaction Types

1. Add type to tx.go validation
2. Implement logic in Apply() method
3. Add API endpoint in server.go
4. Update documentation

📊 Monitoring

Node Health

# Check node status
curl localhost:8001/chaininfo

# Monitor mempool
curl localhost:8001/mempool

# View validators
curl localhost:8001/validators

Network Stats

• Block height and sync status
• Mempool size and pending transactions
• Connected peers count
• Validator uptime and performance

🐛 Troubleshooting

Common Issues

Node won't start:

• Check genesis file path and format
• Verify wallet file exists and is readable
• Ensure ports are not in use

Transaction rejected:

• Check nonce is correct (/account/{address})
• Verify sufficient balance for amount + fee
• Validate transaction signature and format

Peer connection failed:

• Confirm peer address and port
• Check firewall settings
• Verify both nodes are on same network

Validator not proposing:

• Ensure sufficient stake (>= min_validator_stake)
• Check if jailed (/validator/{address})
• Verify not exceeding max_validators limit

Debug Mode

# Verbose logging
./bin/oroz-node --config config.json --debug

# Manual transaction
./bin/oroztx --wallet test.wallet --to 0xDEADBEEF --amount 1000 --api http://localhost:8001

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Code Style

• Follow Go conventions and gofmt
• Add tests for new features
• Document public APIs
• Update README for user-facing changes

🗺️ Roadmap

• Smart Contracts (EVM compatibility)
• Cross-chain bridges
• Light client support
• Mobile wallet apps
• Consensus algorithm improvements
• Sharding implementation