Conflux DevKit provides an easy-to-setup development environment for the Conflux blockchain spaces (Core Space and ESpace EVM).
It leverages Docker to create a devcontainer with all necessary tools, dependencies, and configurations pre-installed, ensuring a seamless and consistent development experience.
This repository offers a minimal setup and serves as a foundation for creating more task-specific repositories, such as a Hardhat repository or a frontend template repository.
- Pre-configured development environment for Conflux Core, ESpace, and PoS.
- Simplified setup with all dependencies installed.
- Consistent and isolated development environment.
- Integrated OpenVSCode server for a web-based development experience.
- Compatibility with GitHub Codespaces and VS Code's devcontainer feature.
There are several ways to reuse the code from this repository. We recommend the following method:
- Download the zip file of the template branch: template.
- Extract the contents of the zip file.
- Follow the instructions in the README.md file to set up your project.
- Initialize your new Git repository from this template.
Using the Dockerfile and develop.toml.template, the Docker instance will create an independent chain.
The independent chain will be reachable with the following RPC endpoints, which can be added to Fluent (Core and eSpace) or Metamask (eSpace) wallet:
- Core:
http://localhost:12537
(or Codespace host instead of localhost) - ESpace:
http://localhost:8545
(or Codespace host instead of localhost)
You can test the endpoint with the following command from your local system:
curl --location 'http://localhost:12537' --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"cfx_clientVersion","params":[],"id":67}'
The response should look like this:
{
"jsonrpc": "2.0",
"result": "conflux-rust/v2.4.0-205095d-20240628/x86_64-linux-gnu/rustc1.77.2",
"id": 67
}
During the image build process, the official conflux-rust image will be used to install the precompiled binary, and all relevant configuration and data directories will be located in the /opt/conflux/
folder and accessible to a Non-Root user.
Five genesis account private keys will be created in the same folder, and the genesis account will be funded with 10000 CFX. Details can be found in /opt/conflux/genesis_secrets.txt
or by using the devkit -l
command.
You can import these accounts into your wallet, or you can add your development private key to this file before starting the Conflux node.
To start the independent chain in the devcontainer setup, open the terminal in the VS Code interface (this applies to both locally installed VS Code and the web-based version in Codespaces or OpenVSCode-Server) and use the following command:
devkit --start
To stop the node:
devkit --stop
Once the independent chain is running, you can open another terminal and use the devkit
utility for various operations.
Usage: devkit [options]
DevKit CLI utils
Options:
-V, --version output the version number
-l, --list List genesis accounts
-b, --balance Balance of the genesis accounts
-f, --faucet [value...] Faucet <amount> <address>
-e, --eSpaceGenesis Transfer from Core genesis address to eSpace
-g, --generateGenesis [value] Generate genesis addresses
--start Start the development node
--stop Stop the development node
--status Show the node status
--logs Show the node logs
--stderr Show the errors the node produced in the stderr
-h, --help display help for command
To transfer funds from all the genesis Core addresses to their ESpace addresses, use the following command:
devkit -e
This command executes a script that reads the genesis private keys and uses them to call the crossSpaceCall internal contract.
To send CFX to a specific account using the funds available to the miner account, use the following commands. For example, for Core:
devkit -f 100 net2029:aarphdvpx0b2xyfg56rn0b6m237cjmbkkjre6fcdby
For ESpace:
devkit -f 100 0xAAC38E2c9D8389D0a6df1abB078aC67a2428294a
NOTE: If the amount available is 0, you need to wait a few seconds for the mining rewards to reach the account.
To check the balance of the genesis accounts, use:
devkit -b
- Docker installed on your machine (if used locally).
If you don't need the devcontainer functionality but want to use the devkit setup, you can quickly run a development node with the following command:
docker run -it -p 12537:12537 -p 8535:8535 --rm --name conflux-dev spcfxda/conflux-devkit
This command will run the devkit container and expose the necessary ports. Once the devkit container is running, you can execute the utility scripts described above with exec:
docker exec -it conflux-dev devkit -l
docker exec -it conflux-dev devkit -f 100 0xf1428162e14ec7a29b50210fbaefdb45050ee4dd
docker exec -it conflux-dev devkit -e
You can open this repository in Codespaces using the Codespaces tab under the CODE
button:
After the build and download of the layers are completed, the environment will be ready to use.
After opening the repository folder with VS Code, a popup will appear in the bottom right corner:
Click on the Reopen in Container
button. After the build and download of the layers are completed, your VS Code instance will be inside the devcontainer.
You can confirm this from the status in the bottom left corner that should look like this:
The main configuration file for the devcontainer is devcontainer.json, where you can easily change parameters for building the local Docker image. Here is an excerpt:
{
"name": "Conflux DevKit",
"build": {
"context": "conflux",
"dockerfile": "conflux/Dockerfile",
"args": {
// "NODE_RELEASE": "2.4.0",
// "BASE_IMAGE": "node:20-slim",
// "CONFLUX_NODE_ROOT": "/opt/conflux",
// "USERNAME": "conflux",
// "USER_UID": "1001",
// "USER_GID": "1001"
},
"target": "devkit"
},
"forwardPorts": [3000, 12535, 12537, 8545, 8546]
}
Parameter Descriptions:
-
NODE_RELEASE
: Specifies the tag of the official conflux-rust image. This can be changed to point to a different hardfork version of the binary. -
BASE_IMAGE
: Defines the base image used for the development environment. By default,node:20-slim
is chosen for compatibility. This can be changed to your preferred base image, although some amendments to the Dockerfile may be necessary. -
CONFLUX_NODE_ROOT
: Sets the destination folder inside the container for all the node data. -
USERNAME
,USER_UID
,USER_GID
: Ensure you set the correctUSERNAME
,USER_UID
, andUSER_GID
to match your system user and group. This facilitates smoother operation of the Docker container by preventing file permission conflicts.
The repository includes the following directories and files:
To customize the behavior of the devcontainer, modify the files located under the .devcontainer/conflux directory.
Here's the structure of the devcontainer:
.
├── conflux
│ ├── Dockerfile // Dockerfile divided into three sections: release, devkit, openvscode
│ ├── templates
│ │ ├── develop.toml.template // Conflux Node configuration
│ │ ├── log.yaml.template // Conflux Node log configuration
│ │ ├── pos_config.yaml.template // Conflux Node PoS configuration
│ │ └── sh
│ │ └── dev_node.sh.template // Shell wrappers for the Node execution
│ └── utils // devkit Utility written with js-conflux-sdk
│ ├── eslint.config.mjs
│ ├── package.json
│ ├── package-lock.json
│ ├── src
│ │ ├── index.ts
│ │ └── utils.ts
│ └── tsconfig.json
└── devcontainer.json
After making changes to any file to suit your preferences, rebuild the container by following these steps:
-
In VS Code, navigate to the bottom left corner and click on the icon that indicates the current status of the devcontainer setup.
-
From the menu that appears, select
Rebuild container
.
This rebuilds the devcontainer with your modified settings, ensuring that your changes take effect in the development environment.
To quickly start the DevKit server with OpenVSCode Server, use the following command:
docker run -it -p 5000:5000 -p 12537:12537 -p 8535:8535 -v "$(pwd):/workspaces:cached" --rm --name devkit-server spcfxda/conflux-devkit-server
This command performs the following actions:
-it
: Runs the container in interactive mode with a TTY enabled, allowing you to interact with the container via the command line.-p 5000:5000
: Maps port 5000 on your local machine to port 5000 in the container, providing access to the OpenVSCode Server.-p 12537:12537
: Maps port 12537 on your local machine to port 12537 in the container, providing access to the Conflux Core RPC endpoint.-p 8535:8535
: Maps port 8535 on your local machine to port 8535 in the container, providing access to the Conflux ESpace RPC endpoint.-v "$(pwd):/workspaces:cached"
: Mounts the current directory on your local machine ($(pwd)
) to the/workspaces
directory in the container with caching enabled, allowing you to work with your local files inside the container.--rm
: Automatically removes the container when it is stopped.--name devkit-server
: Names the running containerdevkit-server
for easier management and reference.
Consider that $(pwd)
is a linux command, in windows you will have to substitute it with the full path of the directory you want to map.
If you need to customize the Dockerfile or some of its configuration you can follow these steps:
- Clone the repository:
git clone https://github.com/your-repo/conflux-devkit.git
cd conflux-devkit
- After you saved the changes you needed, to start the container with the Conflux node and OpenVSCode server, use the following commands:
docker build .devcontainer/conflux --tag "conflux-devkit-server"
docker run -it -p 5000:5000 -p 12537:12537 -p 8545:8545 -v "$(pwd):/workspaces:cached" -d conflux-devkit-server --name conflux-devkit-server
Open your browser and navigate to http://localhost:5000
to access the OpenVSCode server.
The Dockerfile for the devcontainer includes several build arguments (ARG) and environment variables (ENV) that control various aspects of the build and runtime configuration. Below is a description of each:
Build Arguments (ARG):
NODE_RELEASE
: Specifies the tag of the official Conflux Rust image. This can be modified to use a different version of the binary.BASE_IMAGE
: Defines the base image used for the development environment. The default isnode:20-slim
for compatibility, but it can be changed to another base image if necessary.CONFLUX_NODE_ROOT
: Sets the directory inside the container where all node data will be stored.CONFIG_PATH
: Specifies the path to the main configuration file for the Conflux node.USERNAME
: Defines the default username inside the container. This is set tonode
.USER_UID
: Sets the user ID for the default user.USER_GID
: Sets the group ID for the default user, which is the same as the user ID.SERVER_VERSION
: Specifies the version of OpenVSCode server to be used.SERVER_VERSION_NAME
: Defines the name of the OpenVSCode server version.SERVER_VERSION_URL
: URL to download the specified version of the OpenVSCode server.OPENVSCODE_SERVER_ROOT
: Sets the directory inside the container where OpenVSCode server will be installed.
Environment Variables (ENV):
CHAIN_ID=2029
: Sets the chain ID for the Conflux node.EVM_CHAIN_ID=2030
: Sets the chain ID for the EVM space.CONFLUX_NODE_ROOT=${CONFLUX_NODE_ROOT}
: Ensures theCONFLUX_NODE_ROOT
path is set as an environment variable.CONFIG_PATH=${CONFIG_PATH}
: Ensures theCONFIG_PATH
is set as an environment variable.LANG=C.UTF-8
: Sets the language to UTF-8.LC_ALL=C.UTF-8
: Ensures all locale settings use UTF-8.HOME=/workspaces
: Sets the home directory inside the container.EDITOR=code
: Sets the default editor to VS Code.VISUAL=code
: Sets the default visual editor to VS Code.GIT_EDITOR="code --wait"
: Sets VS Code as the editor for Git commits.OPENVSCODE_SERVER_ROOT=${OPENVSCODE_SERVER_ROOT}
: Ensures theOPENVSCODE_SERVER_ROOT
path is set as an environment variable.
These arguments and environment variables provide a flexible way to configure the development environment to suit different needs and preferences.
3000
: Default port for Node application.12535
: Core WebSocket RPC.12537
: Core HTTP RPC (Endpoint port for Fluent wallet).8545
: ESpace HTTP RPC (Endpoint port for Fluent/MetaMask wallet).8546
: ESpace WebSocket RPC.5000
: Port for OpenVSCode server.
Passwordless sudo is configured for the user specified by USERNAME. This configuration allows the user to execute commands with root privileges without needing to enter a password.
Using sudo
you can install new packages with apt or make system modifications as needed. However, please note that any changes made this way will be lost if the image is rebuilt. To ensure that your changes persist, you should amend the Dockerfile accordingly.
Contributions are welcome! Please refer to the Contributing guideline and the Code of conduct.
This project is licensed under the MIT License. See the LICENSE file for details.
For more information, visit the official documentation.