DotOne Smart Chain

DotOne Smart Chain is a custom EVM-compatible blockchain based on a fork of bnb-chain/bsc.

The project is built on top of the go-ethereum codebase and keeps compatibility with Ethereum smart contracts, Ethereum tooling, and the broader EVM development ecosystem. Because the client is derived from go-ethereum, many tools, binaries, and documents still use Ethereum naming conventions, such as geth.

DotOne Smart Chain inherits the BSC client architecture and its EVM-compatible execution environment. It also keeps the core client structure, command-line tooling, and node operation model used by the upstream project.

DotOne Smart Chain is:

• A self-sovereign blockchain: Provides network execution and validation through its own blockchain infrastructure.
• EVM-compatible: Supports Ethereum smart contracts and common Ethereum tooling.
• Built from a proven client base: Based on the BSC/go-ethereum client architecture.

Release Types

There are three types of releases, each with a clear purpose and version scheme:

• 1. Stable Release: Production-ready builds for most users. Format: v<Major>.<Minor>.<Patch>, example: v1.5.19.
• 2. Feature Release: Early access to a single feature without affecting the core product. Format: v<Major>.<Minor>.<Patch>-feature-<FeatureName>, example: v1.5.19-feature-SI.
• 3. Preview Release: Early builds for users who want to test the latest code. Format: v<Major>.<Minor>.<Patch>-<Meta>, where the meta value indicates maturity: alpha, beta, or rc.

Key Features

Proof of Staked Authority

Proof-of-Work has been used as a practical mechanism for decentralized networks, but it is resource-intensive and requires a large number of participants to maintain security.

Proof-of-Authority provides improved efficiency and some defense against 51% attacks, while tolerating certain levels of Byzantine behavior from malicious or compromised participants. However, traditional PoA systems are often criticized for being less decentralized because a limited set of validators is responsible for block production.

Some blockchains use delegated staking mechanisms to allow token holders to vote for validator sets. This can improve decentralization and support community governance.

The upstream BSC implementation combines delegated staking concepts with Proof-of-Authority through the Parlia consensus engine:

1. Blocks are produced by a limited set of validators.
2. Validators take turns producing blocks in a PoA-style manner, similar to Ethereum's Clique consensus engine.
3. Validator sets can be updated through staking-based governance logic.
4. The consensus engine can interact with system contracts for validator updates, revenue distribution, slashing, and liveness logic.

Native Token

The native token of DotOne Smart Chain is used in the same way that ETH is used on Ethereum.

The native token is used to:

1. Pay gas to deploy or invoke smart contracts on DotOne Smart Chain.

Building the Source

Many of the following instructions are the same as, or similar to, go-ethereum.

For prerequisites and detailed build instructions, read the Installation Instructions.

Building geth requires Go version 1.24 or later and a C compiler such as GCC 5 or higher. You can install them using your preferred package manager.

After the dependencies are installed, run:

make geth

Or build the full suite of utilities:

make all

If you see the following error when running a self-built binary:

Caught SIGILL in blst_cgo_init, consult <blst>/bindinds/go/README.md.

Try adding the following environment variables and build again:

export CGO_CFLAGS="-O -D__BLST_PORTABLE__" 
export CGO_CFLAGS_ALLOW="-O -D__BLST_PORTABLE__"

Executables

The dotone-chain project includes several wrappers and executables in the cmd directory.

Command	Description
geth	Main DotOne Smart Chain client binary. It is the entry point into the network and can run as a full node, archive node, or light node. It exposes JSON-RPC interfaces over HTTP, WebSocket, and IPC transports. Use geth --help or the CLI page for command-line options.
clef	Stand-alone signing tool that can be used as a backend signer for geth.
devp2p	Utilities for interacting with nodes at the networking layer without running a full blockchain node.
abigen	Source code generator that converts Ethereum contract definitions into type-safe Go packages. It works with Ethereum contract ABIs and can also accept Solidity source files. See the Native DApps page for details.
bootnode	Lightweight node discovery tool. It participates in the discovery protocol but does not run higher-level blockchain protocols. It can be used as a bootstrap node for private networks.
evm	Developer utility for running EVM bytecode snippets in a configurable environment. It is useful for isolated debugging of EVM opcodes, for example evm --code 60ff60ff --debug run.
rlpdump	Developer utility for converting binary RLP dumps into a readable hierarchical format, for example rlpdump --hex CE0183FFFFFFC4C304050583616263.

