@fairdatasociety/fdp-contracts-js

FDS Contracts JS Library

This library provides simple interface to interact with FDS contracts.

Installation

The library depends on the ethers.js library. So in order to use the library, ethers must be installed.

To install the both libraries:

npm install --save @fairdatasociety/fdp-contracts ethers

Usage

To work with local fdp-contracts docker image, execute the following command:

fdp-play start --detach --blockchain-image fairdatasociety/fdp-contracts-blockchain $BEE_VERSION

NOTE: it will spin up the whole fdp environment for you with running Bee clients

ENS

To interact with Ethereum Name Service (ENS), import and instantiate the ENS class. The ENS class can be configured with predefined configurations or with a custom one. Currently, the only predefined configuration is for the localhost envirnoment, which means it will use the swarm-test-blockchain image running locally on http://localhost:9545 address.

Predefined configurations can be fetched using the getEnsEnvironmentConfig function.

import { ENS, Environments, getEnsEnvironmentConfig } from '@fairdatasociety/fdp-contracts'

const ens = new ENS(getEnsEnvironmentConfig(Environments.LOCALHOST))

To use custom configuration, provide an instance of EnsEnvironment type, or modify some of the predefined configurations:

import { ENS, Environments, getEnsEnvironmentConfig, EnsEnvironment } from '@fairdatasociety/fdp-contracts'

const customConfig: EnsEnvironment = {
  ...getEnsEnvironmentConfig(Environments.LOCALHOST),
  rpcUrl: 'www.example.com',
}

const ens = new ENS(customConfig)

Here is an example how to interact with ENS:

import { ENS } from '@fairdatasociety/fdp-contracts'

async function example() {
  const ens = new ENS() // Default configuration is for localhost
  const username = 'example'

  const isUsernameAvailable = await ens.isUsernameAvailable(username)

  console.log(`Username ${username} is available: ${isUsernameAvailable}`)
}

For methods that require transactions, a signer must be provided. Signer can be specified when creating an object of the ENS class, or later by calling the connect method. Signer can be a hex string of a private key, or an ethers.js signer.

import { Wallet } from 'ethers'
import { ENS } from '@fairdatasociety/fdp-contracts'

async function example() {
  const ens = new ENS()
  const wallet = new Wallet('0x...', ens.provider)

  ens.connect(wallet)

  const address = await wallet.getAddress()
  const username = 'example'

  await ens.registerUsername(username, address, wallet.publicKey)

  console.log(`Username ${username} successfully registered.`)
}

dApp Registry

The DappRegistry class provides API to interact with the dApp registry smart contract.

import { DappRegistry, Environments, getDappRegistryEnvironmentConfig } from '@fairdatasociety/fdp-contracts'

const dappRegistry = new DappRegistry(getDappRegistryEnvironmentConfig(Environments.LOCALHOST))

Once when an instance is created, connect your signer:

dappRegistry.connect(signer)

Then all methods will be available to interact with the smart contract.

Ratings

The Ratings contract is available as a part of the DappRegistry class. So to interact with the contract, an instance of the DappRegistry class is needed:

const rating = await dappRegistry.getAverageRating(dappLocation)

Development

To compile the library in watch mode:

npm start

To build the library:

npm run build

Local installation

The library can be linked, so it can be imported as a node module from another local project. First, inside this directory run:

npm link

Then in root directory of another project, the library can be installed with:

npm link @fairdatasociety/fdp-contracts

Tests

To automatically start a fdp-contracts container, build the library and run tests:

./scripts/test.sh

Tests are separated into unit and integration tests to the test/unit and test/it directorties, respectively.

In order to run integration tests, a container with FDP contracts must be started first. Also the librarry should be built. Then, tests are executed using the command:

npm run test:integration

To run both tests at once:

npm test