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.
Go v1.16 or higher is required to compile flow-dps-rosetta.
Only Linux amd64 builds are supported, because of the dependency to the flow-go/crypto package.
In order to build the live binary, the following extra steps and dependencies are required:
Please note that the flow-go repository should be cloned in the same folder as the DPS with its default name, so that the Go module replace statement works as intended: replace github.com/onflow/flow-go/crypto => ./flow-go/crypto.
git clone git@github.com:onflow/flow-go.gitcd flow-go/cryptogit checkout v0.21.4go generate
You can then verify that the installation of the flow-go crypto package has been successful by running the tests of the project.
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.jsonUsage 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 errorsThe following command line starts the Flow 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-rosetta-server -a "127.0.0.1:5005" -p 8080The Rosetta API needs its own documentation because of the amount of components it has that interact with each other. The main reason for its complexity is that it needs to interact with the Flow Virtual Machine (FVM) and to translate between the Flow and Rosetta application domains.
This component, given a Cadence script, can execute it at any given height and return the value produced by the script.
The retriever uses the other components to retrieve account balances, blocks and transactions.
The script package produces Cadence scripts with the correct imports and storage paths, depending on the configured Flow chain ID.
The Validator component validates whether the given Rosetta identifiers are valid.