CI for Hedera based projects

When creating a project on the Hedera network, you want to avoid running your tests in the live public Hedera network, the so-called Mainnet. While Hedera is one of the most cost-effective networks regarding transaction fees, there is still a cost associated with each transaction. And while that price is really low, you want to avoid paying those fees during the initial project development stages as the fees can add up. For that use case, a simple solution is to use the Hedera Testnet, a parallel-running Hedera network that can be used to test Hedera, its functionality, and applications built on top of it. Next to the already mentioned Mainnet and Testnet Hedera runs a 3rd network, the Previewnet, that always runs on the next possible release version of Hedera.

Using the Hedera Testnet

The significant benefit of the Hedera Testnet regarding testing a product’s functionality is that a user receives 1000 HBAR daily to run transactions against the Hedera Testnet. This gives a user enough resources to run a huge number of transactions against Testnet, but not a single user can block the complete network by endless tests or nearly infinitely running smart contracts since you can only use 1000 HBAR per day.

To receive access to Testnet and get the 1,000 HBAR for testing, a user only needs to create an account at the Hedera Developer Portal, which contains all the information needed to run any application against Testnet.

To change dynamically between Testnet and Mainnet (and even Previewnet) the connection information can be stored in an environment and, for example, provided as a .env file:

HEDERA_NETWORK=testnet
HEDERA_ACCOUNT_ID=0.0.44535
HEDERA_PRIVATE_KEY=302e020100300506032b6570042204206da2428813c…

This workflow allows developers to quickly run tests from a local machine against Hedera Testnet. That solution is really helpful for triggering tests for a small project on the local developer machine.

Let’s assume you use Hedera in a big enterprise project developed by several teams. Here, a solid continuous integration (CI) pipeline and automatic tests are a must. Let’s assume you use GitHub Actions for your CI pipeline. In that case, you could store the Hedera Testnet account information as secrets in GitHub and use that account for all automated tests. The more your project grows the more tests you want to have and if all those tests interact with Hedera and are executed by every commit you can run out of the maximum of 1,000 HBAR that can be spent on Testnet. While the use of Testnet is excellent for manual tests on your machine, it is not made for a CI-based scenario. Happily, Hedera is a public ledger created with support for big enterprises in mind and provides a good solution for CI integration and automatic tests.

Introducing Solo

Hedera Solo is a command-line interface (CLI) tool that helps you set up a custom Hedera network. This tooling is especially useful for creating a temporary network for tests. Solo is not defined to create a custom production-ready network. The CLI should help you set up a temporary network that can be used to test your applications. Since the network is fully compatible with any “official” Hedera network like Mainnet or Testnet, we can even use our environment-based approach to connect to a network created by Solo.

Solo is provided by NPM and can easily be installed. You only need a node installation on your system:

$ npm install -g @hashgraph/solo

Instead of using the Hedera Developer Portal to receive a user account, the Solo CLI provides the functionality to create a new user:

$ solo account create

Solo even provides a command to update a user’s HBAR amount. The following command provides 10,000,000 HBAR to the account defined by the environment variable HEDERA_ACCOUNT_ID:

$ solo account update --account-id $HEDERA_ACCOUNT_ID --hbar-amount 10000000

As you can see, Solo provides the flexibility needed to define an infrastructure that can be used for even massive projects with thousands of tests. Hedera, in doing so, provides everything necessary to create solid and secure enterprise-grade applications on top of the public ledger. Like all other components of Hedera, Solo is fully open-source.

Using Solo CLI alone and creating a custom CI pipeline is a perfect fit for a use project. However, if you just want to create a small application or an open-source library on top of Hedera, the effort of such a setup might still be high. Here, the community is currently providing a handy solution as an open-source component.

Solo GitHub Action

Open Elements provides an open-source GitHub action to automatically run any GitHub action workflow against a network created by Solo.

The Action can be integrated into any GitHub Action workflow and automatically creates an account with 10,000,000 HBAR that can be used. The needed information to access the network and the account is provided as output variables in GitHub Action. By doing so, a simple workflow that does nothing but only prints the information of the created user account can look like this:

- name: Setup Hedera Solo
  uses: OpenElements/hedera-solo-action@v0.1
  id: solo

- name: Use Hedera Solo
  run: |
    echo "Account ID: ${{ steps.solo.outputs.accountId }}"
    echo "Private Key: ${{ steps.solo.outputs.privateKey }}"
    echo "Public Key: ${{ steps.solo.outputs.publicKey }}"

A workflow that builds and tests software is as simple as the given example. The following action workflow description comes from a real Java-based project (see the entire file here) that runs all tests against a temporary network after every commit:

 - name: Setup Hedera Solo
      id: solo
      uses: OpenElements/hedera-solo-action@v0.1

    - name: Build with Maven
      env:
        HEDERA_ACCOUNT_ID: ${{ steps.solo.outputs.accountId }}
        HEDERA_PRIVATE_KEY: ${{ steps.solo.outputs.privateKey }}
      run: ./mvnw verify

With the given GitHub action, which is free and available at the GitHub marketplace and can be integrated into every GitHub action workflow, every project can easily run automatic tests against a network.

Next Steps

The project is currently released in version 0.1 and will evolve. As a next step, support for the Hedera mirror node will be added to access the mirror node API for the custom network in tests. In addition, it is planned to make the action’s usage more configurable. Since the action is still in an early state, any feedback from the community will be very welcome. Once we know more about the community’s needs regarding such action, it could be possible to maybe even get an official Hedera Solo action in the future.