Harmony SDK - Upgrade

Name of Project / DAO / Company

harmony-sdk

Application type

Grant

Proposal overview

Whilst working on our previous grant harmony-marketplace-sdk, We encountered several problems trying to work with the existing harmony-sdk, mainly a lack of documentation, unclear APIs (especially when coming from ethers.js) and inconsistencies when interacting with the blockchain.

We received similar comments from members of the community, mentioned that the library is outdated and lacks proper testing and documentation.

What we propose is to work on an overhaul of the existing harmony-sdk, so that we can transition into a more familiar API when coming from ethers.js (which is the most used library to interact with EVM compatible blockchains). This will be a major version upgrade with several breaking changes.

Team

Our team has been contributing with different projects in blockchain for a few years, building APIs, SDKs and developer tools. Our goal is to continue to drive the crypto space forward by investing intellectual capital into projects, participating actively to help shape the ecosystems we believe in.

Jose Ramirez

Software Developer with 9 years’ experience in frontend / backend development. He considers himself a “perennial student”, and He stays in touch with the latest technologies. He is very passionate about decentralized finance and blockchain technologies. He built reliable software infrastructure with Node.js, Typescript and React. More recently working with Dapps using libraries like ethers.js, web3.js, and polkadot{.js}.

Brian Zuker

He is a passionate software engineer with 8 years of experience who loves challenges and learning new things. Worked closely with the Product and Design teams to develop new use cases for customers. Worked with technologies such as Node, React, OpenLayers, Python, RabbitMQ, Docker, Kubernetes, MongoDB

Fernando Sirni

He has 7 years of experience working in both back-end and front-end development. He loves teamwork and considers himself a proactive and reliable person. He has worked with technologies such as Node.js, Typescript, React, Docker and both SQL and NoSQL DBs. As the blockchain ecosystem is growing he is more interested in being an active part of it.

Damian Fixel

He is a software engineer with 6 years of experience working on Javascript, reactjs and nodejs. He worked both on big companies and small startups building reusable and scalable products. He has been around crypto since 2016.

About Blockcoders

Our team has been contributing to different projects in blockchain for a few years, building APIs, SDKs, and developer tools. Our goal is to continue to drive the crypto space forward by investing intellectual capital into projects, participating actively to help shape the ecosystems we believe in.

Blockcoders: blockcoders · GitHub
Jose Ramirez: jarcodallo (Jose) · GitHub
Brian Zuker: bzuker (Brian Zuker) · GitHub
Fer: fersirni (Fernando Sirni) - GitHub
Damian: damianfixel (Damian Fixel) - GitHub

Ecosystem Fit

Our target audience are developers that are used to using ethers.js and want an easy (and familiar) way to interact with the Harmony blockchain. This project is the starting point for developers, coming from other ecosystems like Ethereum or Polygon, and it aims to improve Dapps development on Harmony.

Proposal ask

Our proposal is to rework the existing SDK packages to transition them into a more familiar API, using the concepts and lessons learned from the ethers.js project.

We expect this work to take around 14-16 weeks to complete and our ask is 200,000 USD worth of ONE tokens. This would cover development and maintenance for at least 18 months.

Development Roadmap

We will describe a full roadmap of the work proposed here, with estimates:

Milestone 1

In this milestone, we will create a Harmony compatible JSON RPC Provider, that will extend the known json-rpc-provider from ethers.js.

This will include the functionality for the existing interface (where it makes sense) and all of the methods outlined in the existing SDK (Methods in blockchain and messenger).

When this milestone is completed, we will be able to query the Harmony blockchain using this provider.

  • Estimated duration: 2-3 weeks
  • Cost: 40,000 USD
Number Deliverable Specification
1. Provider Create the provider for Harmony to interact with the RPC.
1.b Testing Guide We will add unit tests to cover all basic logic and integration test with the RPC
2. Documentation Create documentation around the provider and how to use it

Milestone 2:

In this milestone we will create a Harmony compatible Signer (an instance of ethers.js Abstract Signer), which will be used to sign messages and transactions and send signed transactions to the Harmony Network, to execute state-changing operations. This will then be extended in Milestone 6 to support different wallets, such as ones using Private Keys, Seed, or HD.

When this milestone is completed, we will be able to sign messages and execute transactions.

  • Estimated duration: 2-3 weeks
  • Cost: 40,000 USD
Number Deliverable Specification
1 Harmony Signer Create an instance of HarmonyWallet, to enable state-changing operations
1.b Testing Guide We will add unit tests to cover all basic logic and integration tests
2 Documentation Create documentation for the HarmonyWallet and how to use it

Milestone 3:

