Harmony's Rosetta Data & Construction API

Hi there! :wave:

We would like to share our initial implementation of the Rosetta Data & Construction API on the Harmony network.

What is Harmony?

Harmony is a sharded Proof of Stake blockchain that is EVM compatible. Learn more about us at https://harmony.one/.

Our implementation

Our Data API implementation reports all of our native token transfers & staking operations as well as all of our early internal quirks that came about during our phased mainnet release. Moreover, our Data API supports basic smart contract functionalities (such as logs, execution status, contract data, etc…) so that future tools (like a contract specific rosetta module) can be more easily built out on top of this core implementation.

Our Construction API implementation takes care of all native token transfers (cross-shard and same-shard transfer) as well as contract creation. However, we have chosen to skip the staking transaction constructions (for now) as the Rosetta spec/SDK does not support the BLS signature type (yet :crossed_fingers:) and we are unable to correctly express the intent of some of our staking operations.


We have documented our implementation in detail at https://api.hmny.io/.

The documentation was done through a Postman collection so you can easily run some sample queries and play with our implementation.


We have done most of our extensive testing using the rosetta-cli and have integrated the Construction and Data API checks in our CI pipeline. Here are the rosetta-cli configs for those who are interested: beacon shard config & aux shard config.

Node Deployment

The simplest way to run a Rosetta (offline & online) endpoint for Harmony is to run a Harmony explorer node via Docker.

You can download docker here.

Building the Docker Image

The docker file can be found in our core repo here. You can simply curl the docker file and build it with the following commands:

$ curl -O https://raw.githubusercontent.com/harmony-one/harmony/main/rosetta/infra/Dockerfile
$ docker build -t harmonyone/explorer-node . 

Pulling the Docker Image

If you wish, you can pull the docker image from docker hub with the following command:

$ docker pull harmonyone/explorer-node:latest

This image will be updated at every release of the Harmony node.

Running the node

To start the node with a shared data directory (say ./data) on shard 0, you can run the following command:

$ docker run -d -p 9700:9700 -p 9800:9800 -p 9500:9500 -v "$(pwd)/data:/root/data" harmonyone/explorer-node --run.shard=0 --http --ws

You can verify that the node is running with the following curl command:

$ curl --location --request POST 'http://localhost:9700/network/list' \
--data-raw '{
"metadata": {}

More documentation on running an explorer node with docker can be found here.

Future Plans

As this is our initial implementation, we plan to improve various things surrounding it in the future. Some of them are:

  • SDK integration.
  • Middleware Rosetta implementation to have 1 endpoint for all shards.
  • Implementation of the /call endpoint to support future Rosetta modules.
  • Staking transaction construction.


The tooling and community have made implementing the Rosetta spec a relatively painless experience for us and we only see it getting better in the future!

We welcome any thoughts or feedback on our implementation so feel free to let us know in this thread or as an issue here.



Welcome to the community, Harmony!

#ONE @coinbase @CoinbasePro @CoinbaseCustody Harmony. Will it be listed?