MAINNET:
Loading...
TESTNET:
Loading...
/
onflow.org
Flow Playground


Logo

The Flow Emulator is a lightweight tool that emulates the behaviour of the real Flow network.
Read the docs»

Report Bug · Contribute



The Emulator

The emulator exposes a gRPC server that implements the Flow Access API, which is designed to have near feature parity with the real network API.

The Flowser Emulator Explorer

There is also a block explorer GUI for the emulator, that will help you speed up development when using the emulator.

Running

Configuration

The Flow Emulator can be run in different modes and settings, all of them are described in the table bellow.

Please note that if you will run the emulator using the Flow CLI you must use flags to pass configuration values and if you plan to run the emulator with Docker you must use the environment variables (Env) to pass configuration values.

FlagEnvDefaultDescription
--port, -pFLOW_PORT3569gRPC port to listen on
--rest-portFLOW_RESTPORT8888REST API port to listen on
--admin-portFLOW_ADMINPORT8080Admin API port to listen on
--verbose, -vFLOW_VERBOSEfalseEnable verbose logging (useful for debugging)
--log-formatFLOW_LOGFORMATtextOutput log format (valid values text, JSON)
--block-time, -bFLOW_BLOCKTIME0Time between sealed blocks. Valid units are ns, us (or µs), ms, s, m, h
--contractsFLOW_WITHCONTRACTSfalseStart with contracts like FUSD, NFT and an NFT Marketplace, when the emulator starts
--service-priv-keyFLOW_SERVICEPRIVATEKEYrandomPrivate key used for the service account
--service-sig-algoFLOW_SERVICEKEYSIGALGOECDSA_P256Service account key signature algorithm
--service-hash-algoFLOW_SERVICEKEYHASHALGOSHA3_256Service account key hash algorithm
--initFLOW_INITfalseGenerate and set a new service account
--rest-debugFLOW_RESTDEBUGfalseEnable REST API debugging output
--grpc-debugFLOW_GRPCDEBUGfalseEnable gRPC server reflection for debugging with grpc_cli
--persistFLOW_PERSISTfalseEnable persistence of the state between restarts
--snapshotFLOW_SNAPSHOTfalseEnable snapshot support ( this option automatically enables persistence )
--dbpathFLOW_DBPATH./flowdbSpecify path for the database file persisting the state
--simple-addressesFLOW_SIMPLEADDRESSESfalseUse sequential addresses starting with 0x1
--token-supplyFLOW_TOKENSUPPLY1000000000.0Initial FLOW token supply
--transaction-expiryFLOW_TRANSACTIONEXPIRY10Transaction expiry, measured in blocks
--storage-limitFLOW_STORAGELIMITENABLEDtrueEnable account storage limit
--storage-per-flowFLOW_STORAGEMBPERFLOWSpecify size of the storage in MB for each FLOW in account balance. Default value from the flow-go
--min-account-balanceFLOW_MINIMUMACCOUNTBALANCESpecify minimum balance the account must have. Default value from the flow-go
--transaction-feesFLOW_TRANSACTIONFEESENABLEDfalseEnable variable transaction fees and execution effort metering
as decribed in Variable Transaction Fees: Execution Effort FLIP
--transaction-max-gas-limitFLOW_TRANSACTIONMAXGASLIMIT9999Maximum gas limit for transactions
--script-gas-limitFLOW_SCRIPTGASLIMIT100000Specify gas limit for script execution

Running the emulator with the Flow CLI

The emulator is bundled with the Flow CLI, a command-line interface for working with Flow.

Installation

Follow these steps to install the Flow CLI.

Starting the server

Starting the emulator by using Flow CLI also leverages CLI configuration file flow.json. You can use the flow.json to specify the service account which will be reused between restarts. Read more about CLI configuration here.

You can start the emulator with the Flow CLI:

flow emulator --init

Using the emulator in a project

You can start the emulator in your project context by running the above command in the same directory as flow.json. This will configure the emulator with your project's service account, meaning you can use it to sign and submit transactions. Read more about the project and configuration here.

Using Emulator in Go

You can use the emulator as a module in your Go project. To install emulator, use go get:

go get github.com/onflow/flow-emulator

After installing the emulator module you can initialize it in the code:

var opts []emulator.Option
privKey, err := crypto.DecodePrivateKeyHex(crypto.ECDSA_P256, "")

opts = append(opts, emulator.WithServicePublicKey(
  privKey.PublicKey(),
  crypto.ECDSA_P256,
  crypto.SHA3_256,
))

blockchain, err := emulator.NewBlockchain(opts...)

You can then access all methods of the blockchain like so:

account, err := blockchain.GetAccount(address) 

Managing emulator state

It's possible to manage emulator state by using the admin API. You can at any point create a new named snapshot of the state and then at any later point revert emulator state to that reference.

In order to use the state management functionality you need to run the emulator with persistent state:

flow emulator --persist

Create a new snapshot by doing an HTTP request:

GET http://localhost:8080/emulator/snapshot/{name}

Please note the example above uses the default admin API port

At any later point you can reload to that snapshot by executing the same HTTP request as before. You need to use the same value for name parameter.

The snapshot functionality is a great tool for testing where you can first initialize a base snapshot with seed values, execute the test and then revert to that initialized state.

Running the emulator with Docker

Docker builds for the emulator are automatically built and pushed to gcr.io/flow-container-registry/emulator, tagged by commit and semantic version. You can also build the image locally.

docker run gcr.io/flow-container-registry/emulator

The full list of environment variables can be found here. You can pass any environment variable by using -e docker flag and pass the valid value.

Custom Configuration Example:

docker run -e FLOW_PORT=9001 -e FLOW_VERBOSE=true -e FLOW_SERVICEPRIVATEKEY=<hex-encoded key> gcr.io/flow-container-registry/emulator

To generate a service key, use the keys generate command in the Flow CLI.

flow keys generate

Development

Read contributing document.