Running geth

Going through every command-line flag is outside the scope of this README. For the full list of options, see the CLI documentation.

The examples below show common ways to run a geth instance.

Hardware Requirements

Hardware requirements depend on the target network, sync mode, database size, and node role.

For a full node on mainnet, the upstream requirements include:

• A VPS running a recent version of macOS, Linux, or Windows.
• 3 TB of free disk space as of December 2023, using SSD storage such as gp3, 8k IOPS, 500 MB/s throughput, and read latency below 1 ms. If the node is started with snap sync, NVMe SSD is recommended.
• 16 CPU cores and 64 GB of memory.
• Suggested instance types include m5zn.6xlarge or r7iz.4xlarge on AWS, or c2-standard-16 on Google Cloud.
• A broadband internet connection with upload and download speeds of at least 5 MB/s.

For testnet usage, the upstream requirements include:

• A VPS running a recent version of macOS, Linux, or Windows.
• 500 GB of storage.
• 4 CPU cores and 16 GB of memory.

Steps to Run a Full Node

1. Download the pre-built binaries

# Linux
wget $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest |grep browser_ |grep geth_linux |cut -d\" -f4)
mv geth_linux geth
chmod -v u+x geth

# MacOS
wget $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest |grep browser_ |grep geth_mac |cut -d\" -f4)
mv geth_macos geth
chmod -v u+x geth

2. Download the config files

//== mainnet
wget $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest |grep browser_ |grep mainnet |cut -d\" -f4)
unzip mainnet.zip

