# ontology: the official Go implementation of the Ontology chain

> The ontology repository is the reference Go implementation of the Ontology blockchain, providing a node with a full CLI, a separate signature server for signing transactions, multiple consensus algorithms and WASM smart contract support. It is aimed at developers who want to run a node, join a network or build against the chain's tooling.

**ontio/ontology** — Official Go implementation of the Ontology protocol. https://dev-docs.ont.io/#/

- Repository: https://github.com/ontio/ontology
- Stars: 909 · Forks: 310
- Language: Go
- License: LGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/ontio-ontology

## A node, a CLI and a signature server in one build

The repository describes itself as the official Go implementation of the Ontology blockchain, a high-performance public blockchain project and distributed trust collaboration platform. The Ontology MainNet was launched on June 30th, 2018.

What a build produces is the interesting part. After `make all` you get two executables. The first is `ontology`, the primary Ontology node application and CLI, which is both the peer to peer node and the wallet and command line client in one binary. The second is `tools/sigsvr`, the Ontology Signature Server, `sigsvr`, described as an RPC server for signing transactions.

That second binary is the one that shows the project's design assumption. A blockchain node should not hold the private key that authorises a transaction, so the signing operation is split out into a separate service that the node talks to over RPC. It is the same separation you would build by hand for a production deployment, except here it ships in the box.

The repository layout shows the whole system laid out by subsystem: `account/`, `cmd/`, `cmd-tools/`, `common/`, `consensus/`, `core/`, `docker/`, `errors/`, `events/`, `http/`, `merkle/`, `p2pserver/`, `smartcontract/`, `txnpool/`, `validator/`, `vm/`, plus `integrationtest/` and `wasmtest/` directories for the test suites and `config.json` for the node configuration.

The dependency list in go.mod shows the borrowed parts. It pulls `github.com/ethereum/go-ethereum` v1.15.9, `gorilla/websocket`, `prometheus/client_golang`, `syndtr/goleveldb` for the database, `graph-gophers/graphql-go` for the query API, `urfave/cli` for the command line, `holiman/uint256`, `ontio/ontology-crypto` for the cryptographic primitives, `ontio/ontology-eventbus` and `ontio/wagon`, and `dop251/goja`, which is a JavaScript engine, matching the chain's support for JavaScript alongside WASM in its virtual machine.

## Consensus choice and a one second block

The feature list in the README is short and each item maps to a design decision.

There are scalable lightweight universal smart contracts, scalable WASM contract support, a cross-chain interactive protocol, multiple encryption algorithms supported, highly optimized transaction processing speed, P2P link layer encryption as an optional module, multiple consensus algorithms supported, namely VBFT, DBFT, RBFT, SBFT and PoW, and quick block generation time of 1 to 30 seconds.

The consensus list is the one that matters for a node operator. VBFT and the other BFT variants are the permissioned style algorithms where a set of validators agree on blocks, and PoW is the proof of work option. A node therefore has to be configured with the algorithm the network it joins expects, and the difference is not a tuning knob, it is a different protocol.

The block generation range of 1 to 30 seconds is worth reading carefully rather than as a headline. The same chain can produce a block every second or every thirty seconds, and the choice affects how quickly a transaction is confirmed, which is also why the transfer examples later in the README note that the transaction will not be executed before the block is generated and added.

The optional P2P link layer encryption module is a separate thing from the multiple encryption algorithms. One is about confidentiality of the link between nodes and the other is about the cryptographic algorithms the chain supports for signing and key management. They are often conflated when blockchain projects are described, and here they are separate features.

The chain also comes with tooling around it. The README mentions SDKs, the SmartX IDE, an Ontology blockchain explorer, and says the project is maintained by both the Ontology core tech team and community members.

## Building from source and what you get

The Build From Source section lists one prerequisite, Golang version 1.17 or later, and three commands:

```shell
$ git clone https://github.com/ontio/ontology.git
$ cd ontology
$ make all
```

Two cautions are in the README. The code in the `master` branch may not be stable, and new features are still being rapidly developed, so the master branch may be unstable. Stable versions are in the releases section.

The Makefile shows what the build actually does. `VERSION` comes from `git describe --always --tags --long`, and the version string is injected into the binary with `-ldflags`, which is how the binary reports which commit it came from. The `ontology` target builds with `CGO_ENABLED=1`, while `sigsvr` is built without it, and the `abi` target copies the native ABI script's JSON files into `tools/abi`.

