@melonproject/melon.js

Melon.js

A convenient Javascript interface to the Melon protocol Ethereum smart contracts.

Principles

• Functional programming:
  • Types with Flow-Type
  • Composition over inheritance
  • TODO: Do not throw exceptions. Use railways instead.
• Abstract token decimals problem: This library consumes and returns always quantities as a BigNumber with decimals included. I.e. "12.23" and not "1200000000000" (number of 0s depending on the token decimals)
• Abstract token address problem: Always consume and return tokens in their symbol name instead of address.
• Return standard JS object wherever possible. For example: Timestamps are Date objects. Ids are numbers (no need for bignumber), ...

Usage

To use melon.js, you need to set it up with a Parity provider (either local or hosted node). Below is an example of how to setup Melon.js inside the saga of a React application.

Setting up Melon.js

Be sure that the following lines are executed before any other usage of melon.js

import {
  getParityProvider,
  providers,
  setEnvironment,
  getEnvironment,
} from '@melonproject/melon.js';

function* yourSaga() {
  const { providerType, api } = yield call(getParityProvider);

  setEnvironment({ api, providerType });

  if (providerType !== providers.INJECTED) {
    // you are using the ethers-wallet signer (in-browser strategy)
  } else {
    // you are using an external signer, such as the Parity signer or an unlocked node
  }
  // you then need to add your wallet address on the account key of the environment object
  setEnvironment({ account: { address: 'YOUR_WALLET_ADDRESS' } });
}

Calling functions in Melon.js

All the functions that interact with the blockchain (read or write) follow the same pattern. You need to pass in the environment object (as set up above) as the first argument, and the arguments to the smart contract function as a second argument in an object. Below is an example of calling the setupFund function in the saga of a React application.

import {
  setupFund,
  getEnvironment,
} from "@melonproject/melon.js";


function* yourSaga() {
  const environment = getEnvironment();
  const fund = yield call(setupFund, environment, { name, signature });
}

Worth noting: If you are trying to perform a transaction and are using the Ethers-wallet signer, you need to add the decrypted version of your wallet instance to the environment object before passing the environment object as the first argument of your function. In the above example, you would do the following before callibg setupFund:

const decryptedWallet = yield call(decryptWallet, wallet, password);
environment.account = decryptedWallet;

Link dev build

To use the latest version of melon.js and to further develop it in place, it can be linked:

git clone [e-mail]:melonproject/melon.js.git
cd melon.js
yarn install
yarn build
yarn link
cd ../portal
yarn link @melonproject/melon.js

If you make changes to the source files (in lib/ folder), you need to build it again before they are usable in the dependent project:

yarn build

Folder structure

The folder structure is based on the structure of the protocol contract. That said, the melon.js has a different goal: Making interaction with the protocol as developer friendly as possible. Whereas the protocol needs to be efficient on the blockchain and secure.

/

The shape of this repository is inspired by this blogpost. On the root level, there are the common configuration files like package.json, .eslintrc, ...

And three important folders:

• lib/: The ES6/7 source code
• build/: The transpiled ES5 code (ignored in git)
• test/: Integration tests, unit tests, mocks, common fixtures and package wide test helpers
• docs/: Autogenerated docs with esdoc. (TODO)

lib/

This is probably the most interesting folder. Here is the actual code. The structure mirrors the protocol contract (i.e. assets/, exchange/, ...), adding only utils/ for common utility functions.

lib/[contract]

Each of these contract folders can have the following subfolders:

• calls/: Actual interactions with the blockchain free of gas. So called constant-methods.
• transactions/: Actual interactions with the blockchain that cost gase. So called non-constant-methods.
• events/: Watch & get events
• contracts/: Helpers to get instances of the deployed contracts. Meant for internal use.
• utils/: Utility functions to interact with the data
• schemas/: Flow types (and hopefully in the future, Type Script definitions and GraphQL schemas)
• queries/: Sort and filter functions to insert into JS own .sort(fn), .filter(fn).

Note: Some calls & transactions are more or less a simple JS-wrapper on the contract, where others do more complex stuff and even combine multiple calls to the contracts. But you can be certain: Calls are free.

testing

By interacting with the smart contracts, we have 2 levels of testing:

• tests/integration/ Jasemine Integration tests: Interact with real smart contracts. Be careful with those: They connect to a real unlocked node that you need to set up (see below).
• tests/shared/ Shared expectations. Since Jest & Jasemine have very similar syntax, some test-expectations (expect(asdf).to...) can be isolated in separate functions and shared.

Configure integration tests to use your address

To run the integration tests, you can:

• Use the encrypted json file of the wallet you want to use. Include in your directory an encryptedWallet.json file and a password.json file. They will be used to instantiate a wallet/custom signer, which will then be used to sign integration tests transactions. [!] Do not commit any of those files to git. For the password.json file, below is the expected format:

{ "kovan": "YOUR_KOVAN_WALLET_PASSWORD", "live": "YOUR_MAINNET_WALLET_PASSWORD" }

• Instantiate your integration test wallet using the function importWalletFromMnemonic("your mnemonic phrase"). Include in your directory a mnemonicWallets.json file (not commited to git). { "mnemonic-kovan": "YOUR_KOVAN_MNEMONIC", "mnemonic-live": "YOUR_MAINNET_MNEMONIC" }

• Run an unlocked node (see instructions below).

Set up unlocked parity account

• run parity account new --chain kovan
• Type a password; don't forget to store that password carefully, along with the generated account address.
• Create a new file called "account" and paste the password in.
• In the same folder, create a file called "run.sh". Copy and paste the following command in this file, and replace accordingly with your account address.

parity --chain kovan --author YOURACCOUNTADDRESS --unlock YOURACCOUNTADDRESS --password ./account --auto-update=all --geth --force-ui

• Back to the terminal, make this new file executable by running: chmod 755 run.sh