//== testnet
wget $(curl -s https://api.github.com/repos/bnb-chain/bsc/releases/latest |grep browser_ |grep testnet |cut -d\" -f4)
unzip testnet.zip

3. Download snapshot

Download the latest chaindata snapshot from here. Follow the guide to structure your files.

4. Start a full node

## It will run with Path-Base Storage Scheme by default and enable inline state prune, keeping the latest 600000 blocks' history state.
./geth --config ./config.toml --datadir ./node  --cache 8000 --rpc.allow-unprotected-txs --history.transactions 0

## It is recommend to run fullnode with `--tries-verify-mode none` if you want high performance and care little about state consistency.
./geth --config ./config.toml --datadir ./node  --cache 8000 --rpc.allow-unprotected-txs --history.transactions 0 --tries-verify-mode none

5. Monitor node status

By default, monitor logs from:

./node/bsc.log

When the node starts syncing, you should see output similar to the following:

t=2022-09-08T13:00:27+0000 lvl=info msg="Imported new chain segment"             blocks=1    txs=177   mgas=17.317   elapsed=31.131ms    mgasps=556.259  number=21,153,429 hash=0x42e6b54ba7106387f0650defc62c9ace3160b427702dab7bd1c5abb83a32d8db dirty="0.00 B"
t=2022-09-08T13:00:29+0000 lvl=info msg="Imported new chain segment"             blocks=1    txs=251   mgas=39.638   elapsed=68.827ms    mgasps=575.900  number=21,153,430 hash=0xa3397b273b31b013e43487689782f20c03f47525b4cd4107c1715af45a88796e dirty="0.00 B"
t=2022-09-08T13:00:33+0000 lvl=info msg="Imported new chain segment"             blocks=1    txs=197   mgas=19.364   elapsed=34.663ms    mgasps=558.632  number=21,153,431 hash=0x0c7872b698f28cb5c36a8a3e1e315b1d31bda6109b15467a9735a12380e2ad14 dirty="0.00 B"

6. Interact with a full node

You can start the built-in interactive JavaScript console by using the trailing console subcommand.

The console allows interaction through web3 methods and geth management APIs.

Note: The web3 version bundled with geth is old and may not match the latest official documentation.

This tool is optional. If you do not start the console directly, you can attach to an already running geth instance with:

geth attach

7. More

For more details, see the upstream documentation about running a node and becoming a validator.

Note: Although some internal protections help prevent transactions from crossing between different networks, always use separate accounts for test and production environments. Unless accounts are manually moved, geth separates networks by default and does not make accounts available across them.

Configuration

Instead of passing many flags directly to the geth binary, you can provide a configuration file:

$ geth --config /path/to/your_config.toml

To see how the configuration file should look, use the dumpconfig subcommand to export your current configuration:

$ geth --your-favourite-flags dumpconfig

Programmatically Interfacing with geth Nodes

Developers often need to interact with geth through applications instead of the interactive console.

geth supports JSON-RPC APIs, including standard Ethereum APIs, geth-specific APIs, and the BSC JSON-RPC API reference in this repository:

rpc/json-rpc-api.md

These APIs can be exposed over HTTP, WebSocket, and IPC transports. IPC uses UNIX sockets on UNIX-based platforms and named pipes on Windows.

The IPC interface is enabled by default and exposes all APIs supported by geth. HTTP and WebSocket interfaces must be enabled manually and expose only a subset of APIs for security reasons.

HTTP and WebSocket JSON-RPC options include:

• --http Enable the HTTP-RPC server.
• --http.addr HTTP-RPC server listening interface. Default: localhost.
• --http.port HTTP-RPC server listening port. Default: 8545.
• --http.api APIs offered over the HTTP-RPC interface. Default: eth,net,web3.
• --http.corsdomain Comma-separated list of domains that may send cross-origin requests.
• --ws Enable the WebSocket RPC server.
• --ws.addr WebSocket RPC server listening interface. Default: localhost.
• --ws.port WebSocket RPC server listening port. Default: 8546.
• --ws.api APIs offered over the WebSocket RPC interface. Default: eth,net,web3.
• --ws.origins Origins from which to accept WebSocket requests.
• --ipcdisable Disable the IPC-RPC server.
• --ipcpath Filename for the IPC socket or pipe within the datadir.

Use your preferred programming language, libraries, or tools to connect to a geth node over HTTP, WebSocket, or IPC. All transports use JSON-RPC, and the same connection can be reused for multiple requests.

Security note: Understand the risks before exposing HTTP or WebSocket RPC interfaces. Publicly exposed APIs can be targeted by attackers. Locally exposed APIs can also be accessed by browser tabs, which means malicious web pages may attempt to interact with local RPC endpoints.

Operating a Private Network

• BSC-Deploy: Deployment tool for setting up BNB Smart Chain-based networks.

Running a Bootnode

Bootnodes are lightweight nodes that are not behind a NAT and run only the discovery protocol. When a node starts, it logs its enode, which is a public identifier that other nodes can use to connect.

First, create a bootnode key:

bootnode -genkey boot.key

Then use the key to start a bootnode:

bootnode -nodekey boot.key -addr :30311 -network bsc

The port passed to -addr is arbitrary.

The bootnode command returns logs similar to the following:

enode://3063d1c9e1b824cfbb7c7b6abafa34faec6bb4e7e06941d218d760acdd7963b274278c5c3e63914bd6d1b58504c59ec5522c56f883baceb8538674b92da48a96@127.0.0.1:0?discport=30311
Note: you're using cmd/bootnode, a developer tool.
We recommend using a regular node as bootstrap node for production deployments.
INFO [08-21|11:11:30.687] New local node record                    seq=1,692,616,290,684 id=2c9af1742f8f85ce ip=<nil> udp=0 tcp=0
INFO [08-21|12:11:30.753] New local node record                    seq=1,692,616,290,685 id=2c9af1742f8f85ce ip=54.217.128.118 udp=30311 tcp=0
INFO [09-01|02:46:26.234] New local node record                    seq=1,692,616,290,686 id=2c9af1742f8f85ce ip=34.250.32.100  udp=30311 tcp=0

Contribution

Thank you for considering contributing to the source code.

If you would like to contribute to dotone-chain, please fork the repository, make your changes, commit them, and open a pull request for review.

For larger or more complex changes, discuss the change with the maintainers before opening a pull request. This helps ensure that the change is aligned with the project and makes the review process easier.

Please make sure your contributions follow these guidelines:

• Code must follow the official Go formatting guidelines and use gofmt.
• Code should be documented according to the official Go commentary guidelines.
• Pull requests should be based on and opened against the master branch.
• Commit messages should be prefixed with the package or packages they modify.
  • Example: eth, rpc: make trace configs optional

For more details about configuring your environment, managing dependencies, and testing, see the Developers' Guide.

License

The library code, meaning all code outside the cmd directory, is licensed under the GNU Lesser General Public License v3.0, also included in this repository in the COPYING.LESSER file.

The binaries, meaning all code inside the cmd directory, are licensed under the GNU General Public License v3.0, also included in this repository in the COPYING file.