There are cross compilation targets too, `ontology-cross` and `tools-cross`, producing Windows, Linux and Darwin amd64 binaries, with `CGO_CFLAGS=-Wno-undef-prefix` set for the Darwin build. A `docker` target is what the README's Docker section uses to build the image.

One detail worth checking before you build: the go.mod declares `go 1.23.0` as the module's Go version, while the README's prerequisites section still says Go 1.17 or later. The README header also names Version 2.5.8 for the binary and 1.17.0 for the library, which is behind the current tags. Treat the module file as the source of truth about the toolchain and the releases section as the source of truth about the code.

## MainNet, TestNet and a PrivateNet on your own machine

The CLI can run nodes for the MainNet, the TestNet and a local PrivateNet, and each mode is a different flag.

The MainNet node is started with no arguments:

```shell
./ontology                          # Linux
./ontology-darwin-amd64             # MacOS
start ontology-windows-amd64.exe    # Windows
```

The TestNet node adds `--networkid 2`:

```shell
./ontology --networkid 2                        # Linux
./ontology-darwin-amd64 --networkid 2           # MacOS
 start ontology-windows-amd64.exe --networkid 2 # Windows
```

The PrivateNet is the interesting one for development, and it needs a wallet file first. A wallet file named `wallet.dat` can be generated by running:

```shell
./ontology account add -d
```

and then the node starts with `--testmode`:

```shell
./ontology --testmode                       # Linux
./ontology-darwin-amd64 --testmode          # MacOS
start ontology-windows-amd64.exe --testmode # Windows
```

The resulting directory layout is minimal, a directory containing the `ontology` binary and the `wallet.dat` file. The `-d` flag on `account add` is worth understanding rather than copying blindly, since the README describes the account add command as generating the wallet file with that flag, and the `-d` in the transfer example below is the same letter in a different command, so the two are not interchangeable in meaning.

## The CLI is wallet, client and explorer at once

The examples section shows how much work the single binary absorbs.

An ONT transfer takes addresses directly:

```shell
./ontology asset transfer  --from=ARVVxBPGySL56CvSSWfjRVVyZYpNZ7zp48 --to=AaCe8nVkMRABnp5YgEjYZ9E5KYCxks2uce --amount=10
```

and the result includes the transaction hash, for example `TxHash:437bff5dee9a1894ad421d55b8c70a2b7f34c574de0225046531e32faa1f94ce`. The README notes that due to block time the transfer transaction will not be executed before the block is generated and added, which ties back to the one second block option.

To move ONG instead, you add the asset flag:

```shell
./ontology asset transfer --from=ARVVxBPGySL56CvSSWfjRVVyZYpNZ7zp48 --to=ARVVxBPGySL56CvSSWfjRVVyZYpNZ7zp48 --amount=95.479777254 --asset=ong
```

The precision difference between the two assets is called out explicitly: ONT is an integer and has no decimals, whereas ONG has 9 decimals.

Addresses can be replaced with an index or a label. The index is the sequence number of a particular account in the wallet, starting from 1, and the label is the unique alias of an account in the wallet, so `./ontology asset transfer --from=1 --to=2 --amount=10` moves ten ONT between the first two accounts you added.

Querying is the same binary. `./ontology info status <TxHash>` reports the outcome of a transfer, and `./ontology asset balance <address|index|label>` returns a balance, for example `./ontology asset balance 1`.

## Running the node in Docker

The Docker route is four steps and it is worth following in order, because the first step is a prerequisite rather than a command.

First, set up Docker Compose on your computer, and you will need the latest version of Docker Compose. Second, in the root directory of the source code, run `make docker` to make an Ontology image. Third, run the image. `docker run ontio/ontology` starts Ontology, `docker run -ti ontio/ontology` starts it and allows interactive keyboard input, and if you need to keep the data generated by the image you use Docker's data persistence function. Fourth, arguments to the Ontology command can be added, for example `docker run ontio/ontology --networkid 2`.

The Makefile shows the naming scheme behind the `ontio/ontology` reference. `DOCKER_NS` defaults to `ontio` and can be overridden, and the tag is the architecture plus the version from `git describe`, so the image built locally is tagged with the commit you built rather than with a release number.

