search

zenodeapp / pairwise-alignments

Solidity implementations of well-known pairwise alignment methods such as Needleman-Wunsch's global sequence alignment and the Smith-Waterman local sequence alignment algorithm.
MIT License
3 stars 2 forks source link
algorithm alignment amino-acids contracts dna needleman-wunsch nucleotides proteins smith-waterman solidity substitution-matrices

readme

Pairwise Alignments

Solidity implementations of well-known pairwise alignment methods such as Needleman-Wunsch's global sequence alignment and the Smith-Waterman local sequence alignment algorithm.

This has been built by ZENODE within the Hardhat environment and is licensed under the MIT-license (see LICENSE.md).

A fully functioning dApp can be found here: https://pairwize.zenode.app.

Overview

Dependencies

Features

Algorithms

Hardhat

Getting Started

TL;DR

0. Clone --use the --recursive flag.

git clone --recursive https://github.com/zenodeapp/pairwise-alignments.git <destination_folder>

1. Installation --use npm, yarn or any other package manager.

npm install
yarn install

2. Run the test node --do this in a separate terminal!

npx hardhat node

3. Substitution Matrices (Intermezzo) --skip if you've already deployed the SubstitutionMatrices-contract!

cd submodules/substitution-matrices
// Follow step 1 to 5, excluding step 2, in the TL;DR of submodules/substitution-matrices/README.md
cd ../..

4. Pre-configuration --add the SubstitutionMatrices address to zenode.config.js.

  contracts: {
    needlemanWunsch: {
      name: "NeedlemanWunsch",
      address: "",
      parameters: {
        _matricesAddress: "ADD_SUBSTITUTION_MATRICES_ADDRESS_HERE",
      },
    },
    ...
  }

Repeat for any other algorithm you wish to deploy.

5. Deployment

npx hardhat run scripts/deployment/needlemanWunsch.js
npx hardhat run scripts/deployment/smithWaterman.js

Only deploy the one(s) you pre-configured, see scripts/deployment for all possible algorithms.

6. Configuration --add the algorithm's contract address to zenode.config.js.

  contracts: {
    needlemanWunsch: {
      name: "NeedlemanWunsch",
      address: "ADD_NW_ALGORITHM_ADDRESS_HERE",
      ...
    },
    ...
  },

Repeat for any other algorithm you deployed.

7. Interaction --use the scripts provided in the Interaction phase.

0. Clone

To get started, clone the repository with the --recursive flag:

git clone --recursive https://github.com/zenodeapp/pairwise-alignments.git <destination_folder>

This repository includes submodules and should thus contain the --recursive flag.


If you've already downloaded, forked or cloned this repository without including the --recursive flag, then run this command from the root folder:

git submodule update --init --recursive

Read more on how to work with submodules in the zenode-contracts repository.

1. Installation

Install all dependencies using a package manager of your choosing:

npm install
yarn install

2. Configure and run your (test) node

After having installed all dependencies, use:

npx hardhat node

Make sure to do this in a separate terminal!


This will create a test environment where we can deploy our contract(s) to. By default, this repository is configured to Hardhat's local test node, but can be changed in the hardhat.config.js file. For more information on how to do this, see Hardhat's documentation.

3. Substitution Matrices (Intermezzo)

This step can be skipped if you've already deployed and populated a SubstitutionMatrices-contract.

Our alignment contracts depend on the SubstitutionMatrices-contract as it's required for calculating alignment scores. Thus, before continuing, we'll first have to deploy and populate a SubstitutionMatrices-contract.

  1. cd into the submodule's folder:

    cd submodules/substitution-matrices

  2. Now, head over to the README.md file found in the submodules/substitution-matrices folder and continue from step 1 to 5 (exclude step 2).

    TIP: follow the TL;DR for a quick setup!

    CAUTION: be sure to remain inside the submodule's folder while following the guideline!

  3. Once you've got the SubstitutionMatrices-contract set up, cd back into the pairwise-alignments' root folder:

    cd ../..

4. Pre-configuration

Before we can deploy any alignment algorithm, it's necessary to state which matrices' contract we'll use.

To do this, open the zenode.config.js file and add the SubstitutionMatrices address (from 3. Substitution Matrices) to parameters._matricesAddress:

  contracts: {
    needlemanWunsch: {
      name: "NeedlemanWunsch",
      address: "",
      parameters: {
        _matricesAddress: "ADD_SUBSTITUTION_MATRICES_ADDRESS_HERE",
      },
    },
    ...
  }

Repeat this step for any other algorithm you would like to deploy.

5. Deployment

Now that we've pre-configured zenode.config.js, we can deploy our algorithm(s) using:

Needleman-Wunsch

npx hardhat run scripts/deployment/needlemanWunsch.js

Smith-Waterman

npx hardhat run scripts/deployment/smithWaterman.js

Only deploy the one(s) you pre-configured, see the scripts/deployment folder for all possible algorithms.

6. Configuration

Now head back to zenode.config.js and add the addresses for all the algorithms we deployed to the contracts object; so it knows which contracts it's supposed to interact with.

  contracts: {
    needlemanWunsch: {
      name: "NeedlemanWunsch",
      address: "ADD_NW_ALGORITHM_ADDRESS_HERE",
      ...
    },
    ...
  },

Same as before; repeat for any other algorithm you've deployed.

7. Interaction

We're all set!


Here are a few Hardhat tasks (written in hardhat.config.js) to test our contracts with:

Appendix

A. zenode.config.js

This is where most of the personalization for contract deployment takes place.

In the case of the pairwise-alignments repository this includes:

Credits

Sources of inspiration


— ZEN

Copyright (c) 2022 ZENODE