mirror of
https://github.com/luxfi/evm.git
synced 2026-09-24 00:27:44 +00:00
263 lines
8.8 KiB
Markdown
263 lines
8.8 KiB
Markdown
# Lux EVM
|
|
|
|
[](https://pkg.go.dev/github.com/luxfi/evm)
|
|
[](https://goreportcard.com/report/github.com/luxfi/evm)
|
|
[](https://github.com/luxfi/geth/actions/workflows/lint-tests-release.yml)
|
|
[](https://github.com/luxfi/geth/actions/workflows/codeql-analysis.yml)
|
|
|
|
## Overview
|
|
|
|
The Lux EVM is a high-performance Ethereum Virtual Machine implementation optimized for the Lux Network. It provides full Ethereum compatibility while leveraging Lux's advanced consensus and networking capabilities.
|
|
|
|
[Lux](https://docs.lux.network/overview/getting-started/lux-platform) is a network composed of multiple blockchains.
|
|
Each blockchain is an instance of a Virtual Machine (VM), much like an object in an object-oriented language is an instance of a class.
|
|
That is, the VM defines the behavior of the blockchain.
|
|
|
|
EVM is the [Virtual Machine (VM)](https://docs.lux.network/learn/lux/virtual-machines) that defines the EVM Contract Chains. Lux EVM is a customizable version of [Lux Ethereum VM (C-Chain)](https://github.com/luxfi/geth).
|
|
|
|
This chain implements the Ethereum Virtual Machine and supports Solidity smart contracts as well as most other Ethereum client functionality.
|
|
|
|
### Key Features
|
|
|
|
- **⚡ High Performance**: Sub-second finality with high throughput
|
|
- **🔄 Full EVM Compatibility**: Deploy existing Ethereum dApps without modification
|
|
- **🏗️ Customizable**: Configure gas limits, fees, and network parameters
|
|
- **🔐 Secure**: Built on Avalanche consensus for maximum security
|
|
- **📊 Efficient**: Optimized state management and storage
|
|
|
|
## Building
|
|
|
|
The EVM runs in a separate process from the main Lux process and communicates with it over a local gRPC connection.
|
|
|
|
### Lux Compatibility
|
|
|
|
```text
|
|
[v0.1.0] [email protected] (Protocol Version: 9)
|
|
[v0.1.1-v0.1.2] [email protected] (Protocol Version: 10)
|
|
[v0.2.0] [email protected] (Protocol Version: 11)
|
|
[v0.2.1] [email protected] (Protocol Version: 12)
|
|
[v0.2.2] [email protected] (Protocol Version: 14)
|
|
[v0.2.3] [email protected] (Protocol Version: 15)
|
|
[v0.2.4] [email protected] (Protocol Version: 15)
|
|
[v0.2.5] [email protected] (Protocol Version: 15)
|
|
[v0.2.6] [email protected] (Protocol Version: 15)
|
|
[v0.2.7] [email protected] (Protocol Version: 15)
|
|
[v0.2.8] [email protected] (Protocol Version: 15)
|
|
[v0.2.9] [email protected] (Protocol Version: 15)
|
|
[v0.3.0] [email protected] (Protocol Version: 16)
|
|
[v0.4.0] [email protected] (Protocol Version: 17)
|
|
[v0.4.1] [email protected] (Protocol Version: 18)
|
|
[v0.4.2] [email protected] (Protocol Version: 18)
|
|
[v0.4.3] [email protected] (Protocol Version: 19)
|
|
[v0.4.4] [email protected] (Protocol Version: 19)
|
|
[v0.4.5] [email protected] (Protocol Version: 20)
|
|
[v0.4.6] [email protected] (Protocol Version: 20)
|
|
[v0.4.7] [email protected] (Protocol Version: 21)
|
|
[v0.4.8] [email protected] (Protocol Version: 22)
|
|
[v0.4.9] [email protected] (Protocol Version: 23)
|
|
[v0.4.10] [email protected] (Protocol Version: 23)
|
|
[v0.4.11] [email protected] (Protocol Version: 24)
|
|
[v0.4.12] [email protected] (Protocol Version: 24)
|
|
[v0.5.0] [email protected] (Protocol Version: 25)
|
|
[v0.5.1] [email protected] (Protocol Version: 26)
|
|
[v0.5.2] [email protected] (Protocol Version: 26)
|
|
[v0.5.3] [email protected] (Protocol Version: 27)
|
|
[v0.5.4] [email protected] (Protocol Version: 28)
|
|
[v0.5.5] [email protected] (Protocol Version: 28)
|
|
[v0.5.6] [email protected] (Protocol Version: 28)
|
|
[v0.5.7] [email protected] (Protocol Version: 29)
|
|
[v0.5.8] [email protected] (Protocol Version: 29)
|
|
[v0.5.9] [email protected] (Protocol Version: 30)
|
|
[v0.5.10] [email protected] (Protocol Version: 30)
|
|
```
|
|
|
|
## API
|
|
|
|
The Lux EVM supports the following API namespaces:
|
|
|
|
- `eth`
|
|
- `personal`
|
|
- `txpool`
|
|
- `debug`
|
|
|
|
Only the `eth` namespace is enabled by default.
|
|
Lux EVM is a simplified version of [Geth VM (C-Chain)](https://github.com/luxfi/geth).
|
|
Full documentation for the C-Chain's API can be found [here](https://docs.lux.network/apis/node/apis/c-chain).
|
|
|
|
## Compatibility
|
|
|
|
The Lux EVM is compatible with almost all Ethereum tooling, including [Remix](https://docs.lux.network/build/dapp/smart-contracts/remix-deploy), [Metamask](https://docs.lux.network/build/dapp/chain-settings), and [Foundry](https://docs.lux.network/build/dapp/smart-contracts/toolchains/foundry).
|
|
|
|
## Differences Between Lux EVM and Lux Geth
|
|
|
|
- Added configurable fees and gas limits in genesis
|
|
- Merged Lux hardforks into the single "Lux EVM" hardfork
|
|
- Removed Atomic Txs and Shared Memory
|
|
- Removed Multicoin Contract and State
|
|
|
|
## Block Format
|
|
|
|
To support these changes, there have been a number of changes to the EVM block format compared to what exists on the C-Chain and Ethereum. Here we list the changes to the block format as compared to Ethereum.
|
|
|
|
### Block Header
|
|
|
|
- `BaseFee`: Added by EIP-1559 to represent the base fee of the block (present in Ethereum as of EIP-1559)
|
|
- `BlockGasCost`: surcharge for producing a block faster than the target rate
|
|
|
|
## Create an EVM Subnet on a Local Network
|
|
|
|
### Clone Subnet-evm
|
|
|
|
First install Go 1.23.9 or later. Follow the instructions [here](https://go.dev/doc/install). You can verify by running `go version`.
|
|
|
|
Set `$GOPATH` environment variable properly for Go to look for Go Workspaces. Please read [this](https://go.dev/doc/code) for details. You can verify by running `echo $GOPATH`.
|
|
|
|
As a few software will be installed into `$GOPATH/bin`, please make sure that `$GOPATH/bin` is in your `$PATH`, otherwise, you may get error running the commands below.
|
|
|
|
Download the `evm` repository into your `$GOPATH`:
|
|
|
|
```sh
|
|
cd $GOPATH
|
|
mkdir -p src/github.com/luxfi
|
|
cd src/github.com/luxfi
|
|
git clone [email protected]:luxdefi/evm.git
|
|
cd evm
|
|
```
|
|
|
|
This will clone and checkout to `master` branch.
|
|
|
|
### Run Local Network
|
|
|
|
To run a local network, it is recommended to use the [lux-cli](https://github.com/luxfi/lux-cli#lux-cli) to set up an instance of EVM on a local Lux Network.
|
|
|
|
There are two options when using the Lux-CLI:
|
|
|
|
1. Use an official EVM release: https://docs.lux.network/subnets/build-first-subnet
|
|
2. Build and deploy a locally built (and optionally modified) version of EVM: https://docs.lux.network/subnets/create-custom-subnet
|
|
|
|
## Configuration
|
|
|
|
### Genesis Configuration
|
|
|
|
Configure your EVM instance through the genesis file:
|
|
|
|
```json
|
|
{
|
|
"config": {
|
|
"chainId": 7777,
|
|
"homesteadBlock": 0,
|
|
"eip150Block": 0,
|
|
"eip155Block": 0,
|
|
"eip158Block": 0,
|
|
"byzantiumBlock": 0,
|
|
"constantinopleBlock": 0,
|
|
"petersburgBlock": 0,
|
|
"istanbulBlock": 0,
|
|
"muirGlacierBlock": 0,
|
|
"subnetEVMTimestamp": 0,
|
|
"feeConfig": {
|
|
"gasLimit": 15000000,
|
|
"targetBlockRate": 2,
|
|
"minBaseFee": 25000000000,
|
|
"targetGas": 15000000,
|
|
"baseFeeChangeDenominator": 36,
|
|
"minBlockGasCost": 0,
|
|
"maxBlockGasCost": 1000000,
|
|
"blockGasCostStep": 200000
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Network Upgrades (v2.0.0+)
|
|
|
|
Starting with version 2.0.0, all network upgrades are active from genesis. For adding future upgrades, see [NETWORK_UPGRADES.md](./NETWORK_UPGRADES.md).
|
|
|
|
## Development
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
go test ./...
|
|
|
|
# Run tests with coverage
|
|
go test -coverprofile=coverage.out ./...
|
|
go tool cover -html=coverage.out
|
|
|
|
# Run specific package tests
|
|
go test ./core/...
|
|
go test ./eth/...
|
|
```
|
|
|
|
### Benchmarking
|
|
|
|
```bash
|
|
# Run benchmarks
|
|
go test -bench=. ./core/vm/...
|
|
go test -bench=. ./core/state/...
|
|
```
|
|
|
|
### Debugging
|
|
|
|
Enable debug APIs in your configuration:
|
|
|
|
```json
|
|
{
|
|
"eth-apis": ["eth", "debug", "net", "web3"]
|
|
}
|
|
```
|
|
|
|
## Performance Tuning
|
|
|
|
### Database Backend
|
|
|
|
The EVM uses BadgerDB by default for optimal performance:
|
|
|
|
```json
|
|
{
|
|
"database-type": "badgerdb",
|
|
"database-cache-size": 2048
|
|
}
|
|
```
|
|
|
|
### State Management
|
|
|
|
Configure state pruning for efficient storage:
|
|
|
|
```json
|
|
{
|
|
"pruning-enabled": true,
|
|
"pruning-blocks-to-keep": 1000,
|
|
"pruning-interval": 3600
|
|
}
|
|
```
|
|
|
|
## Security
|
|
|
|
- Always run nodes with appropriate firewall rules
|
|
- Use secure RPC endpoints with authentication
|
|
- Keep your node software up to date
|
|
- Monitor for security advisories
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guidelines](../CONTRIBUTING.md) for details.
|
|
|
|
1. Fork the repository
|
|
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## Resources
|
|
|
|
- [Lux Documentation](https://docs.lux.network)
|
|
- [Discord Community](https://discord.gg/luxnetwork)
|
|
- [GitHub Issues](https://github.com/luxfi/evm/issues)
|
|
- [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf)
|
|
|
|
## License
|
|
|
|
This project is licensed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for details.
|