Skip to content

Latest commit

 

History

History
211 lines (133 loc) · 7.64 KB

contributing.md

File metadata and controls

211 lines (133 loc) · 7.64 KB
Raw

Contributing

Contributions to go-nitro are welcome from anyone.

Magmo (at Consensys Mesh) are developing go-nitro under contract for the Filecoin Foundation. As a consequence, we reserve discretionary veto rights on feature additions, architectural decisions, etc., which may hinder progress toward the specific aims of this contract.

Contribution lifecycle

Magmo uses Github Projects for go-nitro project management. We will aim to keep a handful of "good first issues" in the pipeline, which are a good place to start.

Before spending lots of time working on an issue, consider asking us for feedback via Slack, the issue tracker, or email. We would love to help make your contributions more successful!

Pull requests (internal or external) will be reviewed by one or two members of Magmo. We aim to review most contributions within one business day.

We include a PR template to serve as a guideline, not a rule, to communicate the code culture we wish to maintain in this repository.

Style

When in doubt, defer to the Effective Go document CodeReviewComments as "style guides".

Prerequisites (MacOS instructions)

Install golang

brew install golang

Install golangci-lint:

brew install golangci-lint
brew upgrade golangci-lint

Install staticcheck

go install honnef.co/go/tools/cmd/staticcheck@latest

Make sure GOPATH is set:

echo $GOPATH

You should see $HOME/go.

Building and Testing

To build:

go build ./...

To run tests:

go test ./...

Documenation website

This is built using a variant of mkdocs. First, follow these instructions to install. Or even better, run

pip install -r requirements.txt

You may also need to follow these additional instructions.

Then run

mkdocs serve

and navigate to http://localhost:8000 .

Using Docker

docker pull squidfunk/mkdocs-material

and then:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

You will need to diable strict mode to have this work mkdocs/mkdocs#2108.

Viewing Godocs website

Run

godoc --http :6060

and navigate to http://localhost:6060/pkg/github.com/statechannels/go-nitro/

Pre PR checks:

Please execute the following on any branch that's ready for review or merge.

staticcheck:

staticcheck ./...

format:

gofumpt -w .

lint:

golangci-lint run

remove unused dependencies:

go mod tidy

Debugging Tests

VS code is used to debug tests. To start a debugging session in VS code:

  • Ensure you have the go extension installed
  • Open the test file.
  • Open the Run and Debug section.
  • Run the Debug Test configuration.

With the extension it is also possible to start a debugging session right from a test function.

Generating Go bindings

We use solc and abigen to generate Go bindings from our *.sol source files.

This is achieved by running the generate_adjudicator_bindings.sh script at the top level of the repo. Because our *.sol files depend on external projects via node_modules, to run this script successfully you must:

  • have successfully run npm install in the nitro-protocol directory.
  • have solc installed at the correct version (currently 0.8.17, see the CI or linting config for a hint if you think it may have changed)
  • have abigen (a tool shipped with go-ethereum) installed. Currently we use version 1.10.8, see the CI for a hint if you think it may have changed.

The resulting Go bindings file is checked-in to the repository. Although it is auto-generated from on-chain source code, it effectively forms part of the off-chain source code.

If you alter the contracts, you should regenerate the bindings file at check it in. A github action will run which will check that you have done this correctly.

TIP: if you find that the github action still reports a mismatch despite regenerating the bindings, this may be due to the action using the "test merge" of your PR (rather than the tip of your branch). Try rebasing your branch.

Testground

We run deeper tests of the code on your PR using a hosted testground runner. You may see a comment appear with links to dashboards containing performance metrics and statistics. The tests may also be run locally. For more information, see our testground test plan repository.

Logs

Go-nitro uses the log/slog package to output structured logging. Integration tests typically write logs from several go-nitro nodes to the artifacts directory.

A typical log line is

{
  "time": "2023-08-23T11:23:55.727269-07:00",
  "level": "INFO",
  "msg": "Constructed Engine",
  "address": "0xAAA6628Ec44A8a742987EF3A114dDFE2D4F7aDCE"
}

You can use a tool such as pino-pretty to get a colorized, JSON-formatted output from the logs:

cat artifacts/complex_integration_message_alice.log | npx pino-pretty > output.log

Opening output.log in an editor like VSCode enables the log lines to be folded / searched.

Start RPC servers with Docker

To test the creation and execution of channels it is necessary to have a test network with multiple nodes. To spin up a docker image with 3 rpc servers and channels pre-populated, run the following:

  1. make docker/network/build
  2. make docker/network/start

Three rpc go-nitro servers will be available on ports 4005, 4006, and 4007 for Alice, Irene, and Bob. A ledger channel is created between Alice and Irene, and another ledger channel is created between Irene and Bob. A virtual channel is created between Alice and Bob. Each server may be communicated with over JSON-RPC at a localhost endpoint with an appropriate port. See these instructions on how to do that.

Start RPC servers test command

A test command is available to start up multiple RPC servers and a test chain. This is used to easily and quickly spin up a test environment. The command requires that foundry is installed locally; foundry installation instructions are available here.

The command will:

  1. Start an foundry anvil test chain
  2. Deploy the adjudicator contract to the test chain
  3. Start an RPC server for Alice (0xAAA6628Ec44A8a742987EF3A114dDFE2D4F7aDCE) listening for RPCs on port 4005
  4. Start an RPC server for Irene (0x111A00868581f73AB42FEEF67D235Ca09ca1E8db) listening for RPCs on port 4006
  5. Start an RPC server for Bob (0xBBB676f9cFF8D242e9eaC39D063848807d3D1D94) listening for RPCs on port 4007

Stopping the test command will shutdown all RPC servers and anvil.

To run the command from the go-nitro directory run go run ./cmd/start-rpc-servers