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)