The `-ti` distinction is not cosmetic. The `ontology` binary is a CLI, and starting a node interactively means seeing its output, so a detached run without a TTY attached gives you a container whose logs you have to go and fetch rather than a node you can watch sync.

There is also a `docker/` directory in the repository, and the `scripts/` and `.gha.*` files at the top level show the project's continuous integration: separate scripts for checking the licence, checking template logs, running gofmt, running the Go tests and deploying, wired into both a Travis configuration and GitHub Actions scripts.

## LGPL-3.0 terms and a version line to watch

The licence field on the repository says LGPL-3.0, with a LICENSE file and a CONTRIBUTING.md at the top level. LGPL is a weak copyleft licence, and for a blockchain node it means that if you modify the code and distribute it, you have to keep your changes available under the same terms, while a separate application talking to the node over its RPC interfaces is unaffected.

The release history is where the maintenance picture is. The tags are v2.7.0 on 2025-11-27, v3.1.2 on 2026-07-29 and v3.1.5 on 2026-09-02, and the last push was on 2026-10-13. So the project is on a 3.1 line, with a 2.7 line that shipped before it, and work continues after the newest tag.

That combination, a moving master branch that the README warns may be unstable, a 3.x line, and a stable 2.x line still tagged, is the pattern of a chain that is running and changing. For a node operator the practical consequence is to run a tagged release rather than master, and to check the release notes for consensus or protocol changes when you upgrade, since a consensus change is not a patch level event.

The other thing the repository tells you is that the node is one part of a wider ecosystem. There are SDKs, the SmartX IDE and a blockchain explorer, and the project says it is maintained by the core tech team together with community members. The Go implementation is the reference that the rest of that tooling is built around, which is why it is worth reading even if you never run a node yourself.

## Conclusion

Adopt ontology when you need to run an Ontology node, experiment on a PrivateNet or build against the reference Go implementation of the chain, and you can live with a repository whose master branch is stated to be unstable. Skip it if you need a stable tagged source to build from, because the README directs you to the releases section for stable versions, and check the version drift before you start, since the README header still names an older release than the tags and the module requires a newer Go than the README states. Verify first that the consensus mode and contract environment your application expects are enabled in the configuration you use. The licence field on the repository says LGPL-3.0, and the last push was on 2026-10-13.

## FAQ

### What does the ontology repository build?

Running `make all` produces two executables: `ontology`, the primary node application and CLI, and `tools/sigsvr`, the Signature Server, an RPC server for signing transactions. The build requires Golang 1.17 or later according to the README, while go.mod declares go 1.23.0.

### How do I run a local Ontology PrivateNet?

Create a wallet file first with `./ontology account add -d`, which generates `wallet.dat`, then start the node with `./ontology --testmode` on Linux, `./ontology-darwin-amd64 --testmode` on MacOS or `start ontology-windows-amd64.exe --testmode` on Windows.

### Which consensus algorithms does ontology support?

The README lists multiple consensus algorithms supported, namely VBFT, DBFT, RBFT, SBFT and PoW, with quick block generation time of 1 to 30 seconds. The node has to be configured with the algorithm the network it joins expects.

### How do I transfer ONT and ONG with the ontology CLI?

Use `./ontology asset transfer --from=... --to=... --amount=...`, adding `--asset=ong` for ONG. You can replace addresses with an account index, starting from 1, or with an account label, and you query the outcome with `./ontology info status <TxHash>`.

### How do I run ontology with Docker?

Run `make docker` in the root of the source tree to build the image, then `docker run ontio/ontology` to start it, or `docker run -ti ontio/ontology` for interactive keyboard input. Arguments pass through, for example `docker run ontio/ontology --networkid 2`.

### What licence is ontology released under and how current is it?

The licence field on the repository says LGPL-3.0, with a LICENSE file at the top level. The releases are v2.7.0 on 2025-11-27, v3.1.2 on 2026-07-29 and v3.1.5 on 2026-09-02, with the last push on 2026-10-13, and the README notes the master branch may be unstable.

## Sources

- [Issues](https://github.com/ontio/ontology/issues)
- [License: LGPL-3.0](https://github.com/ontio/ontology/blob/master/LICENSE)
- [ontio/ontology on GitHub](https://github.com/ontio/ontology)
- [README](https://github.com/ontio/ontology/blob/master/README.md)
- [Releases](https://github.com/ontio/ontology/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ontio-ontology