github.com/nspcc-dev/neo-go@v0.105.2-0.20240517133400-6be757af3eba/README.md (about) 1 <p align="center"> 2 <picture> 3 <source media="(prefers-color-scheme: dark)" srcset="./.github/logo_dark.png"> 4 <source media="(prefers-color-scheme: light)" srcset="./.github/logo_light.png"> 5 <img src="./.github/logo_light.png" width="300px" alt="NeoGo logo"> 6 </picture> 7 </p> 8 <p align="center"> 9 <b>Go</b> Node and SDK for the <a href="https://neo.org">Neo</a> blockchain. 10 </p> 11 12 <hr /> 13 14 [![codecov](https://codecov.io/gh/nspcc-dev/neo-go/branch/master/graph/badge.svg)](https://codecov.io/gh/nspcc-dev/neo-go) 15 [![GithubWorkflows Tests](https://github.com/nspcc-dev/neo-go/actions/workflows/tests.yml/badge.svg)](https://github.com/nspcc-dev/neo-go/actions/workflows/tests.yml) 16 [![Report](https://goreportcard.com/badge/github.com/nspcc-dev/neo-go)](https://goreportcard.com/report/github.com/nspcc-dev/neo-go) 17 [![GoDoc](https://godoc.org/github.com/nspcc-dev/neo-go?status.svg)](https://godoc.org/github.com/nspcc-dev/neo-go) 18 ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/nspcc-dev/neo-go?sort=semver) 19 ![License](https://img.shields.io/github/license/nspcc-dev/neo-go.svg?style=popout) 20 21 # Overview 22 23 NeoGo is a complete platform for distributed application development built on 24 top of and compatible with the [Neo project](https://github.com/neo-project). 25 This includes, but not limited to (see documentation for more details): 26 27 - [Consensus node](docs/consensus.md) 28 - [RPC node & client](docs/rpc.md) 29 - [CLI tool](docs/cli.md) 30 - [Smart contract compiler](docs/compiler.md) 31 - [Neo virtual machine](docs/vm.md) 32 - [Smart contract examples](examples/README.md) 33 - [Oracle service](docs/oracle.md) 34 - [State validation service](docs/stateroots.md) 35 36 The protocol implemented here is Neo N3-compatible, however you can also find 37 an implementation of the Neo Legacy protocol in the [**master-2.x** 38 branch](https://github.com/nspcc-dev/neo-go/tree/master-2.x) and releases 39 before 0.80.0 (**0.7X.Y** track). 40 41 # Getting started 42 43 ## Installation 44 45 NeoGo is distributed as a single binary that includes all the functionality 46 provided (but smart contract compiler requires Go compiler to operate). You 47 can grab it from [releases 48 page](https://github.com/nspcc-dev/neo-go/releases), use a Docker image (see 49 [Docker Hub](https://hub.docker.com/r/nspccdev/neo-go) for various releases of 50 NeoGo, `:latest` points to the latest release) or build yourself. 51 52 ### Building 53 54 Building NeoGo requires Go 1.20+ and `make`: 55 56 ``` 57 make 58 ``` 59 60 The resulting binary is `bin/neo-go`. Notice that using some random revision 61 from the `master` branch is not recommended (it can have any number of 62 incompatibilities and bugs depending on the development stage), please use 63 tagged released versions. 64 65 #### Building on Windows 66 67 To build NeoGo on Windows platform we recommend you to install `make` from [MinGW 68 package](https://osdn.net/projects/mingw/). Then, you can build NeoGo with: 69 70 ``` 71 make 72 ``` 73 74 The resulting binary is `bin/neo-go.exe`. 75 76 ## Running a node 77 78 A node needs to connect to some network, either local one (usually referred to 79 as `privnet`) or public (like `mainnet` or `testnet`). Network configuration 80 is stored in a file and NeoGo allows you to store multiple files in one 81 directory (`./config` by default) and easily switch between them using network 82 flags. 83 84 To start Neo node on a private network, use: 85 86 ``` 87 ./bin/neo-go node 88 ``` 89 90 Or specify a different network with an appropriate flag like this: 91 92 ``` 93 ./bin/neo-go node --mainnet 94 ``` 95 96 Available network flags: 97 - `--mainnet, -m` 98 - `--privnet, -p` 99 - `--testnet, -t` 100 101 To run a consensus/committee node, refer to [consensus 102 documentation](docs/consensus.md). 103 104 If you're running a node on Windows, please turn off or configure Windows 105 Firewall appropriately (allowing inbound connections to the P2P port). 106 107 ### Docker 108 109 By default, the `CMD` is set to run a node on `privnet`. So, to do this, simply run: 110 111 ```bash 112 docker run -d --name neo-go -p 20332:20332 -p 20331:20331 nspccdev/neo-go 113 ``` 114 115 Which will start a node on `privnet` and expose node's ports `20332` (P2P 116 protocol) and `20331` (JSON-RPC server). 117 118 ### Importing mainnet/testnet dump files 119 120 If you want to jump-start your mainnet or testnet node with [chain archives 121 provided by NGD](https://sync.ngd.network/), follow these instructions: 122 ``` 123 $ wget .../chain.acc.zip # chain dump file 124 $ unzip chain.acc.zip 125 $ ./bin/neo-go db restore -m -i chain.acc # for testnet use '-t' flag instead of '-m' 126 ``` 127 128 The process differs from the C# node in that block importing is a separate 129 mode. After it ends, the node can be started normally. 130 131 ## Running a private network 132 133 Refer to [consensus node documentation](docs/consensus.md). 134 135 ## Smart contract development 136 137 Please refer to [NeoGo smart contract development 138 workshop](https://github.com/nspcc-dev/neo-go-sc-wrkshp) that shows some 139 simple contracts that can be compiled/deployed/run using NeoGo compiler, SDK 140 and a private network. For details on how Go code is translated to Neo VM 141 bytecode and what you can and can not do in a smart contract, please refer to the 142 [compiler documentation](docs/compiler.md). 143 144 Refer to [examples](examples/README.md) for more Neo smart contract examples 145 written in Go. 146 147 ## Wallets 148 149 NeoGo wallet is just a 150 [NEP-6](https://github.com/neo-project/proposals/blob/68398d28b6932b8dd2b377d5d51bca7b0442f532/nep-6.mediawiki) 151 file that is used by CLI commands to sign various things. CLI commands are not 152 a direct part of the node, but rather a part of the NeoGo binary, their 153 implementations use RPC to query data from the blockchain and perform any 154 required actions. It's not required to open a wallet on an RPC node (unless 155 your node provides some service for the network like consensus or oracle nodes 156 do). 157 158 ## Monitoring 159 NeoGo provides [Prometheus](https://prometheus.io/docs/guides/go-application) and 160 [Pprof](https://golang.org/pkg/net/http/pprof/) services that can be enabled 161 in the node in order to provide additional monitoring and debugging data. 162 163 Configuring any of the two services is easy, add the following section (`Pprof` 164 instead of `Prometheus` if you need that) to the respective `config/protocol.*.yml`: 165 ``` 166 Prometheus: 167 Enabled: true 168 Addresses: 169 - ":2112" 170 ``` 171 where you can switch on/off and define port. Prometheus is enabled and Pprof is disabled by default. 172 173 ## Contributing 174 175 Feel free to contribute to this project after reading the 176 [contributing guidelines](CONTRIBUTING.md). 177 178 Before starting to work on a certain topic, create a new issue first 179 describing the feature/topic you are going to implement. 180 181 # Contact 182 183 - [@AnnaShaleva](https://github.com/AnnaShaleva) on GitHub 184 - [@roman-khimov](https://github.com/roman-khimov) on GitHub 185 - Reach out to us on the [Neo Discord](https://discordapp.com/invite/R8v48YA) channel 186 187 # License 188 189 - Open-source [MIT](LICENSE.md)