flow-rosetta-server

Flow Rosetta Server

Description

The Flow Rosetta Server implements the Rosetta Data API specifications for the Flow network. It uses the Flow DPS Server's GRPC API as the backend to query the required data. Flow core contract addresses are derived from the chain ID with which the service is started. This allows the Rosetta API to access state remotely, or locally by running the Flow DPS Server on the same host.

Testing

The Flow system model, where resources can be moved freely between accounts without generating events, makes it impossible to fully reconcile account balances on the Rosetta Data API. As a consequence, balance reconciliation has to be disabled when running the Rosetta CLI against the Flow Rosetta Server.

Additionally, some of the events generated by Flow are not accurately reflecting the account address they relate to. This is also due to the same resource-based smart contract programming model. For instance, when an account receives vaults from different locations to execute a swap of tokens, the events related to this swap might indicate the swap contract's address, as it uses volatile vaults.

Currently, the only way to work around this issue is to create exemptions for accounts which contain such smart contracts. As account balances using non-standard approaches to transfer Flow tokens can already not be reconciled, this is an acceptable limitation. In general, transactions by Rosetta should not be used to deduce account balances. Full historical account balance lookup is available and should thus be prefered to determine the account balance at any block height.

The discussed configuration is available in the flow.json and exemptions.json files for the mainnet-9 spork DPS. The following command can be executed to validate the Data API for that spork:

rosetta-cli check:data --configuration-file flow.json

Usage

Usage of flow-rosetta-server:
  -a, --api string              host URL for GRPC API endpoint (default "127.0.0.1:5005")
  -e, --cache uint              maximum cache size for register reads in bytes (default 1073741824)
  -l, --level string            log output level (default "info")
  -p, --port uint16             port to host Rosetta API on (default 8080)
  -t, --transaction-limit int   maximum amount of transactions to include in a block response (default 200)
      --smart-status-codes      enable smart non-500 HTTP status codes for Rosetta API errors

Example

The following command line starts the Flow DPS Rosetta server for a main network spork on port 8080. It uses a local instance of the Flow DPS Server for access to the execution state.

./flow-dps-rosetta -a "127.0.0.1:5005" -p 8080