Skip to content

Latest commit

 

History

History
273 lines (195 loc) · 9.41 KB

README.md

File metadata and controls

273 lines (195 loc) · 9.41 KB
Raw

Development Overview

Please note that this repository is under very active development and breaking changes are likely to occur. If the documentation falls out of date please see our guide on how to contribute!

LFG - Development

Install Dependencies

  • Install Docker
  • Install Docker Compose
  • Install Golang
  • protoc-gen-go, protoc-go-inject-tag and mockgen by running make install_cli_deps

Note to the reader: Please update this list if you found anything missing.

Last tested by with:

$ docker --version
Docker version 20.10.14, build a224086

$ protoc --version
libprotoc 3.19.4

$ which protoc-go-inject-tag && echo "protoc-go-inject-tag Installed"
/your$HOME/go/bin/protoc-go-inject-tag
protoc-go-inject-tag Installed

$ go version
go version go1.18.1 darwin/arm64

$ mockgen --version
v1.6.0

$ system_profiler SPSoftwareDataType
Software:

    System Software Overview:

      System Version: macOS 12.3.1 (21E258)
      Kernel Version: Darwin 21.4.0

Prepare Local Environment

Generate local files

$ git clone [email protected]:pokt-network/pocket.git && cd pocket
$ make develop_start

Optionally activate changelog pre-commit hook

cp .githooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Please note that the Github workflow will still prevent this from merging unless the CHANGELOG is updated.

Pocket Network CLI

The Pocket node provides a CLI for interacting with Pocket RPC Server. The CLI can be used for both read & write operations by users and to aid in automation.

In order to build the CLI:

  1. Generate local files
make develop_start
  1. Build the CLI binary
make build

The cli binary will be available at bin/p1 and can be used instead of go run app/client/*.go

The commands available are listed here or accessible via bin/p1 --help

Swagger UI

Swagger UI is available to help during the development process.

In order to spin a local instance of it with the API definition for the Pocket Network Node RPC interface automatically pre-loaded you can run:

make swagger-ui

View Available Commands

$ make

Running Unit Tests

$ make test_all

Note that there are a few tests in the library that are prone to race conditions and we are working on improving them. This can be checked with make test_race.

Running LocalNet

V1 Localnet Demo

  1. Delete any previous docker state
$ make docker_wipe
  1. In one shell, run the 4 nodes setup:
$ make compose_and_watch
  1. In another shell, run the development client:
$ make client_start && make client_connect
  1. Check the state of each node:
✔ PrintNodeState
  1. Trigger the next view to ensure everything is working:
✔ TriggerNextView
  1. Reset the ResetToGenesis if you want to:
✔ ResetToGenesis
  1. Set the client to automatic and watch it go:
✔ TogglePacemakerMode
✔ TriggerNextView
  1. [Optional] Common manual set of verification steps
✔ ResetToGenesis
✔ PrintNodeState # Check committed height is 0
✔ TriggerNextView
✔ PrintNodeState # Check committed height is 1
✔ TriggerNextView
✔ PrintNodeState # Check committed height is 2
✔ TogglePacemakerMode # Check that it’s automatic now
✔ TriggerNextView # Let it rip!

Profiling

If you need to profile the node for CPU and/or memory usage, you can use the pprof tool. A quick guide is available here.

Code Organization

Pocket
├── app                               # Entrypoint to running the Pocket node and clients
│   ├── client                        # Entrypoint to running a local Pocket debug client
│   └── pocket                        # Entrypoint to running a local Pocket node
├── bin                               # Destination for compiled pocket binaries
├── build                             # Build related source files including Docker, scripts, etc
│   ├── config                        # Configuration files for to run nodes in development
│   ├── deployments                   # Docker-compose to run different cluster of services for development
│   ├── docs                          # Links to V1 Protocol implementation documentation (excluding the protocol specification)
├── consensus                         # Implementation of the Consensus module
├── docs                              # Links to V1 Protocol implementation documentation (excluding the protocol specification)
├── logger                            # Implementation of the Logger module
├── p2p                               # Implementation of the P2P module
├── persistence                       # Implementation of the Persistence module
├── rpc                               # Implementation of the RPC module
├── runtime                           # Implementation of the Runtime module
│   ├── configs                       # Configuration struct definitions
│   │   └── proto                     # Protobuf representing the specific configuration of the various modules
│   ├── defaults                      # Default values for the configuration structs
│   ├── genesis
│   │   └── proto                     # Protobuf representing the genesis state of the Pocket blockchain
│   └── test_artifacts                # Componentry used for generating test artifacts such as particular genesis states used in testing
├── shared                            # Shared types, modules and utils
│   ├── codec
│   │   └── proto
│   ├── converters
│   ├── core                          # Core types (Actor, Pools, etc.) used throughout the codebase
│   │   └── types
│   │       └── proto                 # Protobuf representing the core types used throughout the codebase
│   ├── crypto
│   ├── docs
│   │   └── flows
│   ├── messaging                     # Messaging structs and functions
│   │   └── proto
│   └── modules                       # Shared modules definitions (interfaces)
├── telemetry                         # Implementation of the Telemetry module
├── utility                           # Implementation of the Utility module
└── Makefile                          # The source of targets used to develop, build and test

Linters

We utilize golangci-lint to run the linters. It is a wrapper around a number of linters and is configured to run many at once. The linters are configured to run on every commit and pull request via CI, and all code issues are populated as GitHub annotations to let developers and reviewers easily locate an issue.

Installation of golangci-lint

Please follow the instructions on the golangci-lint website.

Running linters locally

You can run golangci-lint locally against all packages with:

make go_lint

If you need to specify any additional flags, you can run golangci-lint directly as it picks up the configuration from the .golangci.yml file.

VSCode Integration

golangci-lint has an integration with VSCode. Per documentation, recommended settings are:

"go.lintTool":"golangci-lint",
"go.lintFlags": [
  "--fast"
]

Configuration

golangci-lint is a sophisticated tool including both default and custom linters. The configuration file, which can grow quite large, is located at .golangci.yml.

The official documentation includes a list of different linters and their configuration options. Please refer to this page for more information.

Custom linters

We can write custom linters using go-ruleguard. The rules are located in the build/linters directory. The rules are written in the Ruleguard DSL, if you've never worked with ruleguard in the past, it makes sense to go through introduction article and Ruleguard by example tour.

Ruleguard is run via gocritic linter which is a part of golangci-lint, so if you wish to change configuration or debug a particular rule, you can modify the .golangci.yml file.