Harmoniq CLI

About

Harmoniq CLI is a powerful command-line interface for the Harmoniq protocol. It allows developers to interact with the Harmoniq API - build, configure and execute automated workflows. More details about Harmoniq can be found at harmoniqprotocol.xyz.

Setup

Install dependencies with

npm install

Configure

cp .env.sample .env

1. Connect to the Harmoniq API on api.harmoniqprotocol.xyz or run the engine locally. Update the BASE_API_URL in the .env file with the URL to the engine API.

2. Acquire the JWT token for the API and set it in the .env file.

Getting Started

Now let's create and run our first automated workflow. As an example we will choose a periodic transfer workflow from the samples.

Create Workflow

The workfows are defined in a yaml files. Here's an example of a samples/transfer.workflow.yaml workflow:

- name: scheduled_transfer
  version: 0.0.1
  wallet: $WORKFLOW_WALLET
  steps:
    - name: transfer
      contract: Token
      network: $WORKFLOW_NETWORK
      method: transfer
      arguments:
        - to: $RECEIVER_ADDRESS
        - amount: $PERIODIC_TRANSFER_AMOUNT
      trigger:
          name: daily_schedule
          type: periodic
          interval: minute
  contracts:
    - name: Token
      address: $TOKEN_ADDRESS
      abi: SOL.abi
      network: $WORKFLOW_NETWORK

Studying the file we can see that it's a one step workflow, that will transfer an amount of tokens to a receiver address every day. It contains the following atributes:

• name: the name of the workflow

• version: the version of the workflow

• wallet: the wallet that will be used to execute the workflow. In this case a local wallet.

• steps: the steps that the workflow will execute. In this case a transfer step.

• trigger: the trigger that will start the workflow. In this case a periodic trigger that will start the workflow every day.

• contracts: the contracts that the workflow will use. In this case a contract named Token.

Take a look into workflow arguments, they are the variables that the workflow will use. We will confiuge them in the next step. Now it's time to create the workflow:

./harmoniq workflows create ./samples/transfer.workflow.yaml
WORKFLOW_ID= #put here the received workflow id

As an response you will receive the workflow id, store it in env variable for future use.

Configure Workflow

Circling back to workflow arguments, those are the variables that the workflow will use:

• WORKFLOW_WALLET: the address of the wallet that will be used to execute the workflow.

• TOKEN_ADDRESS: the address of the token that will be used to transfer.

• RECEIVER_ADDRESS: the address of the receiver that will receive the tokens.

• PERIODIC_TRANSFER_AMOUNT: the amount of tokens that will be transferred.

Wallet creation

Workflows can use local or external wallets, in this case we will create a local wallet. The local wallets are created by the harmoniq engine, they are good for on-premise mode and testing.

We can create a wallet with the following command:

./harmoniq wallets create
WORKFLOW_WALLET= #put here the received wallet address 

The transfer wallet also needs a receiver address, we can use any wallet address for this. For this tutorial we will create a new wallet with Harmoniq CLI:

./harmoniq wallets create
RECEIVER_ADDRESS= #put here the received wallet address 

Now we need to get the token address, we will use the USDC token address on sepolia network.

TOKEN_ADDRESS=2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv

Workflow Instance creation

Now to finish the workflow configuration, we need to create a workflow instance. Workflow instance is the workflow adapted to user's use case. This is the command to create a workflow instance:

./harmoniq instances create $WORKFLOW_ID  -p "{\"WORKFLOW_WALLET\": \"$WORKFLOW_WALLET\", \"RECEIVER_ADDRESS\": \"$RECEIVER_ADDRESS\", \"TOKEN_ADDRESS\": \"$TOKEN_ADDRESS\", \"PERIODIC_TRANSFER_AMOUNT\": \"100000\", \"WORKFLOW_NETWORK\": \"sepolia\"}"
WORKFLOW_INSTANCE_ID= #store here the received workflow instance id

Upload the ABIs used

Now if you use run the service locally, you need to upload the ABIs used by the workflow.

 ./harmoniq abi upload sol.abi  ./abis/sol.abi.json

Start the workflow

For workflow to function properly, we need SOL and USDC. After we acquire the funds, we can start the workflow instance:

./harmoniq instances start $WORKFLOW_INSTANCE_ID

Validate the instance status:

./harmoniq instances status running