Flow is a fast, secure, and developer-friendly blockchain built to support the next generation of games, apps and the digital assets that power them. Read more about it here.

• Getting started
• Documentation
• Installation
  • Clone Repository
  • Install Dependencies
• Development Workflow
  • Testing
  • Building
  • Local Network
  • Code Generation

• To install all dependencies and tools, see the project setup guide
• To dig into more documentation about Flow, see the documentation
• To learn how to contribute, see the contributing guide
• To see information on developing Flow, see the development workflow

You can find an overview of the Flow architecture on the documentation website.

Development on Flow is divided into work streams. Each work stream has a home directory containing high-level documentation for the stream, as well as links to documentation for relevant components used by that work stream.

The following table lists all work streams and links to their home directory and documentation:

• Clone this repository

• Install Go (Flow requires Go 1.25 and later)

• Install Docker, which is used for running a local network and integration tests

• Make sure the GOPATH and GOBIN environment variables are set, and GOBIN is added to your path:

  export GOPATH=$(go env GOPATH)
  export GOBIN=$GOPATH/bin
  export PATH=$PATH:$GOBIN

  Add these to your shell profile to persist them for future runs.

• Then, run the following command:

  make install-tools

At this point, you should be ready to build, test, and run Flow! 🎉

Flow has a unit test suite and an integration test suite. Unit tests for a module live within the module they are testing. Integration tests live in integration/tests.

Run the unit test suite:

make test

Run the integration test suite:

make integration-test

The recommended way to build and run Flow for local development is using Docker.

Build a Docker image for all nodes:

make docker-native-build-flow

Build a Docker image for a particular node role (replace $ROLE with collection, consensus, etc.):

make docker-native-build-$ROLE

Build the binary for an access node that can be run directly on the machine without using Docker.

make docker-native-build-access-binary

this builds a binary for Linux/x86_64 machine.

The make command will generate a binary called flow_access_node

When importing the github.com/onflow/flow-go module in your Go project, testing or building your project may require setting extra Go flags because the module requires cgo. In particular, CGO_ENABLED must be set to 1 if cgo isn't enabled by default. This constraint comes from the underlying cryptography library. Refer to the crypto repository build for more details.

A local version of the network can be run for manual testing and integration. See the Local Network Guide for instructions.

Generated code is kept up to date in the repository, so should be committed whenever it changes.

Run all code generators:

make generate

Generate protobuf stubs:

make generate-proto

Generate OpenAPI schema models:

make generate-openapi

Generate mocks used for unit tests:

make generate-mocks

We use github.com/vektra/mockery for mocking interfaces within tests. The configuration is in .mockery.yaml.

You can add new packages by their fully qualified name. e.g.

github.com/onflow/flow-go/module/execution:

This will add all interfaces within the module/execution/ (non-recursive).

Mockery dropped support for generating function mocks. Instead, you can use this pattern:

1. Create a mock_interfaces directory in the package where the function mock exists.
2. Add a file that mocks the function. for example, this mocks the `StateMachineEventsTelemetryFactory(candidateView uint64) protocol_state.StateMachineTelemetryConsumer

package mockinterfaces

import "github.com/onflow/flow-go/state/protocol/protocol_state"

// ExecForkActor allows to create a mock for the ExecForkActor callback
type StateMachineEventsTelemetryFactory interface {
	Execute(candidateView uint64) protocol_state.StateMachineTelemetryConsumer
}

3. Add the package to .mockery.yaml. Note: specify the directory where you want the mock to be placed.

  github.com/onflow/flow-go/state/protocol/protocol_state/mock_interfaces:
    config:
      dir: "state/protocol/protocol_state/mock"