In this milestone we will rework the harmony-contract package. We will support the same interface as ethers.js BaseContract. This will be an abstraction over Contracts deployed on the Harmony network. It will allow us to serialize calls and transactions to an on-chain contract and deserialize the result so that it can be used by developers.

When this milestone is completed, we will be able to interact with deployed contracts and listen to events

  • Estimated duration: 2-3 weeks
  • Cost: 40,000 USD
Number Deliverable Specification
1 Harmony Contracts Package Create an instance of HarmonyContract, to enable interaction with deployed contracts
1.b Testing Guide We will add unit tests to cover all basic logic and integration test with hrc20 and hrc721 contracts.
2 Documentation We will add documentation for interacting with Contracts using this package

Milestone 4:

In this milestone we will provide a collection of APIs to create accounts and wallets. These include HD wallets, Private Key wallets, and Mnemonic Seed wallets that will be used as an extension of the Signer, delivered in Milestone 2.

  • Estimated duration: 2-3 weeks
  • Cost: 30,000 USD
Number Deliverable Specification
1. Harmony Account package We will update the account package to encapsulate common operations related to accounts and wallets.
1.b Testing Guide We will add unit tests to cover all basic logic and integration tests
2 Documentation Document how to use the utility functions

Milestone 5:

In this milestone we will provide functions for dealing with staking. This will allow us to encapsulate the creation of Staking Transactions, validators, and methods to delegate, undelegate and collect rewards.

  • Estimated duration: 2-3 weeks
  • Cost: 30,000 USD
Number Deliverable Specification
1. Harmony Staking Package We will update the staking package to enable staking operations
1.b Testing Guide We will add unit tests to cover all basic logic and integration tests
2 Documentation Document how to use the staking functions

Milestone 6:

In this milestone we will provide utility functions for dealing with transactions, address management, encryption, unit conversion, and staking.

  • Estimated duration: 2-3 weeks
  • Cost: 30,000 USD
Number Deliverable Specification
1. Harmony Utils Package We will update a utils package to encapsulate common operations
1.b Testing Guide We will add unit tests to cover all basic logic and integration tests
2 Documentation Document how to use the utility functions

Milestone 7:

In this milestone we will publish a final release of all packages, finish polishing the documentation, fix any bugs and address feedback from Harmony’s community.

  • Estimated duration: 1-2 week
  • Cost: 20,000 USD
Number Deliverable Specification
1 Publish all packages Create a final release of all packages
2 Documentation Final polishes to documentation
3 License Add an MIT License
4 Fixes Fix reported bugs from pre-release.
5 Feedback Address feedback from the community

Metrics for success

The number of developers or dapps using the new version of harmony-sdk to interact with Harmony blockchain. This can be tracked based on Github stars + npm downloads.

External links

Github Twitter Linkedin Website

Thanks for your proposal, it has been assigned and the team will review and respond shortly :blue_heart:

Thanks for you reply. We are really excited to start with it :sunglasses:

For teams that are asking for this upgrade, please post here with the justifications on engineering time that’s reduced, thanks to the utility of the SDK

Meanwhile, for the current marketplace SDK, we haven’t seen a lot of fork activities. Which teams are currently onboarded with the SDK, and how many downloads are there thus far?

1 Like

The developers who experienced the issues with this library may have already switched to some alternatives. Can you identify some clear benefits of using the SDK compared to the alternatives? For example, I can think of: much smaller bundle size (how much?), being able to parse and execute Harmony specific transactions (staking, and what else). There may be more.

What other apps are using this library as a dependency?

1 Like

Hi @aaronqli,

Thank you for your reply and feedback. So far, we haven’t found many alternatives to the current SDK. As outlined in our proposal, the current SDK has several opened issues without response, does not have proper documentation and the APIs are unclear (specially when coming from a familiar Etherjs SDK).

The main benefit we see is lowering the barrier of entry for new and existing devs, by providing interfaces that are used across many other projects, favoring the portability of projects into the Harmony ecosystem.

Also, since we will be breaking packages further, there will be an impact in bundle size (we’ll show the difference once we work further on the project).

The new implementation will handle Harmony specific use cases, as detailed in the grant proposal.
SDKs, we believe, are crucial for adoption of a determined protocol, since it provides a standardized way to interact with the blockchain and makes it easier to onboard projects.

We took the initiative to do a MVP of the first Milestone for the @harmony-js/providers. This is currently under development and we expect to deliver the first beta version this week.

Another point to take in consideration is that the author of harmony-sdk is not longer maintain this library. Part of our proposal is provide maintenance for at least 18 months and handle every new feature or issue.

cc: @Jacksteroo @giv

We will keep your team in mind. For the time being, we’re kicking off a Developer Growth team and will be reviewing our SDK offerings and circle back if we’d like to assign the work in this form going forward.