OpenLedger Ecosystem

Overview

This repository contains the core smart contracts for the OpenLedger ecosystem, featuring the native OPN token, WOPEN and its governance wrapper GOPEN. Built with modern development practices, comprehensive testing, and security-first principles.

Smart Contracts

Open.sol (OPN Token)

• Native token of the Openledger ecosystem with advanced ERC20 capabilities
• Implements EIP-2612 permit functionality for gasless approvals
• Features built-in decimals (18) and standard transfer/approval mechanisms
• Designed with security-first approach following OpenZeppelin standards
• Powers the core functionality of the Openledger ecosystem

GOpen.sol (Governance Token)

• Governance wrapper for OPN tokens maintaining 1:1 backing ratio
• Implements ERC20Votes for on-chain governance capabilities
• Features vote delegation and historical vote tracking through checkpoints
• Allows secure wrapping and unwrapping of OPN tokens
• Protects against common attack vectors with comprehensive security measures

OpenLedgerGovernor.sol (Governance Contract)

• Core on-chain governance contract for protocol upgrades and parameter changes
• Built on OpenZeppelin Governor framework with timelock and role-based access control
• Manages proposal creation, voting, queuing, and execution with transparent lifecycle
• Enforces proposal threshold, voting delay, voting period, quorum, and timelock delay
• Integrates with GOpen token for voting power and supports vote delegation
• Comprehensive test suite ensures security, correctness, and resilience

WOpen.sol (WOPEN Wrapped Ether-Compatible Token)

• Implementation of a wrapped token with deposit and withdrawal capabilities
• Users can deposit Ether to mint WOpen tokens and withdraw Ether by burning them
• Security enhancements: Uses a receive() function to securely handle Ether deposits and prevent fallback-based vulnerabilities like the WETH permit attack
• Compatibility: Built on Solidity 0.6.12 for security and compatibility guarantees
• Fully ERC20-compliant with a 1:1 peg to the native Open token

Network Information

The contracts are deployed on:

• Openledger Testnet (ChainID: 161201)
• Openledger mainnet (ChainID: 1612) (Planned)
• Ethereum Sepolia Testnet
• Ethereum Mainnet (Planned)

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• Git

Quick Start

# Clone the repository
git clone https://github.com/YOUR_USERNAME/openledger.git
cd openledger

# Install dependencies
npm install

# Compile contracts
npm run compile

# Run tests
npm test

# Run specific test suites
npm run test:OPEN
npm run test:GOpen
npm run test:OpenLedgerGovernor

# Generate coverage report
npm run coverage

Development

Available Scripts

# Testing
npm test                    # Run all tests
npm run test:OPEN          # Test OPEN token
npm run test:WOpen         # Test WOPEN token
npm run test:GOpen         # Test GOPEN token
npm run test:OpenLedgerGovernor  # Test governance contracts
npm run coverage           # Generate test coverage report

# Code Quality
npm run lint               # Lint Solidity contracts
npm run lint:fix           # Fix linting issues
npm run format             # Format code with Prettier
npm run format:check       # Check code formatting

# Compilation
npm run compile            # Compile contracts
npm run clean              # Clean build artifacts

# Deployment
npm run deploy:OPEN:hardhat              # Deploy to Hardhat network
npm run deploy:OPEN:sepolia              # Deploy to Sepolia testnet
npm run deploy:WOPEN:openledger-testnet  # Deploy WOPEN to testnet
npm run deploy:GOPEN:openledger-testnet  # Deploy GOPEN to testnet
npm run deploy:OpenLedgerGovernor:openledger-testnet  # Deploy Governor to testnet

# Verification
npx hardhat verify --list-networks       # List available networks

Environment Setup

1. Copy .env-sample to .env:

   cp .env-sample .env

2. Fill in your environment variables:

   SEPOLIA_RPC_URL=your_sepolia_rpc_url
   OPEN_RPC_URL=your_openledger_testnet_rpc_url
   SCAN_API_KEY_OPN=your_scan_api_key
   SCAN_API_KEY_SEPOLIA=your_sepolia_scan_api_key
   PRIVATE_KEY=your_private_key_for_deployment

3. For mainnet deployments, use Hardhat vars:

   npx hardhat vars set RPC_KEY_ETHEREUM your_mainnet_rpc_key
   npx hardhat vars set SCAN_API_KEY_ETHEREUM your_mainnet_scan_api_key

Development Tools

This project uses modern development tools:

• Prettier: Code formatting
• Solhint: Solidity linting
• Hardhat: Development environment
• Solidity Coverage: Test coverage reporting
• GitHub Actions: CI/CD pipeline

Code Quality

# Run all quality checks
npm run lint
npm run format:check
npm test

Deployment

Deploy to Testnet

# Deploy OPEN token to Sepolia
npm run deploy:OPEN:sepolia

# Deploy WOPEN to OpenLedger testnet
npm run deploy:WOPEN:openledger-testnet

# Deploy GOPEN to OpenLedger testnet
npm run deploy:GOPEN:openledger-testnet

# Deploy Governor to OpenLedger testnet
npm run deploy:OpenLedgerGovernor:openledger-testnet

Verify Contracts

After deployment, verify contracts on block explorers:

npx hardhat verify --network <network> <contract_address> <constructor_args>

Security

Security Features

• ✅ All contracts use OpenZeppelin's battle-tested implementations
• ✅ Comprehensive test coverage for all functionality
• ✅ Follows best practices for smart contract development
• ✅ Reentrancy protection implemented
• ✅ Access control mechanisms in place
• ✅ Security audits completed (see audit/ directory)

Reporting Security Issues

Please do not open public issues for security vulnerabilities.

Instead, please email security@openledger.xyz with:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

See SECURITY.md for more details.

Security Audits

All contracts have been professionally audited:

• OpenLedger OPEN Token - Final Report
• OpenLedger WOPEN & GOPEN - Final Report

Audit reports are available in the audit/ directory.

Documentation

Contract Documentation

• Open Token Documentation - Native OPN token implementation
• WOPEN Token Documentation - Wrapped token implementation
• GOpen Token Documentation - Governance token with voting
• Governor Documentation - On-chain governance system

Additional Resources

• Contributing Guidelines - How to contribute to the project
• Security Policy - Security reporting and best practices
• Changelog - Version history and changes

Project Structure

openledger/
├── contracts/          # Smart contracts
│   ├── Open.sol       # Native OPN token
│   ├── WOPEN.sol      # Wrapped token
│   ├── GOPEN.sol      # Governance token
│   ├── OpenLedgerGovernor.sol  # Governance contract
│   └── mock/          # Mock contracts for testing
├── test/              # Test files
│   ├── governance/    # Governance tests
│   └── ...            # Other test files
├── docs/              # Documentation
├── ignition/          # Deployment scripts
├── audit/             # Security audit reports
└── .github/           # GitHub Actions workflows

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support:

• Open an issue on GitHub
• Email: support@openledger.xyz
• Documentation: docs/

Acknowledgments

• Built with Hardhat
• Uses OpenZeppelin Contracts
• Inspired by industry best practices

---

Note: Remember to update YOUR_USERNAME in package.json, README.md, and other files with your actual GitHub username or organization name.