{"id":13669722,"url":"https://github.com/onflow/flow-emulator","last_synced_at":"2026-01-12T09:44:47.970Z","repository":{"id":37024505,"uuid":"308682673","full_name":"onflow/flow-emulator","owner":"onflow","description":"The Flow Emulator is a lightweight tool that emulates the behaviour of the real Flow network","archived":false,"fork":false,"pushed_at":"2025-05-02T07:31:18.000Z","size":5322,"stargazers_count":87,"open_issues_count":15,"forks_count":51,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-05-02T08:38:48.736Z","etag":null,"topics":["blockchain","emulator","flow"],"latest_commit_sha":null,"homepage":"https://onflow.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":".github/security_scann.yaml","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-30T16:16:25.000Z","updated_at":"2025-04-22T17:50:36.000Z","dependencies_parsed_at":"2023-09-28T21:33:01.954Z","dependency_job_id":"529fe43c-6162-4582-8212-726a1239fed6","html_url":"https://github.com/onflow/flow-emulator","commit_stats":null,"previous_names":[],"tags_count":175,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onflow%2Fflow-emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onflow","download_url":"https://codeload.github.com/onflow/flow-emulator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592395,"owners_count":22097013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","emulator","flow"],"created_at":"2024-08-02T09:00:20.665Z","updated_at":"2026-01-12T09:44:47.965Z","avatar_url":"https://github.com/onflow.png","language":"Go","funding_links":[],"categories":["Flow区块链"],"sub_categories":["开发工具"],"readme":"\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.onflow.org/emulator/\"\u003e\n    \u003cimg src=\"docs/emulator-banner.svg\" alt=\"Logo\" width=\"410\" height=\"auto\"\u003e\n  \u003c/a\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ci\u003eThe Flow Emulator is a lightweight tool that emulates the behaviour of the real Flow network.\u003c/i\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://docs.onflow.org/emulator/\"\u003e\u003cstrong\u003eRead the docs»\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/onflow/flow-emulator/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/onflow/flow-emulator/blob/master/CONTRIBUTING.md\"\u003eContribute\u003c/a\u003e\n  \u003c/p\u003e\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n### The Emulator\n\nThe emulator exposes a gRPC server that implements the Flow Access API, which is designed to have near feature parity\nwith the real network API.\n\n### The Flowser Emulator Explorer\n\nThere is also a block explorer GUI for the emulator, that will help you speed up development when using the emulator.\n\n- [Flowser GitHub Repository](https://github.com/onflowser/flowser)\n- [Flowser Documentation](https://github.com/onflowser/flowser#-contents)\n\n# Running\n\n## Configuration\n\nThe Flow Emulator can be run in different modes and settings, all of them are described in the table below.\n\nPlease note that if you will run the emulator using the Flow CLI you must use flags to pass configuration values\nand if you plan to run the emulator with Docker you must use the environment variables (Env) to pass configuration\nvalues.\n\n| Flag                              | Env                                  | Default        | Description                                                                                                                                                                                                   |\n|-----------------------------------|--------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `--port`, `-p`                    | `FLOW_PORT`                          | `3569`         | gRPC port to listen on                                                                                                                                                                                        |\n| `--rest-port`                     | `FLOW_RESTPORT`                      | `8888`         | REST API port to listen on                                                                                                                                                                                    |\n| `--admin-port`                    | `FLOW_ADMINPORT`                     | `8080`         | Admin API port to listen on                                                                                                                                                                                   |\n| `--verbose`, `-v`                 | `FLOW_VERBOSE`                       | `false`        | Enable verbose logging (useful for debugging)                                                                                                                                                                 |\n| `--log-format`                    | `FLOW_LOGFORMAT`                     | `text`         | Output log format (valid values `text`, `JSON`)                                                                                                                                                               |\n| `--block-time`, `-b`              | `FLOW_BLOCKTIME`                     | `0`            | Time between sealed blocks. Valid units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`                                                                                                                         |\n| `--contracts`                     | `FLOW_WITHCONTRACTS`                 | `false`        | Start with contracts like [ExampleNFT](https://github.com/onflow/flow-nft/blob/master/contracts/NonFungibleToken.cdc) when the emulator starts                                                                |\n| `--service-priv-key`              | `FLOW_SERVICEPRIVATEKEY`             | random         | Private key used for the [service account](https://docs.onflow.org/flow-token/concepts/#flow-service-account)                                                                                                 |\n| `--service-sig-algo`              | `FLOW_SERVICEKEYSIGALGO`             | `ECDSA_P256`   | Service account key [signature algorithm](https://docs.onflow.org/cadence/language/crypto/#signing-algorithms)                                                                                                |\n| `--service-hash-algo`             | `FLOW_SERVICEKEYHASHALGO`            | `SHA3_256`     | Service account key [hash algorithm](https://docs.onflow.org/cadence/language/crypto/#hashing)                                                                                                                |\n| `--init`                          | `FLOW_INIT`                          | `false`        | Generate and set a new [service account](https://docs.onflow.org/flow-token/concepts/#flow-service-account)                                                                                                   |\n| `--rest-debug`                    | `FLOW_RESTDEBUG`                     | `false`        | Enable REST API debugging output                                                                                                                                                                              |\n| `--grpc-debug`                    | `FLOW_GRPCDEBUG`                     | `false`        | Enable gRPC server reflection for debugging with grpc_cli                                                                                                                                                     |\n| `--persist`                       | `FLOW_PERSIST`                       | false          | Enable persistence of the state between restarts                                                                                                                                                              |\n| `--snapshot`                      | `FLOW_SNAPSHOT`                      | false          | Enable snapshot support                                                                                                                                                                                       |\n| `--dbpath`                        | `FLOW_DBPATH`                        | `./flowdb`     | Specify path for the database file persisting the state                                                                                                                                                       |\n| `--simple-addresses`              | `FLOW_SIMPLEADDRESSES`               | `false`        | Use sequential addresses starting with `0x1`                                                                                                                                                                  |\n| `--token-supply`                  | `FLOW_TOKENSUPPLY`                   | `1000000000.0` | Initial FLOW token supply                                                                                                                                                                                     |\n| `--transaction-expiry`            | `FLOW_TRANSACTIONEXPIRY`             | `10`           | [Transaction expiry](https://docs.onflow.org/flow-go-sdk/building-transactions/#reference-block), measured in blocks                                                                                          |\n| `--storage-limit`                 | `FLOW_STORAGELIMITENABLED`           | `true`         | Enable [account storage limit](https://docs.onflow.org/cadence/language/accounts/#storage-limit)                                                                                                              |\n| `--storage-per-flow`              | `FLOW_STORAGEMBPERFLOW`              |                | Specify size of the storage in MB for each FLOW in account balance. Default value from the flow-go                                                                                                            |\n| `--min-account-balance`           | `FLOW_MINIMUMACCOUNTBALANCE`         |                | Specify minimum balance the account must have. Default value from the flow-go                                                                                                                                 |\n| `--transaction-fees`              | `FLOW_TRANSACTIONFEESENABLED`        | `false`        | Enable variable transaction fees and execution effort metering \u003cbr\u003e as described in [Variable Transaction Fees: Execution Effort](https://github.com/onflow/flow/pull/753) FLIP                               |\n| `--transaction-max-compute-limit` | `FLOW_TRANSACTIONMAXCOMPUTELIMIT`    | `9999`         | Maximum [compute limit for transactions](https://docs.onflow.org/flow-go-sdk/building-transactions/#gas-limit)                                                                                                |\n| `--script-compute-limit`          | `FLOW_SCRIPTCOMPUTELIMIT`            | `100000`       | Specify compute limit for script execution                                                                                                                                                                    |\n| ~~`--transaction-max-gas-limit`~~ | ~~`FLOW_TRANSACTIONMAXGASLIMIT`~~    | `9999`         | **Deprecated:** Use `--transaction-max-compute-limit` instead                                                                                                                                                 |\n| ~~`--script-gas-limit`~~          | ~~`FLOW_SCRIPTGASLIMIT`~~            | `100000`       | **Deprecated:** Use `--script-compute-limit` instead                                                                                                                                                          |\n| `--coverage-reporting`            | `FLOW_COVERAGEREPORTING`             | `false`        | Enable Cadence code coverage reporting                                                                                                                                                                        |\n| `--contract-removal`              | `FLOW_CONTRACTREMOVAL`               | `true`         | Allow removal of already deployed contracts, used for updating during development                                                                                                                             |\n| `--skip-tx-validation`            | `FLOW_SKIPTRANSACTIONVALIDATION`     | `false`        | Skip verification of transaction signatures and sequence numbers                                                                                                                                              |\n| `--host`                          | `FLOW_HOST`                          | ` `            | Host to listen on for emulator GRPC/REST/Admin servers (default: All Interfaces)                                                                                                                              |\n| `--chain-id`                      | `FLOW_CHAINID`                       | `emulator`     | Chain to simulate, if 'mainnet' or 'testnet' values are used, you will be able to run transactions against that network and a local fork will be created.  Valid values are: 'emulator', 'testnet', 'mainnet' |\n| `--redis-url`                     | `FLOW_REDIS_URL`                     | ''             | Redis-server URL for persisting redis storage backend ( `redis://[[username:]password@]host[:port][/database]` )                                                                                              |\n| `--fork-host`                     | `FLOW_FORK_HOST`                     | ''             | gRPC access node address (`host:port`) to fork from                                                                                                                                                           |\n| `--fork-height`                   | `FLOW_FORK_HEIGHT`                   | `0`            | Block height to pin the fork (defaults to latest sealed)                                                                                                                                                      |\n| `--legacy-upgrade`                | `FLOW_LEGACYUPGRADE`                 | `false`        | Enable upgrading of legacy contracts                                                                                                                                                                          |\n| `--computation-reporting`         | `FLOW_COMPUTATIONREPORTING`          | `false`        | Enable computation reporting for Cadence programs                                                                                                                                                             |\n| `--computation-profiling`         | `FLOW_COMPUTATIONPROFILING`          | `false`        | Enable computation profiling for Cadence programs                                                                                                                                                             |\n| `--checkpoint-dir`                | `FLOW_CHECKPOINTDIR`                 | ''             | Checkpoint directory to load the emulator state from, if starting the emulator from a checkpoint                                                                                                              |\n| `--state-hash`                    | `FLOW_STATEHASH`                     | ''             | State hash of the checkpoint, if starting the emulator from a checkpoint                                                                                                                                      |\n| `--num-accounts`                  | `FLOW_NUMACCOUNTS`                   | `0`            | Precreate and fund this many accounts at startup (mints 1000.0 FLOW to each)                                                                                                                                 |\n    \n## Running the emulator with the Flow CLI\n\nThe emulator is bundled with the [Flow CLI](https://docs.onflow.org/flow-cli), a command-line interface for working with\nFlow.\n\n### Installation\n\nFollow [these steps](https://docs.onflow.org/flow-cli/install/) to install the Flow CLI.\n\n### Starting the server\n\nStarting the emulator by using Flow CLI also leverages CLI configuration file `flow.json`.\nYou can use the `flow.json` to specify the service account which will be reused between restarts.\nRead more about CLI configuration [here](https://docs.onflow.org/flow-cli/configuration/).\n\nYou can start the emulator with the Flow CLI:\n\n```shell script\nflow emulator\n```\n\nYou need to make sure the configuration `flow.json` exists, or create it beforehand using the `flow init` command.\n\n### Using the emulator in a project\n\nYou can start the emulator in your project context by running the above command\nin the same directory as `flow.json`. This will configure the emulator with your\nproject's service account, meaning you can use it to sign and submit transactions.\nRead more about the project and configuration [here](https://docs.onflow.org/flow-cli/configuration/).\n\n## Using Emulator in Go\n\nYou can use the emulator as a module in your Go project. To install emulator, use go get:\n\n```\ngo get github.com/onflow/flow-emulator\n```\n\nAfter installing the emulator module you can initialize it in the code:\n\n```go\nvar opts []emulator.Option\nprivKey, err := crypto.DecodePrivateKeyHex(crypto.ECDSA_P256, \"\")\n\nopts = append(opts, emulator.WithServicePublicKey(\nprivKey.PublicKey(),\ncrypto.ECDSA_P256,\ncrypto.SHA3_256,\n))\n\nblockchain, err := emulator.NewBlockchain(opts...)\n```\n\nYou can then access all methods of the blockchain like so:\n\n```go\naccount, err := blockchain.GetAccount(address)\n```\n\n## Rolling back state to blockheight\n\nIt is possible to roll back the emulator state to a specific block height. This\nfeature is extremely useful for testing purposes. You can set up an account\nstate, perform tests on that state, and then roll back the state to its initial\nstate after each test.\n\nTo roll back to a specific block height, you can utilize below HTTP request:\n``\nPOST http://localhost:8080/emulator/rollback\n\nPost Data: height={block height}\n\n```\n\nNote: it is only possible to roll back state to a height that was previously executed by the emulator.\nTo pin the starting block height when using a fork, use the `--fork-height` flag.\n\n## Managing emulator state\nIt's possible to manage emulator state by using the admin API. You can at any point\ncreate a new named snapshot of the state and then at any later point revert emulator\nstate to that reference.\n\nIn order to use the state management functionality you need to run the emulator with persistent state:\n```sh\nflow emulator --persist\n```\n\nCreate a new snapshot by doing an HTTP request:\n\n```\nPOST http://localhost:8080/emulator/snapshots\n\nPost Data: name={snapshot name}\n\n```\n\n*Please note the example above uses the default admin API port*\n\nAt any later point you can reload to that snapshot by executing:\n\n```\nPUT http://localhost:8080/emulator/snapshots?name={snapshot name}\n```\n\nYou need to use the same value for `name` parameter.\n\nThe snapshot functionality is a great tool for testing where you can first initialize\na base snapshot with seed values, execute the test and then revert to that initialized state.\n\nYou can list existing snapshots with:\n\n```\nGET http://localhost:8080/emulator/snapshots\n```\n\n## Cadence Code Coverage\n\nThe admin API includes endpoints for viewing and managing Cadence code coverage.\n\nIn order to use this functionality you need to run the emulator with the respective flag which enables code coverage:\n\n```sh\nflow emulator --coverage-reporting\n```\n\nTo view the code coverage report, visit this URL: http://localhost:8080/emulator/codeCoverage\n\nTo flush/reset the collected code coverage report, run the following command:\n\n```sh\ncurl -XPUT 'http://localhost:8080/emulator/codeCoverage/reset'\n```\n\nNote: The above command will reset the code coverage for all the locations, except\nfor `A.f8d6e0586b0a20c7.FlowServiceAccount`, which is a system contract that is essential to the operations of Flow.\n\nTo get better reports with source file references, you can utilize the `sourceFile` pragma in the headers of your\ntransactions and scripts.\n\n```cadence\n#sourceFile(\"scripts/myScript.cdc\")\n```\n\n## Cadence Computation Reporting\n\nThe admin API includes an endpoint for viewing the computation reports for Cadence programs.\n\nIn order to use this functionality you need to run the emulator with the respective flag which enables computation\nreporting:\n\n```sh\nflow emulator --computation-reporting\n```\n\nTo view the computation report, visit this URL: http://localhost:8080/emulator/computationReport.\n\nThe computation report can be reset by sending a PUT request to the following URL:\nhttp://localhost:8080/emulator/computationReport/reset.\n\n## Cadence Computation Profiling\n\nThe admin API includes an endpoint for viewing the computation profile for Cadence programs.\n\nIn order to use this functionality you need to run the emulator with the respective flag which enables computation\nprofiling:\n\n```sh\nflow emulator --computation-profiling\n```\n\nTo view the computation report, visit this URL: http://localhost:8080/emulator/computationProfile.\n\nThis downloads a pprof file that can be analyzed using https://github.com/google/pprof.\n\nTo view the profile in a web browser, run the following command:\n\n```sh\npprof -http=:8081 profile.pprof\n```\n\nThen open your web browser and navigate to `http://localhost:8081`.\n\nTo view the source code of the functions, first [download all deployed contracts](#downloading-all-deployed-contracts),\nextract the ZIP file, and place the `contracts` folder in the same directory where you run the pprof command.\n\nThen run the pprof command with the `-source_path` flag:\n\n```sh\npprof -source_path=contracts -http=:8081 profile.pprof\n```\n\nThe computation profile can be reset by sending a PUT request to the following URL:\nhttp://localhost:8080/emulator/computationProfile/reset.\n\n## Downloading all deployed contracts\n\nTo download all deployed contracts as a ZIP file, visit this URL: http://localhost:8080/emulator/allContracts\n\n## Running the emulator with Docker\n\nDocker builds for the emulator are automatically built and pushed to\n`gcr.io/flow-container-registry/emulator`, tagged by commit and semantic version. You can also build the image locally.\n\n```sh\ndocker run -p 3569:3569 -p 8080:8080 -e FLOW_HOST=0.0.0.0 gcr.io/flow-container-registry/emulator\n```\n\nThe full list of environment variables can be found [here](#configuration).\nYou can pass any environment variable by using `-e` docker flag and pass the valid value.\n\n*Custom Configuration Example:*\n\n```sh\ndocker run -p 3569:3569 -p 8080:8080 \\\n    -e FLOW_HOST=0.0.0.0 \\\n    -e FLOW_PORT=9001 \\\n    -e FLOW_VERBOSE=true \\\n    -e FLOW_SERVICEPRIVATEKEY=\u003chex-encoded key\u003e \\\n    gcr.io/flow-container-registry/emulator\n```\n\nTo generate a service key, use the `keys generate` command in the Flow CLI.\n\n```bash\nflow keys generate\n```\n\n## Emulating mainnet and testnet transactions\n\nThe emulator allows you to simulate the execution of transactions as if\nperformed on the Mainnet or Testnet. To activate this feature,\nyou must specify the network name for the chain ID flag and the RPC host\nto connect to.\n\n```sh\nflow emulator --fork-host access.mainnet.nodes.onflow.org:9000\nflow emulator --fork-host access.mainnet.nodes.onflow.org:9000 --fork-height 12345\n```\n\nPlease note, that the actual execution on the real network may differ depending on the exact state when the transaction\nis executed.\n\nBy default, the forked network will start from the latest sealed block when the emulator is started.\nYou can specify a different starting block height by using the `--fork-height` flag.\n\nYou can also store all of your changes and cached registers to a persistent db by using the `--persist` flag,\nalong with the other SQLite settings.\n\nTo submit transactions as a different account, you can use the `--skip-tx-validation` flag to disable the transaction\nsignature\nverification. Then submit transactions from any account using any valid private key.\n\n## Debugging\n\nTo debug any transactions sent via VSCode or Flow CLI, you can use the `debugger` pragma.\nThis will cause execution to pause at the debugger for any transaction or script which includes that pragma.\n\n```cadence\n#debugger()\n```\n\n## Development\n\nRead [contributing document](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonflow%2Fflow-emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonflow%2Fflow-emulator/lists"}