Ensemble CLI

About

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

Setup

Install dependencies with

npm install

Configure

cp .env.sample .env

1. Connect to the Ensemble API on api.ensemble.codes 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: erc20.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:

./ensemble 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 ensemble engine, they are good for on-premise mode and testing.

We can create a wallet with the following command:

./ensemble 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 Ensemble CLI:

./ensemble 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=0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238

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:

./ensemble 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.

 ./ensemble abi upload erc20.abi  ./abis/erc20.abi.json

Start the workflow

For workflow to function properly, we need Sepolia ETH and USDC. For this example we will use the faucet of the sepolia network. For USDC we can use sepolia USDC faucet.

After we acquire the funds, we can start the workflow instance:

./ensemble instances start $WORKFLOW_INSTANCE_ID

Validate the instance status:

./ensemble instances status running

More Examples

Read our manuals to get more examples and cheatsheets about working with Ensemble workflows.

• DCA
• Transfer