Integrating Free Market with the Client SDK

This is a quick walkthrough of how to execute workflows using the Free Market Client SDK. The SDK is available as a NodeJS package, and can be installed using npm or yarn. The client SDK is compatible with both NodeJS and browser environments, but in this example we'll be using NodeJS to keep things simple.

Fist, create a new directory and initialize a new Typescript project:

mkdir fmp-client-example
cd fmp-client-example
npm init -y
npm install -D typescript
npx tsc --init

Next, install the Free Market Client SDK:

npm install -S @freemarket/client

Now we're ready to start writing some code. Create a new file called index.ts and add the following code:

import { Workflow, WorkflowInstance } from '@freemarket/client-sdk'

const main = async () => {

  // define a workflow
  const workflow: Workflow = {
    name: 'Sample Workflow',
    description: 'A simple workflow that wraps some ETH',
    steps: [
      {
        type: 'wrap-native',
        amount: '0.1',
        source: 'caller',
      },
    ],
  }

  // create an instance of the workflow
  const workflowInstance = new WorkflowInstance(workflow)
}

void main()

For simplicity, we've defined a 'hello world' style workflow that has a single step. It simply wraps a hard coded amount of ETH. The Workflow type the raw data structure for Free Market workflows. WorkflowInstance is a wrapper around Workflow that provides some additional functionality.

If you've been using Free Market Studio to author workflows, you can access the JSON representation of a workflow by clicking on the JSON tab in the workflow editor.

Next, we'll need to give workflowInstance a Web3 provider. The SDK supports any standard EIP 1193 compliant provider. In this sample we'll set it up using Ether.js. First install the dependencies:

npm install -S @ethersproject/providers @ethersproject/wallet @ethersproject/experimental

Then add the following code to your index.ts file below where we created workflowInstance:

  // set up a standard EIP 1193 compatible provider
  const ethersProvider = new JsonRpcProvider('http://localhost:8545')
  const wallet = Wallet.fromMnemonic('your mnemonic here').connect(ethersProvider)
  const standardProvider = new Eip1193Bridge(wallet, ethersProvider)
  
  workflowInstance.setProvider('start-chain', standardProvider)

The next thing we need is a WorkflowRunner that will actually handle the submission of the workflow to Free Market's on-chain workflow engine. Add the following code below where we set up the provider:

  // give the provider to the instance
  workflowInstance.setProvider('start-chain', standardProvider)

  // create a runner for the workflow instance
  const runner = await workflowInstance.getRunner(wallet.address)

  // add an event handler to print out progress messages
  runner.addEventHandler(event => console.log(event.message))

  // execute the workflow
  await runner.execute()

At this point your entire index.ts file should look like this:

import { Workflow, WorkflowInstance } from '@freemarket/client-sdk'

import { JsonRpcProvider } from '@ethersproject/providers'
import { Wallet } from '@ethersproject/wallet'
import { Eip1193Bridge } from '@ethersproject/experimental'

const main = async () => {
  // define a workflow
  const workflow: Workflow = {
    name: 'Sample Workflow',
    description: 'A simple workflow that wraps some ETH',
    steps: [
      {
        type: 'wrap-native',
        amount: '0.1',
        source: 'caller',
      },
    ],
  }

  // create an instance of the workflow
  const workflowInstance = new WorkflowInstance(workflow)

  // set up a standard EIP 1193 compatible provider
  const ethersProvider = new JsonRpcProvider('http://localhost:8545')
  const wallet = Wallet.fromMnemonic('your mnemonic here').connect(ethersProvider)
  const standardProvider = new Eip1193Bridge(wallet, ethersProvider)

  // give the provider to the instance
  workflowInstance.setProvider('start-chain', standardProvider)

  // create a runner for the workflow instance
  const runner = await workflowInstance.getRunner(wallet.address)

  // add an event handler to print out progress messages
  runner.addEventHandler(event => console.log(event.message))

  // execute the workflow
  await runner.execute()
}

void main()

Compile and run the code:

npx tsc
node index.js

You should see the following output:

Initializing
Submitting workflow to ethereum
Workflow submitted, waiting for confirmation
Workflow confirmed on ethereum
Workflow has completed successfully